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

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.fields Typeobject DescriptionMap of record fields. The key is the field name in camelCase, as in API responses, and the value is its description
Fielddata.fields.<field>.type Typestring DescriptionValue type: number, string, boolean, object
Fielddata.fields.<field>.readonly Typeboolean DescriptionRead-only field
Fielddata.fields.<field>.label Typestring DescriptionField label
Fielddata.fields.<field>.description Typestring DescriptionField description
Fielddata.batch Typestring[] DescriptionWrite operations available to the dictionary in the batch call POST /v1/statuses/batch: create, update, delete — see Batch calls

The label and description values are returned in English. Request headers do not switch the language.

Dictionary record fields described by data.fields:

Field Type RO Description
Fieldid Typenumber ROyes DescriptionRecord ID
FieldentityId Typestring RO DescriptionDictionary type (DEAL_STAGE, SOURCE, etc.). Set only when creating a record. PATCH does not change it
FieldstatusId Typestring RO DescriptionSymbolic code of the value. Set only when creating a record. PATCH does not change it
Fieldname Typestring RO DescriptionName
FieldnameInit Typestring/null RO DescriptionOriginal name
Fielddescription Typestring/null RO DescriptionRecord description. Not returned on every Bitrix24 account. Where it is missing, the field arrives as null
Fieldsort Typenumber RO DescriptionSort order
Fieldcolor Typestring/null RO DescriptionColor in HEX with a leading #
Fieldsemantics Typestring/null RO DescriptionSemantics: S — success, F — failure. null — an in-progress stage or a dictionary without semantics. Set only when creating a record. PATCH does not change it
Fieldsystem Typeboolean ROyes DescriptionSystem value that cannot be changed or deleted
FieldcategoryId Typenumber/null RO DescriptionPipeline ID. Populated for dictionaries of the form DEAL_STAGE_N, otherwise 0 or null. Determined by the dictionary in entityId, PATCH does not change it
Fieldextra Typeobject ROyes DescriptionAdditional data for dictionaries with stages — STATUS, DEAL_STAGE, DEAL_STAGE_N, QUOTE_STATUS. Contains the nested keys SEMANTICS and COLOR. Other dictionaries do not have this field

Response example

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." },
      "description": { "type": "string", "readonly": false, "label": "Description", "description": "Text description of the entry. The field is not available on every Bitrix24 account." },
      "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
HTTP403 CodeSCOPE_DENIED DescriptionAPI key does not have the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of errors, see 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. The mapping below holds for a stage whose sort places it within its own group:

extra.SEMANTICS semantics Stage state
extra.SEMANTICSprocess semanticsnull Stage stateIntermediate stage
extra.SEMANTICSsuccess semanticsS Stage stateSuccessful completion
extra.SEMANTICSfailure semanticsF Stage stateFailure
extra.SEMANTICSapology semanticsF Stage stateAnother 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.

extra.SEMANTICS follows sort, while semantics does not. The nested key is computed from the stage position relative to the success stage: a stage with semantics: "F" placed before the success stage by sort returns extra.SEMANTICS: "process", while the semantics field stays F. So changing sort does not change the stage group. To replace a stage with one from another group, see Update dictionary record.

See also