#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)

Field Type Required Default Description
title string yes — Smart process name
isCategoriesEnabled boolean false Use custom pipelines and sales tunnels in the smart process
isStagesEnabled boolean false Use custom stages and kanban in the smart process
isBeginCloseDatesEnabled boolean false "Start date" and "End date" fields
isClientEnabled boolean false "Client" field linked to contacts and companies
isLinkWithProductsEnabled boolean false Linking catalog products
isMycompanyEnabled boolean false "Your company details" field
isObserversEnabled boolean false "Observers" field
isSourceEnabled boolean false "Source" and "More about the source" fields
isAutomationEnabled boolean false Automation rules and triggers
isBizProcEnabled boolean false Business process designer
isDocumentsEnabled boolean false Document printing
isRecyclebinEnabled boolean false Recycle bin usage
isSetOpenPermissions boolean true Make new pipelines available to everyone
isUseInUserfieldEnabled boolean false Use the smart process in a user field
isRecurringEnabled boolean false "Recurrence" field
isPaymentsEnabled boolean false Online payment
isCountersEnabled boolean false Counters (notifications and badges)
relations object {} Relations with other CRM entities — see "Relations and user fields" below
linkedUserFields object {} Set of user fields in which the smart process will be displayed — see "Relations and user fields" below

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

#Examples

#curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.tech/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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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).

JSON 
{
  "title": "Supply contracts",
  "relations": {
    "parent": [
      { "entityTypeId": 2, "isChildrenListEnabled": "Y" }
    ],
    "child": [
      { "entityTypeId": 3, "isChildrenListEnabled": "Y" }
    ]
  }
}
Record field Type Description
entityTypeId number ID of the related type (2 = deals, 3 = contacts, 4 = companies, 7 = quotes, 31 = invoices, 1030+ = smart processes)
isChildrenListEnabled string ("Y"/"N") Whether to show the list of this smart process's records in the related type's card

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 is "Y" (enable display) or "N" (disable).

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

3 fixed keys are supported:

Key Where the smart process is displayed
TASKS_TASK|UF_CRM_TASK "CRM item" field in tasks
TASKS_TASK_TEMPLATE|UF_CRM_TASK "CRM item" field in task templates
CALENDAR_EVENT|UF_CRM_CAL_EVENT "CRM item" field in calendar events

#Response fields

Field Type Description
id number Internal record ID of the type
entityTypeId number Assigned entityTypeId — used in /v1/items/:entityTypeId
title string Name
createdBy number Creator
createdTime datetime Creation date
updatedTime datetime Modification date
customSectionId number | null Digital workplace ID (if linked)

Plus all isXxxEnabled flags in the state that was passed (or false by default). Full list — Type fields.

The list of items of the created type opens in Bitrix24 by entityTypeId:

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

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

#Response example

JSON 
{
  "success": true,
  "data": {
    "id": 31,
    "entityTypeId": 1050,
    "title": "Supply contracts",
    "createdBy": 1,
    "createdTime": "2026-04-21T13:46:45+03:00",
    "updatedTime": "2026-04-21T13:46:45+03: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:

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

#Errors

HTTP Code Description
401 MISSING_API_KEY The X-Api-Key header was not passed
401 INVALID_API_KEY The key was not found or was revoked
403 SCOPE_DENIED The API key does not have the crm scope
422 BITRIX_ERROR Any error from Bitrix24: title not passed, entityTypeId out of range, the portal's smart process limit exceeded, etc. The specific reason is in the message field

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 entityTypeId out of range was passed
  • Maximum number of smart processes exceeded — the portal limit was reached

Full list of general API errors — Errors.

#Known specifics

Auto-generation of entityTypeId. Bitrix24 assigns a free identifier itself. If you want to pass your own, the value must be unique and fall into one of the ranges: 128-192 inclusive, 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.

After creation isInitialized: false. Bitrix24 has not yet generated the standard stages and pipelines. They are created on the first access to the type in the interface or programmatically — via /v1/statuses and /v1/categories/:entityTypeId.

relations are bidirectional. If you specified parent: [{entityTypeId: 2, ...}], then in deals (type 2) a link to your new type automatically appears in the relations.child field 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