For AI agents: markdown of this page — /docs-content-en/entities/statuses/fields.md documentation index — /llms.txt

Dictionary fields

GET /v1/statuses/fields

Returns a description of all entity fields with their types and attributes.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses/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. Request headers do not switch the language.

Field Type RO Description
id number yes Record ID
entityId string Dictionary type (DEAL_STAGE, SOURCE, etc.)
statusId string Symbolic code of the value
name string Name
nameInit string/null Original name
sort number Sort order
color string/null Color in HEX with a leading #
semantics string/null Semantics: S — success, F — failure. null — an in-progress stage or a dictionary without semantics
system boolean yes System value that cannot be changed or deleted
categoryId number/null Pipeline ID. Set for dictionaries of the form DEAL_STAGE_N, otherwise 0 or null
extra object yes Additional data for dictionaries with stages — STATUS, DEAL_STAGE, DEAL_STAGE_N, QUOTE_STATUS. Nested keys SEMANTICS and COLOR. Other dictionaries do not have this field

Response example

GET /v1/statuses/fields returns field descriptions under the data.fields key (names are camelCase, as in API responses), where each field is { type, readonly, label, description }. All eleven fields carry a label, including the service field extra. Plus data.batch with the list of available batch operations.

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Unique numeric identifier of the reference-book entry." },
      "entityId": { "type": "string", "readonly": false, "label": "Reference type", "description": "Reference-book type this entry belongs to (e.g. DEAL_STAGE, SOURCE, STATUS)." },
      "statusId": { "type": "string", "readonly": false, "label": "Status code", "description": "Symbolic code of the value within its reference book." },
      "name": { "type": "string", "readonly": false, "label": "Name", "description": "Display name of the entry." },
      "nameInit": { "type": "string", "readonly": false, "label": "Initial name", "description": "Original name assigned when the entry was created." },
      "sort": { "type": "number", "readonly": false, "label": "Sort", "description": "Sort order within the reference book." },
      "color": { "type": "string", "readonly": false, "label": "Color", "description": "HEX color of the value." },
      "semantics": { "type": "string", "readonly": false, "label": "Semantics", "description": "Stage semantics: S — success, F — failure, null — in progress or no semantics." },
      "system": { "type": "boolean", "readonly": true, "label": "System", "description": "System value that cannot be changed or deleted." },
      "categoryId": { "type": "number", "readonly": false, "label": "Pipeline ID", "description": "Pipeline ID for entityId values of the DEAL_STAGE_N form." },
      "extra": { "type": "object", "readonly": true, "label": "Extra data", "description": "Additional data of stage directories — an object with the nested keys SEMANTICS (stage semantics) and COLOR (stage colour). Filled by Bitrix24, read-only." }
    },
    "batch": ["create", "update", "delete"]
  }
}

Error response example

403 — missing scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Errors

HTTP Code Description
403 SCOPE_DENIED API key does not have the crm scope
401 TOKEN_MISSING API key was not provided
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of errors — Errors.

Known specifics

The SEMANTICS key inside extra is more detailed than the semantics field. The field distinguishes three states, while the nested key distinguishes four:

extra.SEMANTICS semantics Stage state
process null Intermediate stage
success S Successful completion
failure F Failure
apology F Another final failure stage

The failure and apology stages are indistinguishable in the semantics field — both arrive as F. If your scenario needs to tell them apart, read extra.SEMANTICS.

See also