Get a List of CRM Directory Values v 3.0 crm.dictionary.[directory].list
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
Scope:
crmWho can execute the method: a user with permission to view leads, deals, or other CRM objects
This method belongs to REST 3.0. The call specifics and response format of the new API version are described in the REST 3.0 overview.
The crm.dictionary.<directory>.list method returns CRM directory values, for example, all deal types or all sources. The directory is set by the <directory> segment of the method name.
To specify a deal type, pass the value ID in the typeId field: for the "Sales" type, it is SALE. The IDs of all deal types are returned by the crm.dictionary.dealtype.list method.
Method Name for the Directory
|
Directory |
Method |
Where the value is used |
|
Deal types |
|
The |
|
Contact types |
|
The |
|
Company types |
|
The |
|
Salutations |
|
The |
|
Number of employees |
|
The |
|
Industries |
|
The |
|
Sources |
|
The |
|
Phone types |
|
The |
|
Email types |
|
The |
|
Website types |
|
The |
|
Messenger types |
|
The |
|
Address types |
|
The |
|
CRM object types |
|
The |
|
Stage groups |
|
The |
|
Activity providers |
|
The |
The method name is written in lowercase: crm.dictionary.dealtype.list, not crm.dictionary.dealType.list. If the name is written in a different case or contains an unknown directory, the method returns the "Method Not Found" error.
A single value by ID is returned by the crm.dictionary.<directory>.get method.
Method Parameters
Required parameters are marked with *
|
Name |
Description |
|
select |
List of fields to return for each value. Parameter description If the parameter is not passed, the method returns all fields |
|
filter |
Value selection conditions in the REST 3.0 format. Parameter description If the parameter is not passed, the method returns all values |
|
order |
Sorting in the format |
|
pagination |
Pagination parameters. Parameter description If the parameter is not passed, CRM value directories return the first 50 values, and the other directories return all values |
The select Parameter
Each directory has its own set of fields, which is described in the Directory Fields section.
Values in the response contain only the fields from select. An empty array [] returns all fields. For an unknown field, the method returns an error.
If you only need the names of the provider activity types, pass the types.name path in select, and the other keys are left out of the response. Dot notation works only for the types field of the activityprovider directory.
The filter Parameter
A filter is an array of conditions. The method combines the conditions in the array with AND logic. A condition is written in one of these ways:
["field", "operator", value]— for example,["sort", ">=", 20]["field", value]— without an operator: the method uses=, orinfor an array value, for example,["id", ["CALL", "WEB"]]
The operators available for each directory are listed in the Directory Fields section, and what each operator does is described in the REST 3.0 overview. Partial string search is not supported: there is no like operator, and ["name", "=", "Sales"] finds only the value with exactly this name.
The value must match the field type: a number for integer, true or false for boolean, and a string for string. The string "10" for the sort field or "N" for the isSystem field causes a validation error.
To combine conditions with OR logic, pass a group — an object with these keys:
type— the valuefilterlogic—andoror,andby defaultnegative—trueselects the values for which the group condition is not met. Works only in CRM value directories and in theentitytypedirectoryconditions— an array of conditions and nested groups
Example: the SALE deal type or types with a sort order greater than 40.
{
"filter": [
{
"type": "filter",
"logic": "or",
"conditions": [
["id", "=", "SALE"],
["sort", ">", 40]
]
}
]
}
If filter is passed as a string, a number, or an object such as {"id": "SALE"}, the method returns the BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION error.
The order Parameter
An object where the key is a field name and the value is the sort direction:
ASC— ascendingDESC— descending
The direction is case-insensitive. The fields available for sorting are listed in the Directory Fields section.
If order is not passed, the order depends on the directory:
- CRM value directories — by
sortin ascending order - stage groups — by
id - other directories — in the order in which Bitrix24 stores them
The pagination Parameter
|
Name |
Description |
|
limit |
Number of values per page. For a value greater than Default: |
|
page |
Page number, starting from If |
|
offset |
Number of values to skip from the beginning of the list. A negative value causes an error. Default: |
The method does not check unknown keys in pagination. If you pass {"size": 10} instead of {"limit": 10}, there is no error, and the response returns up to 50 values.
The response does not contain the total number of values. If a page returns fewer values than specified in limit, it is the last page.
Directory Fields
Directories differ in their set of fields, filter operators, and sort fields. Field descriptions with the filterable and sortable attributes are returned by the crm.dictionary.<directory>.field.list method.
CRM Value Directories
The dealtype, contacttype, companytype, honorific, employees, industry, and source directories. Values of these directories can be created, updated, and deleted with the crm.dictionary.<directory>.add, crm.dictionary.<directory>.update, and crm.dictionary.<directory>.delete methods.
|
Name |
Description |
|
id |
Value ID, for example, |
|
name |
Value name |
|
sort |
Sort order |
|
isSystem |
Indicates a default value. Possible values:
|
You can filter by all fields with the operators =, !=, >, >=, <, <=, in. The between operator works only for sort. You can sort by id, name, sort.
Communication Types
The phonetype, emailtype, webtype, and imtype directories — types of phone numbers, email addresses, websites, and messengers. The app passes the type ID in the valueTypeId key of a multiple field value, for example, {"valueTypeId": "WORK", "value": "+49300000000"}.
|
Name |
Description |
|
id |
Type ID, for example, |
|
name |
Full name, for example, "Work Phone". Can be |
|
nameShort |
Short name, for example, "Work Phone". Can be |
|
isDeprecated |
Indicates a deprecated type. Possible values:
|
You can filter by all fields with the operators =, !=, in. You can sort by all fields.
Address Types
The addresstype directory — types of contact and company addresses, for example, a legal or street address.
|
Name |
Description |
|
id |
Address type ID, for example, |
|
name |
Type code, for example, |
|
title |
Type name, for example, "Legal address" |
You can filter by all fields with the operators =, !=, in. You can sort by all fields.
Stage Groups
The stagesemantic directory — the groups to which a CRM item stage belongs.
|
Name |
Description |
|
id |
Group ID. Possible values:
|
|
name |
Group name |
You can filter by all fields with the operators =, !=, in. You can sort by all fields.
CRM Object Types
The entitytype directory contains only system object types: lead, deal, contact, company, estimate, invoice, document, and company document. It contains no SPAs. Their entityTypeId IDs are returned by the crm.type.list method.
|
Name |
Description |
|
id |
Object type ID |
|
code |
Type code, for example, |
|
title |
Type name |
You can filter by all fields with the operators =, !=, >, >=, <, <=, in. The between operator works only for id. You can sort by all fields.
Activity Providers
The activityprovider directory — CRM activity providers, for example, universal activity, meeting, call, email, task.
|
Name |
Description |
|
id |
Provider ID, for example, |
|
name |
Provider name |
|
isAvailable |
Indicates whether the provider is available in Bitrix24. Possible values:
|
|
isActive |
Indicates whether the provider is enabled. Possible values:
|
|
types |
Activity types of the provider. Each type has the ID |
|
defaultTypeId |
Default activity type, for example, |
|
capabilities |
Capabilities of the provider activities, for example, |
You can filter only by the id, isAvailable, and isActive fields with the operators =, !=, in. You can sort only by id.
Code Examples
How to Use Examples in Documentation
The new API call differs by adding the /api/ segment to the request URL:
https://{installation_address}/rest/api/{user_id}/{webhook_token}/crm.dictionary.dealtype.list
The examples retrieve the first three deal types that can be deleted, in ascending sort order. For a different directory, replace the method name according to the table above and check the fields in select, filter, and order against the Directory Fields section.
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"select":["id","name","sort"],"filter":[["isSystem","=",false]],"order":{"sort":"ASC"},"pagination":{"limit":3}}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/crm.dictionary.dealtype.list
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"select":["id","name","sort"],"filter":[["isSystem","=",false]],"order":{"sort":"ASC"},"pagination":{"limit":3},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/api/crm.dictionary.dealtype.list
CRM methods are not yet included in the list of REST 3.0 methods known to $b24.actions.v3.call.make: such a call returns the SDK error JSSDK_CORE_METHOD_NOT_SUPPORT_IN_API_V3. Call the method through the REST 3.0 HTTP client — $b24.getHttpClient(ApiVersion.v3).call.
import { ApiVersion, Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
type DictionaryListResult = {
items: {
id: string
name: string
sort: number
}[]
}
try {
const response = await $b24.getHttpClient(ApiVersion.v3).call<DictionaryListResult>(
'crm.dictionary.dealtype.list',
{
select: ['id', 'name', 'sort'],
filter: [
['isSystem', '=', false],
],
order: {
sort: 'ASC',
},
pagination: {
limit: 3,
},
},
Text.getUuidRfc4122()
)
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
console.info('Deal types:', result.items)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
CRM methods are not yet included in the list of REST 3.0 methods known to $b24.actions.v3.call.make. Call the method through the REST 3.0 HTTP client — $b24.getHttpClient(B24Js.ApiVersion.v3).call.
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function listDealTypes() {
try {
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.getHttpClient(B24Js.ApiVersion.v3).call(
'crm.dictionary.dealtype.list',
{
select: ['id', 'name', 'sort'],
filter: [
['isSystem', '=', false],
],
order: {
sort: 'ASC',
},
pagination: {
limit: 3,
},
},
B24Js.Text.getUuidRfc4122()
)
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
console.info('Deal types:', result.items)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', listDealTypes)
</script>
b24pysdk has no ready-made wrappers for CRM methods, and the SDK sends to REST 3.0 only the methods from the Config().api_v3_methods list. Add the method to this list and call it via bitrix_token.call_method with prefer_version=3.
from b24pysdk import Config
from b24pysdk.errors import BitrixSDKException
from b24pysdk.errors.v3 import BitrixAPIError
method = "crm.dictionary.dealtype.list"
Config().configure(api_v3_methods=Config().api_v3_methods | {method})
try:
response = bitrix_token.call_method(
api_method=method,
params={
"select": ["id", "name", "sort"],
"filter": [
["isSystem", "=", False],
],
"order": {"sort": "ASC"},
"pagination": {"limit": 3},
},
prefer_version=3,
)
for item in response["result"]["items"]:
print(item["id"], item["name"], item["sort"])
except BitrixAPIError as error:
print(
"Bitrix API error",
f"code: {error.code}",
f"message: {error.error.message}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Bitrix SDK error: {error.message}")
except Exception as error:
print(f"Unexpected error: {error}")
SDKs do not yet support the /rest/api/ address in calls. Use direct HTTP requests, for example, via curl or fetch.
try {
$response = $b24Service
->core
->call(
'crm.dictionary.dealtype.list',
[
'select' => ['id', 'name', 'sort'],
'filter' => [
['isSystem', '=', false],
],
'order' => [
'sort' => 'ASC',
],
'pagination' => [
'limit' => 3,
],
]
);
$result = $response
->getResponseData()
->getResult();
print_r($result);
} catch (Throwable $e) {
echo $e->getMessage();
}
SDKs do not yet support the /rest/api/ address in calls. Use direct HTTP requests, for example, via curl or fetch.
BX24.callMethod(
'crm.dictionary.dealtype.list',
{
select: ['id', 'name', 'sort'],
filter: [
['isSystem', '=', false],
],
order: {
sort: 'ASC',
},
pagination: {
limit: 3,
},
},
result => {
if (result.error())
console.error(result.error());
else
console.dir(result.data());
}
);
SDKs do not yet support the /rest/api/ address in calls. Use direct HTTP requests, for example, via curl or fetch.
require_once('crest.php');
$result = CRest::call(
'crm.dictionary.dealtype.list',
[
'select' => ['id', 'name', 'sort'],
'filter' => [
['isSystem', '=', false],
],
'order' => [
'sort' => 'ASC',
],
'pagination' => [
'limit' => 3,
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "crm.dictionary.dealtype.list", b24.Params{
"select": []string{"id", "name", "sort"},
"filter": []any{
[]any{"isSystem", "=", false},
},
"order": b24.Params{
"sort": "ASC",
},
"pagination": b24.Params{
"limit": 3,
},
}, b24.WithIdempotent())
if err != nil {
return fmt.Errorf("crm.dictionary.dealtype.list: %w", err)
}
raw, ok := b24.Unwrap(res.Result, "items")
if !ok {
return fmt.Errorf("response has no items key")
}
var items []struct {
ID string `json:"id"`
Name string `json:"name"`
Sort int `json:"sort"`
}
if err := json.Unmarshal(raw, &items); err != nil {
return fmt.Errorf("parse response: %w", err)
}
for _, it := range items {
fmt.Println(it.ID, it.Name, it.Sort)
}
Response Handling
HTTP status: 200
{
"result": {
"items": [
{
"id": "COMPLEX",
"name": "Integrated sales",
"sort": 20
},
{
"id": "GOODS",
"name": "Merchandise sales",
"sort": 30
},
{
"id": "SERVICES",
"name": "Services",
"sort": 40
}
]
},
"time": {
"start": 1793715427,
"finish": 1793715427.786939,
"duration": 0.7869389057159424,
"processing": 0,
"date_start": "2026-11-03T17:17:07+03:00",
"date_finish": "2026-11-03T17:17:07+03:00",
"operating_reset_at": 1793716020,
"operating": 0
}
}
Returned Data
|
Name |
Description |
|
result |
Object with response data |
|
result.items |
Array of directory values on the current page. If no values match the filter or the page is beyond the end of the list, the array is empty |
|
result.items[] |
Directory value. The set of fields is defined by the |
|
time |
Information about the request execution time |
Error Handling
HTTP status: 400
{
"error": {
"code": "BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION",
"message": "Error validating request object.",
"validation": [
{
"message": "This request requires data type \"int\" in field \"sort\".",
"field": "sort"
}
]
}
}
|
Name |
Description |
|
error.code |
String error code. Use it to identify the type of exception |
|
error.message |
Text description of the error |
|
error.validation |
Array with error details. Present only in data validation errors |
|
error.validation[].field |
Name of the field where the validation error occurred |
|
error.validation[].message |
Description of the error related to the specified field |
Possible Error Codes
Request Validation Errors
Error Code: BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION
|
Field |
Error description |
How to Fix |
|
|
This request requires data type |
Pass a value of the field type in the filter condition |
|
|
DTO |
The field cannot be used in a filter. The fields available for filtering are listed in the Directory Fields section |
|
|
DTO |
The field cannot be used for sorting. The fields available for sorting are listed in the Directory Fields section |
Filter Errors
Error Code: BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION
|
Field |
Error description |
How to Fix |
|
|
Invalid filter |
Check the condition from the error message, the operators, and |
|
|
Invalid filter |
Pass an array of two values for |
Unknown Filter Operator
Error Code: BITRIX_REST_V3_EXCEPTION_UNKNOWNFILTEROPERATOREXCEPTION
|
Field |
Error description |
How to Fix |
|
|
Unknown filter operator |
Use the operators from the Directory Fields section. There is no |
Unknown Field Error
Error Code: BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION
|
Field |
Error description |
How to Fix |
|
|
Unknown field |
Check the field name in |
Sort Error
Error Code: BITRIX_REST_V3_EXCEPTION_INVALIDORDEREXCEPTION
|
Field |
Error description |
How to Fix |
|
|
Invalid sort order |
Pass |
Pagination Error
Error Code: BITRIX_REST_V3_EXCEPTION_INVALIDPAGINATIONEXCEPTION
|
Field |
Error description |
How to Fix |
|
|
Incorrect |
Pass a positive number in |
Access Denied
Error Code: BITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION, HTTP status: 403
|
Field |
Error description |
How to Fix |
|
|
Access denied |
Call the method on behalf of a user with permission to view leads, deals, or other CRM objects |
Method Not Found
Error Code: BITRIX_REST_V3_EXCEPTION_METHODNOTFOUNDEXCEPTION, HTTP status: 404
|
Field |
Error description |
How to Fix |
|
|
Method |
Check the method name: it is written in lowercase, for example, |
Statuses and System Error Codes
HTTP Status: 4xx, 5xx
The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.
|
Status |
Code |
Description |
|
|
|
An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The request intensity limit has been exceeded |
|
|
|
The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit |
|
|
|
The request contains no authorization data: neither an access token nor a webhook code was passed |
|
|
|
Methods are called over the HTTPS protocol only |
|
|
|
The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support |
|
|
|
REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — |
|
|
|
No active webhook with the specified user identifier and secret code was found |
|
|
|
No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope |
|
|
|
The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with |
|
|
|
The access token has expired |
|
|
|
The application is installed, but the Bitrix24 administrator has granted access to it only to specific users |
|
|
|
The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site |
Continue Learning
- CRM Directories in REST 3.0: Overview of Methods
- Add a CRM Directory Value v 3.0 crm.dictionary.[directory].add
- Update a CRM Directory Value v 3.0 crm.dictionary.[directory].update
- Get a CRM Directory Value v 3.0 crm.dictionary.[directory].get
- Delete a CRM Directory Value v 3.0 crm.dictionary.[directory].delete