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.

Request parameters

Parameter Type Description
entityTypeId number Smart process type ID (in the URL)
id number Item ID (in the URL)

Request fields (body)

Parameter Type Description
title string Name
stageId string Stage. List: GET /v1/statuses?filter[entityId]=DYNAMIC_{entityTypeId}_STAGE_{categoryId}
contactId number Contact ID
companyId number Company ID
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
assignedById number Assignee. List: GET /v1/users
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
observers array Observer IDs

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

Examples

In the examples entityTypeId = 156, 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
id number Item ID
title string Name
stageId string Stage
opportunity number Amount
assignedById number Assignee
updatedBy number Last editor
updatedTime datetime Modification date

The response contains all item fields after the update.

Response example

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
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
404 ENTITY_NOT_FOUND An item with the specified ID was not found
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 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
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