## 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` | Workflow 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](/docs/entities/smart-processes/fields).

## Examples

### curl — personal key

```bash
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

```bash
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

```javascript
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

```javascript
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).

```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` | boolean / string | Whether to show the list of this smart process's records in the related type's card |

> **`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"`.

```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 |
| `updatedBy` | number | Last editor |
| `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](/docs/entities/smart-processes/fields).

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

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

`0` — the main pipeline. `<portal>` — the Bitrix24 account 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+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:

```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 |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 400 | `READONLY_FIELD` | A read-only field was passed in the body (`id`, `isInitialized`, `createdTime`, and others) |
| 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 Bitrix24 account limit was reached

Full list of general API errors — [Errors](/docs/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: 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.

**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

- [Update type](/docs/entities/smart-processes/update)
- [Delete type](/docs/entities/smart-processes/delete)
- [List types](/docs/entities/smart-processes/list)
- [Type fields](/docs/entities/smart-processes/fields)
- [Smart process items](/docs/entities/items)
- [Stages and pipelines](/docs/entities/categories)
- [Limits and optimization](/docs/optimization)