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

Status dictionary types

GET /v1/statuses/entity-types

Returns every CRM dictionary in the Bitrix24 account: lead, deal, quote and smart process stages, sources, contact and company types. Pass a dictionary's id as entityId when requesting that dictionary's records.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/statuses/entity-types" \
  -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/entity-types', {
  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/entity-types', {
  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 Typearray DescriptionArray of dictionaries. There is no pagination; the whole array is returned
Fielddata[].id Typestring DescriptionDictionary identifier, for example STATUS, SOURCE, DEAL_STAGE, DEAL_STAGE_3, DYNAMIC_174_STAGE_3. Pass it as entityId in GET /v1/statuses?filter[entityId]=<id>
Fielddata[].name Typestring DescriptionDictionary name
Fielddata[].entityTypeId Typenumber DescriptionCRM object type the stage dictionary belongs to: 1 — lead, 2 — deal, 7 — quote, 31 — invoice; for smart processes, their entityTypeId. Type list: GET /v1/smart-processes
Fielddata[].parentId Typestring DescriptionIdentifier of the general dictionary the pipeline dictionary derives from. Returned for the stages of additional deal pipelines, for example DEAL_STAGE for DEAL_STAGE_1
Fielddata[].categoryId Typenumber | string DescriptionPipeline ID. A string for the stages of additional deal pipelines, a number for other dictionaries. Deal pipelines: GET /v1/deal-categories
Fielddata[].categoryName Typestring DescriptionPipeline name. Returned for smart process stages
Fielddata[].categorySort Typenumber DescriptionPipeline sort order. Returned for smart process stages
Fielddata[].isDefaultCategory Typeboolean DescriptionDefault pipeline. Returned for smart process stages
Fielddata[].isEnabled Typeboolean DescriptionThe dictionary's isEnabled flag. Returned for invoice, smart document and smart process stages
Fielddata[].prefix Typestring DescriptionStage code prefix of the pipeline: the DEAL_STAGE_1 dictionary has the prefix C1, and its stages have codes such as C1:NEW
Fielddata[].fieldAttributeScope Typestring DescriptionPipeline code for field attributes, for example category_1. An empty string for the general deal pipeline
Fielddata[].semanticInfo Typeobject DescriptionCodes of the initial and final stages. An empty object {} for invoice, smart document and smart process stage dictionaries
Fielddata[].semanticInfo.startField Typestring DescriptionInitial stage code
Fielddata[].semanticInfo.finalSuccessField Typestring DescriptionSuccessful final stage code
Fielddata[].semanticInfo.finalUnsuccessField Typestring DescriptionUnsuccessful final stage code
Fielddata[].semanticInfo.finalSort Typenumber DescriptionThe finalSort value from the dictionary settings

Fields other than id and name are returned only for the dictionaries they apply to. Classifiers such as SOURCE and CONTACT_TYPE carry only id and name.

Response example

Three of 37 dictionaries are shown.

JSON 
{
  "success": true,
  "data": [
    {
      "id": "STATUS",
      "name": "Lead stages",
      "entityTypeId": 1,
      "semanticInfo": {
        "startField": "NEW",
        "finalSuccessField": "CONVERTED",
        "finalUnsuccessField": "JUNK",
        "finalSort": 0
      }
    },
    {
      "id": "SOURCE",
      "name": "Sources"
    },
    {
      "id": "DEAL_STAGE_1",
      "name": "Deal stages Retail",
      "entityTypeId": 2,
      "parentId": "DEAL_STAGE",
      "categoryId": "1",
      "prefix": "C1",
      "fieldAttributeScope": "category_1",
      "semanticInfo": {
        "startField": "C1:NEW",
        "finalSuccessField": "C1:WON",
        "finalUnsuccessField": "C1:LOSE",
        "finalSort": 0
      }
    }
  ]
}

Error response example

401 — the key is not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

HTTP Code Description
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The reason is in error.message
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no permission to read CRM dictionaries in Bitrix24
HTTP502 CodeBITRIX_RESPONSE_INVALID DescriptionBitrix24 returned a response of an unexpected shape
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not found or has been revoked

Full list of common API errors — Errors.

Known specifics

A read-only key works. The method only reads data, so a key without write access gets the same response as a full-access key.

One stage dictionary per pipeline. Each deal pipeline and smart process pipeline has its own stage dictionary: DEAL_STAGE is the general pipeline, DEAL_STAGE_<pipeline ID> are additional ones, DYNAMIC_<entityTypeId>_STAGE_<pipeline ID> are smart process pipelines, SMART_INVOICE_STAGE_<pipeline ID> is the invoice pipeline. To get the stages of a specific pipeline, pass its dictionary identifier in filter[entityId].

See also