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

Update dictionary record

PATCH /v1/statuses/:id

Updates the fields of a CRM dictionary record by ID.

Path parameters

Parameter Type Description
Parameterid Typenumber DescriptionDictionary record ID

Request body parameters

Parameter Type Description
Parametername Typestring DescriptionName
Parameterdescription Typestring DescriptionRecord description. The field is not available on every Bitrix24 account
Parametersort Typenumber DescriptionSort order
Parametercolor Typestring DescriptionColor in HEX, e.g. #22B9FF. The # may be omitted

The entityId, statusId, and semantics fields are set only when you create a record, and categoryId is determined by the entityId dictionary. This call does not change these four fields.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/statuses/42" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Prepayment received", "sort": 35}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/statuses/42" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Prepayment received", "sort": 35}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses/42', {
  method: 'PATCH',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Prepayment received', sort: 35 }),
})
const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses/42', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Prepayment received', sort: 35 }),
})
const { success, data } = await res.json()

Response fields

The full updated record is returned.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionUpdated dictionary record (all fields — see Dictionary fields)
Fieldmeta.warnings Typearray DescriptionPresent when the body contains fields that are not in GET /v1/statuses/fields, for example a misspelled name. Warning code UNRECOGNIZED_WRITE_FIELD: such a field may not have been saved. The response status is 200

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 42,
    "entityId": "DEAL_STAGE",
    "statusId": "PREPAYMENT_INVOICE",
    "name": "Prepayment received",
    "nameInit": null,
    "sort": 35,
    "system": false,
    "categoryId": null,
    "color": "#39A8EF",
    "semantics": null,
    "description": null,
    "extra": {
      "SEMANTICS": "process",
      "COLOR": "#39A8EF"
    }
  }
}

Error response example

404 — record not found:

JSON 
{
  "success": false,
  "error": { "code": "ENTITY_NOT_FOUND", "message": "Status is not found." }
}

Errors

HTTP Code Description
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a read-only field: id, system, or extra
HTTP400 CodeEMPTY_UPDATE_BODY DescriptionThe request body is empty — pass at least one field
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo record with the given id
HTTP403 CodeSCOPE_DENIED DescriptionAPI key does not have the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing

Full list of errors — Errors.

Known specifics

Immutable fields in the body do not cause an error. If you pass entityId, statusId, semantics, or categoryId, the response has status 200 and success: true, while these fields keep their previous values. A semantics value other than S, F, or null is not rejected either. So success: true does not mean the field changed: check the result against data in the response.

How to move a stage to another group. You cannot change the group of an existing stage through the API, so you replace the stage with a new one:

  1. Create a stage in the same dictionary with POST /v1/statuses. Without semantics, it becomes an intermediate stage. With semantics: "F", it becomes a final failure stage. A pipeline has only one success stage, and you cannot create a second one.
  2. Move the items to the new stage by passing its code in stageId: for deals — PATCH /v1/deals/:id, for smart process items — PATCH /v1/items/:entityTypeId/:id.
  3. Delete the old stage with DELETE /v1/statuses/:id. While items remain in it, the deletion returns 422 BITRIX_ERROR.

See also