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

Update a smart process item

PATCH /v1/items/:entityTypeId/:id

Updates the fields of a smart process item. Pass only the fields you are changing.

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.

Parameters

Parameter Type Required Description
ParameterentityTypeId (path) Typenumber Requiredyes DescriptionSmart process type ID. List: GET /v1/smart-processes
Parameterid (path) Typenumber Requiredyes DescriptionItem ID. List: GET /v1/items/:entityTypeId

Request fields (body)

Field Type Description
Fieldtitle Typestring DescriptionName
FieldstageId Typestring DescriptionStage. List: GET /v1/statuses?filter[entityId]=DYNAMIC_{entityTypeId}_STAGE_{categoryId}
FieldcontactId Typenumber DescriptionContact ID. Search: GET /v1/contacts
FieldcompanyId Typenumber DescriptionCompany ID. Search: GET /v1/companies
Fieldopportunity Typenumber DescriptionAmount. Stored only on types with product rows enabled (isLinkWithProductsEnabled: true). Check with GET /v1/smart-processes/:entityTypeId
FieldisManualOpportunity Typeboolean DescriptionAmount set manually. A true value on a type with product rows disabled is refused with 422 AMOUNT_NOT_APPLIED
FieldcurrencyId Typestring DescriptionCurrency. List: GET /v1/currencies
FieldassignedById Typenumber DescriptionResponsible person. List: GET /v1/users
Fieldopened Typeboolean DescriptionAvailable to everyone
Fieldbegindate Typedatetime DescriptionStart date. Accepts ISO 8601, but only the date is stored — the time is dropped
Fieldclosedate Typedatetime DescriptionEnd date. Accepts ISO 8601, but only the date is stored — the time is dropped
Fieldobservers Typearray DescriptionObserver IDs — employees. List: GET /v1/users

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 the update.

Examples

The examples use entityTypeId = 156 and id = 783; replace them with your values.

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/items/156/783 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stageId": "DT156_41:WON",
    "opportunity": 750000
  }'

curl — OAuth application

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/items/156/783 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stageId": "DT156_41:WON",
    "opportunity": 750000
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/items/156/783', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    stageId: 'DT156_41:WON',
    opportunity: 750000,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/items/156/783', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    stageId: 'DT156_41:WON',
    opportunity: 750000,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe full item after the update. All fields — see Item fields

Response example

The main fields are shown. Full list: Item fields.

JSON 
{
  "success": true,
  "data": {
    "id": 783,
    "title": "Supply contract",
    "stageId": "DT156_41:WON",
    "categoryId": 41,
    "companyId": 15,
    "contactId": 42,
    "opportunity": 750000,
    "currencyId": "USD",
    "assignedById": 1,
    "createdBy": 1,
    "updatedBy": 1,
    "movedBy": 1,
    "createdTime": "2026-04-15T14:30:00+00:00",
    "updatedTime": "2026-04-15T16:45:00+00:00",
    "movedTime": "2026-04-15T16:45:00+00:00"
  }
}

Error response example

404 — item not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Item not found"
  }
}

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 updated
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
HTTP404 CodeENTITY_NOT_FOUND DescriptionAn item with the specified ID was not found
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 itself has already been updated: 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