For AI agents: markdown of this page — /docs-content-en/entities/items/create.md documentation index — /llms.txt

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 Own company ID
assignedById number Assignee. List: GET /v1/users
opportunity number Amount
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 account 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:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Errors

HTTP Code Description
400 INVALID_DYNAMIC_PARAM entityTypeId is not a positive integer or is reserved (1, 2, 3, 4, 7, 31)
400 READONLY_FIELD A read-only field was passed in the body (id, createdTime, updatedTime and others)
422 BITRIX_ERROR Field validation error from Bitrix24. The specific reason is in the message field
403 SCOPE_DENIED The API key does not have the crm scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

See also