Smart process types

Manage smart process types: create, get, update, delete, search. A type is a template (entity definition), not a record inside it. To work with items inside a type, use /v1/items/:entityTypeId.

Bitrix24 API: crm.type.* Scope: crm

Create a smart process type

POST /v1/smart-processes

Creates a new smart process type with an automatically assigned entityTypeId. After creation, the type is available at /v1/items/:entityTypeId for CRUD operations on items.

Request fields (body)

Full list of fields: GET /v1/smart-processes/fields.

Examples

curl — personal key

curl -X POST https://vibecode.bitrix24.com/v1/smart-processes \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Supply contracts",
    "isStagesEnabled": true,
    "isCategoriesEnabled": true,
    "isAutomationEnabled": true,
    "isBizProcEnabled": true,
    "isLinkWithProductsEnabled": true
  }'

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/smart-processes \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Supply contracts",
    "isStagesEnabled": true,
    "isCategoriesEnabled": true,
    "isAutomationEnabled": true,
    "isBizProcEnabled": true,
    "isLinkWithProductsEnabled": true
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/smart-processes', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Supply contracts',
    isStagesEnabled: true,
    isCategoriesEnabled: true,
    isAutomationEnabled: true,
    isBizProcEnabled: true,
    isLinkWithProductsEnabled: true,
  }),
})

const { success, data } = await res.json()
console.log('Type created, entityTypeId:', data.entityTypeId)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/smart-processes', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Supply contracts',
    isStagesEnabled: true,
    isCategoriesEnabled: true,
    isAutomationEnabled: true,
    isBizProcEnabled: true,
    isLinkWithProductsEnabled: true,
  }),
})

const { success, data } = await res.json()

Relations and user fields

The relations and linkedUserFields fields are not described in /fields, but they are accepted on creation and saved by Bitrix24.

`relations` — relations with CRM entities

An object with two arrays: parent (parent types) and child (child types).

{
  "title": "Supply contracts",
  "relations": {
    "parent": [
      { "entityTypeId": 2, "isChildrenListEnabled": "Y" }
    ],
    "child": [
      { "entityTypeId": 3, "isChildrenListEnabled": "Y" }
    ]
  }
}

isChildrenListEnabled format. The field accepts a boolean true/false, the strings "Y"/"N", or "true"/"false" — the value is normalized automatically (true, "Y", "yes", 1 → enabled; false, "N", "no", 0 → disabled). In responses the flag is always returned as "Y"/"N".

Side effect of isClientEnabled: true: Bitrix24 automatically adds relations with contacts (entityTypeId: 3) and companies (entityTypeId: 4) to relations.parent with the isPredefined: "Y" flag — you do not need to pass them manually.

`linkedUserFields` — display in user fields

An object where the key is a field identifier from another entity in the {ENTITY_CODE}|{FIELD_NAME} format, and the value enables (true) or disables (false) the display.

Value format. The field accepts a boolean true/false, the strings "Y"/"N", or "true"/"false" — the value is normalized automatically (true, "Y", "yes", 1 → enabled; false, "N", "no", 0 → disabled). In responses the flag is always returned as "Y"/"N".

{
  "title": "Supply contracts",
  "linkedUserFields": {
    "TASKS_TASK|UF_CRM_TASK": "Y",
    "TASKS_TASK_TEMPLATE|UF_CRM_TASK": "Y",
    "CALENDAR_EVENT|UF_CRM_CAL_EVENT": "Y"
  }
}

Three fixed keys are supported:

Response fields

Plus all isXxxEnabled flags with the values that were passed (false by default). Full list — Type fields.

In Bitrix24, the item list of the created type opens at a URL built from its entityTypeId:

https://<portal>.bitrix24.com/crm/type/<entityTypeId>/list/category/0/

0 — the main pipeline. <portal> — the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

{
  "success": true,
  "data": {
    "id": 31,
    "entityTypeId": 1050,
    "title": "Supply contracts",
    "createdBy": 1,
    "createdTime": "2026-04-21T13:46:45+00:00",
    "updatedTime": "2026-04-21T13:46:45+00:00",
    "updatedBy": 1,
    "customSectionId": null,
    "isCategoriesEnabled": true,
    "isStagesEnabled": true,
    "isBeginCloseDatesEnabled": false,
    "isClientEnabled": false,
    "isLinkWithProductsEnabled": true,
    "isMycompanyEnabled": false,
    "isObserversEnabled": false,
    "isSourceEnabled": false,
    "isAutomationEnabled": true,
    "isBizProcEnabled": true,
    "isDocumentsEnabled": false,
    "isRecyclebinEnabled": false,
    "isSetOpenPermissions": true,
    "isUseInUserfieldEnabled": false,
    "isRecurringEnabled": false,
    "isPaymentsEnabled": false,
    "isCountersEnabled": false,
    "isInitialized": false
  }
}

Error response example

422 — a required field was not passed:

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required field \"Title\" is not filled in"
  }
}

Errors

Typical message values for BITRIX_ERROR:

• Required field "Title" is not filled in — title was omitted
• EntityTypeId should be more or equal than 128 and less than 192 — an out-of-range entityTypeId was passed
• Maximum number of smart processes exceeded — the account limit was reached

Full list of general API errors — Errors.

Known specifics

Auto-generation of entityTypeId. Bitrix24 assigns a free identifier automatically. If you want to pass your own, the value must be unique and fall into one of the ranges: from 128 to 191 (≥ 128 and < 192), or an even number ≥ 1030. The value is returned in the entityTypeId field of the response — save it and use it in all requests to the type and its items.

isInitialized: false after creation. Bitrix24 has not yet generated the standard stages and pipelines. They are created the first time the type is accessed in the interface, or programmatically — via /v1/statuses and /v1/categories/:entityTypeId.

relations are bidirectional. If you specify parent: [{entityTypeId: 2, ...}], a link to your new type automatically appears in the relations.child field of deals (type 2), with the isPredefined: "N" flag (a user-defined relation).

isSetOpenPermissions defaults to true — this is the only flag with a positive default. If you need private pipelines, pass false explicitly.

See also

• Update type
• Delete type
• List types
• Type fields
• Smart process items
• Stages and pipelines
• Digital workspaces
• Limits and optimization