لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/items.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

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.

Use the entityTypeId field from GET /v1/smart-processes in the /v1/items/:entityTypeId path. The type record's internal id is a different identifier. For example, if a type is returned as { "id": 3, "entityTypeId": 174 }, the path starts with /v1/items/174. Use the returned value rather than assuming all type IDs start at 1030.

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 list available types, call GET /v1/smart-processes.

Use the entityTypeId field from GET /v1/smart-processes in the /v1/items/:entityTypeId path. The type record's internal id is a different identifier. For example, if a type is returned as { "id": 3, "entityTypeId": 174 }, the path starts with /v1/items/174. Use the returned value rather than assuming all type IDs start at 1030.

Request fields (body)

Parameter Type Description
Parametertitle Typestring DescriptionName
ParameterxmlId Typestring DescriptionExternal code
ParameterstageId Typestring DescriptionStage. Format: DT{typeId}_{catId}:{stage}. List: GET /v1/statuses?filter[entityId]=DYNAMIC_{entityTypeId}_STAGE_{categoryId}
ParametercategoryId Typenumber DescriptionPipeline ID. List: GET /v1/categories/:entityTypeId
ParametercontactId Typenumber DescriptionContact ID. Search: GET /v1/contacts
ParametercompanyId Typenumber DescriptionCompany ID. Search: GET /v1/companies
ParametermycompanyId Typenumber DescriptionID of your own company
ParameterassignedById Typenumber DescriptionResponsible person. List: GET /v1/users
Parameteropportunity Typenumber DescriptionAmount. Stored only on types with product rows enabled (isLinkWithProductsEnabled: true). Check with GET /v1/smart-processes/:entityTypeId
ParameterisManualOpportunity Typeboolean DescriptionAmount set manually. A true value on a type with product rows disabled is refused with 422 AMOUNT_NOT_APPLIED
ParametercurrencyId Typestring DescriptionCurrency. List: GET /v1/currencies
Parameteropened Typeboolean DescriptionAvailable to everyone
Parameterbegindate Typedatetime DescriptionStart date. Accepts ISO 8601, but only the date is stored — the time is dropped
Parameterclosedate Typedatetime DescriptionEnd date. Accepts ISO 8601, but only the date is stored — the time is dropped
ParametersourceId Typestring DescriptionSource
Parameterobservers Typearray DescriptionObserver IDs

Full field list: GET /v1/items/:entityTypeId/fields. User fields (ufCrmN_*) are also accepted. Pass fields flat at the JSON root, without a fields object: it is rejected with 400 NESTED_FIELDS_ENVELOPE before creation.

Examples

The examples use 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
Fieldid Typenumber DescriptionItem ID
Fieldtitle Typestring DescriptionName
FieldstageId Typestring DescriptionStage
FieldcategoryId Typenumber DescriptionPipeline ID
FieldcompanyId Typenumber DescriptionCompany ID
FieldcontactId Typenumber DescriptionContact ID
Fieldopportunity Typenumber DescriptionAmount
FieldcurrencyId Typestring DescriptionCurrency
FieldassignedById Typenumber DescriptionResponsible person
FieldcreatedBy Typenumber DescriptionCreator
FieldcreatedTime Typedatetime DescriptionCreation date
FieldupdatedTime Typedatetime DescriptionModification 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
HTTP400 CodeINVALID_DYNAMIC_PARAM DescriptionentityTypeId is not a positive integer or is reserved (1, 2, 3, 4, 7, 31)
HTTP400 CodeNESTED_FIELDS_ENVELOPE DescriptionThe body contains an object under fields instead of flat fields at the JSON root; the item is not created
HTTP400 CodeREADONLY_FIELD DescriptionA read-only field was passed in the body (id, createdTime, updatedTime and others)
HTTP400 CodeCLIENT_BLOCK_DISABLED DescriptionThe 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
HTTP422 CodeAMOUNT_NOT_APPLIED DescriptionThe 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
HTTP422 CodeBITRIX_ERROR DescriptionField validation error from Bitrix24. The specific reason is in the message field
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

See also