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

List CRM dictionary values

GET /v1/crm-dictionaries/:dictionary

Returns one page of values from a CRM dictionary for activities, contact details, or stage semantics.

Availability. An administrator must enable this feature. It requires a CRM update after version 26.2200.0. The release version for that update has not yet been announced. If unavailable, the API returns 422 METHOD_NOT_YET_AVAILABLE with error.release.

Parameters

Parameter Type Required Default Description
Parameterdictionary (path) Typestring Requiredyes Default— Descriptionactivity-providers, email-types, phone-types, im-types, web-types, stage-semantics
Parameterlimit (query) Typeinteger Requiredno Default50 DescriptionPage size, from 1 to 1000
Parameteroffset (query) Typeinteger Requiredno Default0 DescriptionNonnegative number of records to skip

To request the next page, increase offset by limit. The response contains one page without a total record count.

Examples

curl — personal key

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/crm-dictionaries/email-types?limit=2" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/crm-dictionaries/email-types?limit=2" \
  -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/crm-dictionaries/email-types?limit=2', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const result = await res.json()
console.log(result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-dictionaries/email-types?limit=2', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const result = await res.json()
console.log(result)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue
Fielddata Typearray DescriptionDictionary values
Fielddata[].id Typestring DescriptionID for Get a dictionary value
Fielddata[].name Typestring | null DescriptionName. Communication types may return null
Fielddata[].nameShort Typestring | null DescriptionShort name, for communication types only
Fielddata[].isDeprecated Typeboolean DescriptionWhether the communication type is deprecated
Fielddata[].isAvailable Typeboolean DescriptionWhether the activity provider is available, for activity-providers only
Fielddata[].isActive Typeboolean DescriptionWhether the activity provider is active
Fielddata[].types Typearray DescriptionActivity types supported by the provider
Fielddata[].types[].providerTypeId Typestring DescriptionActivity type ID from this array
Fielddata[].types[].name Typestring DescriptionActivity type name
Fielddata[].types[].directions Typeobject DescriptionDirections for this activity type
Fielddata[].defaultTypeId Typestring | null DescriptionDefault activity type, from types[].providerTypeId
Fielddata[].capabilities Typestring[] DescriptionActivity provider capabilities
Fieldmeta.limit Typeinteger DescriptionRequested page size
Fieldmeta.offset Typeinteger DescriptionRequested offset

types, defaultTypeId, capabilities, isAvailable, and isActive apply only to activity-providers. Each stage-semantics item contains id and name.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": "WORK",
      "name": "Work email",
      "nameShort": "Work",
      "isDeprecated": false
    },
    {
      "id": "HOME",
      "name": "Personal email",
      "nameShort": "Personal",
      "isDeprecated": false
    }
  ],
  "meta": {
    "limit": 2,
    "offset": 0
  }
}

Error response example

400: invalid page size:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "limit must be positive and offset nonnegative safe integers"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionA parameter has an invalid type or shape
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionAn unknown or repeated query parameter
HTTP401 CodeMISSING_API_KEY DescriptionThe API key is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 credentials
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied permission for this operation
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe feature is disabled or unavailable on this portal. error.release identifies the required update
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused the request. See error.message
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 returned an invalid response

For shared API errors, see Errors.

See also