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.

Standard deal fields

The response elements of contactIds are numbers (number[]): OpenAPI describes them as number, while this endpoint and fieldsDetailed in /v1/guide publish readItemSchema: { "type": "number" }. The field remains read-only; values and their order do not change.

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 returns the opposite set of records; for hasProducts, it matches no records. Filter by stageSemanticId for deal stages; there is no alternative filter for product presence. 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.

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" }] }
    },
    "relations": {
      "contact": { "type": "many", "entity": "contacts", "operations": ["list", "add", "remove", "set", "clear"] },
      "company": { "type": "one", "entity": "companies", "includable": true }
    },
    "activities": { "operations": ["list", "create"], "types": ["call", "meeting", "email", "task"] },
    "actions": {
      "move": { "description": "Change deal stage", "method": "POST", "path": "/v1/deals/{id}/move", "params": { "stageId": { "type": "string", "required": true }, "categoryId": { "type": "string", "required": false } } }
    },
    "aggregatable": ["amount", "stageId", "stageSemanticId", "categoryId", "assignedById", "sourceId"],
    "batch": ["create", "update", "delete"],
    "import": { "method": "POST", "path": "/v1/deals/import", "maxItems": 100 },
    "include": ["contact", "company"]
  }
}

Four fields from data.fields are shown, along with the other data keys. The data.products block is omitted from the example, and the full set of fields is in the tables above.

What to do with the names from data.include is covered on the Get deal page. More about the include parameter — Related data.

Error response example

403 — the key lacks the crm scope:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope",
    "hint": "This request needs the 'crm' scope, which the calling key does not carry. Add 'crm' to this key in the developer cabinet (or through the management API), then repeat the call.",
    "cause": "key_scope_missing",
    "requiredScope": "crm",
    "keyScopes": ["task", "im"],
    "fix": { "action": "edit_key_scopes", "via": "cabinet" },
    "userMessage": "The app's API key lacks the “CRM” permission. You can add it in the key settings in the developer cabinet."
  }
}

Errors

For the full list of common API errors, see Errors.

See also

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