For AI agents: markdown of this page — /docs-content-en/entities/crm-v3-dictionaries/get.md documentation index — /llms.txt

Get a CRM dictionary entry

GET /v1/crm-dictionaries/:dictionary/:id

Retrieves a CRM dictionary entry by its string ID: a communication type, an activity provider, or a stage outcome.

This feature is rolling out. It requires a CRM update after 26.2200.0 and administrator activation. The release version has not been published. Until available, requests return 422 METHOD_NOT_YET_AVAILABLE with error.release.

Parameters

Parameter Type Required Description
Parameterdictionary (path) Typestring Requiredyes DescriptionDictionary from the table below
Parameterid (path) Typestring Requiredyes DescriptionNonempty entry ID from the list of entries in this dictionary. Preserve its case
dictionary Contents Example id
dictionaryactivity-providers ContentsActivity providers Example idCRM_TODO
dictionaryemail-types ContentsEmail address types Example idWORK
dictionaryphone-types ContentsPhone number types Example idWORK
dictionaryim-types ContentsMessenger types Example idFACEBOOK
dictionaryweb-types ContentsWebsite types Example idWORK
dictionarystage-semantics ContentsStage outcomes Example idF

Query parameters and a request body are not accepted. READONLY keys with the crm scope can read entries.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/crm-dictionaries/activity-providers/CRM_TODO" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/crm-dictionaries/activity-providers/CRM_TODO" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const response = await fetch(
  'https://vibecode.bitrix24.com/v1/crm-dictionaries/activity-providers/CRM_TODO',
  {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY'
    }
  }
)
const { success, data } = await response.json()

JavaScript — OAuth application

javascript 
const response = await fetch(
  'https://vibecode.bitrix24.com/v1/crm-dictionaries/activity-providers/CRM_TODO',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      Authorization: 'Bearer USER_SESSION_TOKEN'
    }
  }
)
const { success, data } = await response.json()

Response fields

HTTP 200 OK.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionEntry from the selected dictionary
Fielddata.id Typestring DescriptionEntry ID from the dictionary list

Activity providers

Field Type Description
Fielddata.name Typestring DescriptionActivity provider name
Fielddata.isAvailable Typeboolean DescriptionAvailable in the Bitrix24 account
Fielddata.isActive Typeboolean DescriptionActive
Fielddata.types Typearray DescriptionActivity types offered by the provider
Fielddata.types[].providerTypeId Typestring DescriptionType ID within this provider
Fielddata.types[].name Typestring DescriptionActivity type name
Fielddata.types[].directions Typeobject DescriptionDirection labels. Keys incoming, outgoing, and undefined have string values. An activity type without directions returns {}
Fielddata.defaultTypeId Typestring / null DescriptionDefault type ID from data.types[].providerTypeId, if provided
Fielddata.capabilities Typestring[] DescriptionProvider capability codes

Email, phone, messenger, and website types

Field Type Description
Fielddata.name Typestring / null DescriptionType name
Fielddata.nameShort Typestring / null DescriptionShort name
Fielddata.isDeprecated Typeboolean DescriptionThe type is deprecated

Stage outcomes

Field Type Description
Fielddata.name Typestring DescriptionStage outcome name

Response example

Activity provider:

JSON 
{
  "success": true,
  "data": {
    "id": "CRM_TODO",
    "name": "To-do",
    "isAvailable": true,
    "isActive": true,
    "types": [
      {
        "providerTypeId": "TODO",
        "name": "To-do",
        "directions": {}
      }
    ],
    "defaultTypeId": "TODO",
    "capabilities": [
      "calendar",
      "completion",
      "ping",
      "badge",
      "timeline"
    ]
  }
}

Email address type:

JSON 
{
  "success": true,
  "data": {
    "id": "WORK",
    "name": "Work email",
    "nameShort": "Work",
    "isDeprecated": false
  }
}

Stage outcome:

JSON 
{
  "success": true,
  "data": {
    "id": "F",
    "name": "Failed"
  }
}

Error response example

404 — entry not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Record with ID = `DUMMY_UNKNOWN` was not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid request shape
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionA query parameter was supplied
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo entry exists with the specified ID
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe feature is not yet available. Update information is provided in error.release
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionInvalid response from Bitrix24
HTTP401 CodeMISSING_API_KEY DescriptionMissing X-Api-Key
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 tokens are configured
HTTP403 CodeSCOPE_DENIED DescriptionThe key requires the crm scope

For shared API errors, see Errors.

See also