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

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)
400 CLIENT_BLOCK_DISABLED The body carries a client (contactId, contactIds or companyId) while the smart process has the "Client" block disabled. Check GET /v1/smart-processes/:entityTypeId, field isClientEnabled
422 AMOUNT_NOT_APPLIED The body carried isManualOpportunity: true while the smart-process type has product rows disabled, so neither the manual mode nor the amount was stored. The item is still created: its actual state is returned in data, and the fields that were not applied are listed in error.details.unappliedFields, with their actual values in error.details.currentValues. An amount sent without that flag is not checked — the response does not let you tell it apart from a recalculation based on product rows
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