Smart processes (Items)

Manage CRM smart process items: create, retrieve, update, delete, filter.

Bitrix24 API: crm.item.* Scope: crm

The path contains a dynamic parameter :entityTypeId — the smart process type ID. Find available types: GET /v1/smart-processes.

Create a smart process item

POST /v1/items/:entityTypeId

Creates a new item in the specified smart process. The entityTypeId parameter defines the smart process type. To find available types: GET /v1/smart-processes.

Request fields (body)

Parameter	Type	Description
`title`	string	Name
`xmlId`	string	External code
`stageId`	string	Stage. Format: `DT{typeId}_{catId}:{stage}`. List: `GET /v1/statuses?filter[entityId]=DYNAMIC_{entityTypeId}_STAGE_{categoryId}`
`categoryId`	number	Pipeline ID. List: `GET /v1/categories/:entityTypeId`
`contactId`	number	Contact ID. Search: `GET /v1/contacts`
`companyId`	number	Company ID. Search: `GET /v1/companies`
`mycompanyId`	number	ID of your own company
`assignedById`	number	Assignee. List: `GET /v1/users`
`opportunity`	number	Amount. Stored only on types with product rows enabled (`isLinkWithProductsEnabled: true`). Check with `GET /v1/smart-processes/:entityTypeId`
`isManualOpportunity`	boolean	Amount set manually. A `true` value on a type with product rows disabled is refused with `422 AMOUNT_NOT_APPLIED`
`currencyId`	string	Currency. List: `GET /v1/currencies`
`opened`	boolean	Available to everyone
`begindate`	datetime	Start date. Accepts ISO 8601, but only the date is stored — the time is dropped
`closedate`	datetime	End date. Accepts ISO 8601, but only the date is stored — the time is dropped
`sourceId`	string	Source
`observers`	array	Observer IDs

Full field list: GET /v1/items/:entityTypeId/fields. User fields (ufCrmN_*) are also accepted.

Examples

In the examples entityTypeId = 156 — replace it with the ID of your smart process.

curl — personal key

Terminal

curl -X POST https://vibecode.bitrix24.com/v1/items/156 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New contract",
    "categoryId": 41,
    "assignedById": 1,
    "companyId": 15,
    "opportunity": 500000,
    "currencyId": "USD"
  }'

curl — OAuth application

Terminal

curl -X POST https://vibecode.bitrix24.com/v1/items/156 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New contract",
    "categoryId": 41,
    "assignedById": 1,
    "companyId": 15,
    "opportunity": 500000,
    "currencyId": "USD"
  }'

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/items/156', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'New contract',
    categoryId: 41,
    assignedById: 1,
    companyId: 15,
    opportunity: 500000,
    currencyId: 'USD',
  }),
})

const { success, data } = await res.json()
console.log('Item ID:', data.id)

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/items/156', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'New contract',
    categoryId: 41,
    assignedById: 1,
    companyId: 15,
    opportunity: 500000,
    currencyId: 'USD',
  }),
})

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

Response fields

Field	Type	Description
`id`	number	Item ID
`title`	string	Name
`stageId`	string	Stage
`categoryId`	number	Pipeline ID
`companyId`	number	Company ID
`contactId`	number	Contact ID
`opportunity`	number	Amount
`currencyId`	string	Currency
`assignedById`	number	Assignee
`createdBy`	number	Creator
`createdTime`	datetime	Creation date
`updatedTime`	datetime	Modification date

The response contains all item fields, including user fields (ufCrmN_*).

The URL of the item card in Bitrix24 is built from id:

https://<portal>.bitrix24.com/crm/type/<entityTypeId>/details/<id>/

<entityTypeId> — the smart process type ID (the same one used in the request path). <portal> — the Bitrix24 portal domain. If the smart process is placed in a separate section of your Bitrix24 account, Bitrix24 opens the card at the corresponding path. Access is limited by the employee's permissions in Bitrix24.

Response example

JSON

{
  "success": true,
  "data": {
    "id": 783,
    "title": "New contract",
    "stageId": "DT156_41:NEW",
    "categoryId": 41,
    "companyId": 15,
    "contactId": null,
    "opportunity": 500000,
    "currencyId": "USD",
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-04-15T14:30:00+00:00",
    "updatedTime": "2026-04-15T14:30:00+00:00"
  }
}

Error response example

403 — no scope: