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