Deal fields

GET /v1/deals/fields

Returns the full list of available fields, including user fields (ufCrm*).

Examples

curl — personal key

curl "https://vibecode.bitrix24.com/v1/deals/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl "https://vibecode.bitrix24.com/v1/deals/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/deals/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/deals/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

The label and description field captions are returned in English, while the ones the platform takes straight from the Bitrix24 account come in the account language. Request headers do not switch the language. Enum values carry an English label.

The seven fields above — leadId, quoteId, taxValue, originId, originatorId, additionalInfo and lastActivityBy — are accepted in filter and in sorting, including in GET /v1/deals, POST /v1/deals/search and POST /v1/deals/aggregate. Five of them (leadId, quoteId, originId, originatorId, additionalInfo) may arrive as null, and for the three string fields an empty string from Bitrix24 is normalized to null — compare against an empty value, not against "".

The six computed fields — isWon, isLose, isWork, hasProducts, receivedAmount, lostAmount — are calculated by Bitrix24 only for a list, a search or the list action of the global batch POST /v1/batch whose select names the field explicitly and without * (GET /v1/deals?select=id,isWon,receivedAmount, POST /v1/deals/search with select). A single GET /v1/deals/{id}, a list without select and the list action of the entity batch (its select is a projection, not forwarded to Bitrix24) return null for them — that is «not requested», not «empty». All six are read-only: a sent value is rejected (create and update — 400 READONLY_FIELD, import — 400 IMPORT_ITEM_VALIDATION, entity batch — 400 BATCH_ITEM_VALIDATION, global batch — READONLY_FIELD under the call). The four flags are not accepted in filter (400 UNKNOWN_FILTER_FIELD): a boolean filter travels to Bitrix24 as Y/N, while Bitrix24 matches these flags only against a boolean value — for the three stage flags the string Y answers the inverted set, for hasProducts it matches no record; filter on stageSemanticId for the stage, there is no substitute for the products. Sorting by all six works; receivedAmount and lostAmount are also accepted in sum/avg/min/max of POST /v1/deals/aggregate — the result is in the account's accounting currency, unlike sum(amount), which adds deal amounts in their own currencies as they are.

The UTM fields (utmSource, utmMedium, utmCampaign, utmContent, utmTerm) are returned on reads but accepted neither in filter nor in sorting. Such a request is rejected with 400 UNKNOWN_FILTER_FIELD or 400 UNKNOWN_SORT_FIELD before Bitrix24 is called, and the reason for each field arrives in its description in this same endpoint's response. For contacts, filter by contactId (the primary contact) or by contactIds (any linked contact).

User fields (ufCrm*) are also returned in responses and accepted on create/update. For an enumeration field, this endpoint returns an array of options at data.fields.<field name>.items, shaped as { "ID": "3983", "VALUE": "warm" }. This is not the enum key of declared fields with value and label elements: to write to a user field, send the ID, while VALUE is the option label for display. A label sent instead of the identifier is lost without an error. Details — Value format by type.

Available includes

The GET /v1/deals/fields endpoint returns the list of available includes: contact, company.

Usage example: Get deals.

More on includes: Related data.

Response example

{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Unique numeric identifier of the deal." },
      "title": { "type": "string", "readonly": false, "label": "Title", "description": "Deal title." },
      "assignedById": { "type": "number", "readonly": false, "label": "Assignee", "description": "ID of the responsible user. List: GET /v1/users." },
      "stageSemanticId": { "type": "string", "readonly": true, "label": "Stage semantics", "description": "Semantic category of the current stage — codes are decoded in enum.", "enum": [{ "value": "P", "label": "In progress" }, { "value": "S", "label": "Success" }, { "value": "F", "label": "Failure" }] }
    },
    "batch": ["create", "update", "delete"]
  }
}

Only 3 of the many fields are shown. The full list is in the table above.

Errors

Full list of common API errors — Errors.

See also

• Create deal
• User fields
• Entity API
• Limits and optimization