[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-entities\u002Fstatuses\u002Fupdate":3,"docs-tabs-entities\u002Fstatuses\u002Fupdate":6},{"content":4,"lastmod":5},"\n## Update dictionary record\n\n`PATCH \u002Fv1\u002Fstatuses\u002F:id`\n\nUpdates the fields of a CRM dictionary record by ID.\n\n## Path parameters\n\n| Parameter | Type | Description |\n|----------|-----|---------|\n| `id` | number | Dictionary record ID |\n\n## Request body parameters\n\n| Parameter | Type | Description |\n|----------|-----|---------|\n| `name` | string | Name |\n| `description` | string | Record description. The field is not available on every Bitrix24 account |\n| `sort` | number | Sort order |\n| `color` | string | Color in HEX, e.g. `#22B9FF`. The `#` may be omitted |\n\nThe `entityId`, `statusId`, and `semantics` fields are set only when you [create a record](\u002Fdocs\u002Fentities\u002Fstatuses\u002Fcreate), and `categoryId` is determined by the `entityId` dictionary. This call does not change these four fields.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fstatuses\u002F42\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"name\": \"Prepayment received\", \"sort\": 35}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fstatuses\u002F42\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"name\": \"Prepayment received\", \"sort\": 35}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fstatuses\u002F42', {\n  method: 'PATCH',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({ name: 'Prepayment received', sort: 35 }),\n})\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fstatuses\u002F42', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ name: 'Prepayment received', sort: 35 }),\n})\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\nThe full updated record is returned.\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | object | Updated dictionary record (all fields — see [Dictionary fields](\u002Fdocs\u002Fentities\u002Fstatuses\u002Ffields)) |\n| `meta.warnings` | array | Present when the body contains fields that are not in [`GET \u002Fv1\u002Fstatuses\u002Ffields`](\u002Fdocs\u002Fentities\u002Fstatuses\u002Ffields), for example a misspelled name. Warning code `UNRECOGNIZED_WRITE_FIELD`: such a field may not have been saved. The response status is `200` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 42,\n    \"entityId\": \"DEAL_STAGE\",\n    \"statusId\": \"PREPAYMENT_INVOICE\",\n    \"name\": \"Prepayment received\",\n    \"nameInit\": null,\n    \"sort\": 35,\n    \"system\": false,\n    \"categoryId\": null,\n    \"color\": \"#39A8EF\",\n    \"semantics\": null,\n    \"description\": null,\n    \"extra\": {\n      \"SEMANTICS\": \"process\",\n      \"COLOR\": \"#39A8EF\"\n    }\n  }\n}\n```\n\n## Error response example\n\n404 — record not found:\n\n```json\n{\n  \"success\": false,\n  \"error\": { \"code\": \"ENTITY_NOT_FOUND\", \"message\": \"Status is not found.\" }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `READONLY_FIELD` | The body contains a read-only field: `id`, `system`, or `extra` |\n| 400 | `EMPTY_UPDATE_BODY` | The request body is empty — pass at least one field |\n| 404 | `ENTITY_NOT_FOUND` | No record with the given `id` |\n| 403 | `SCOPE_DENIED` | API key does not have the `crm` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n\nFull list of errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**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.\n\n**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:\n\n1. Create a stage in the same dictionary with [`POST \u002Fv1\u002Fstatuses`](\u002Fdocs\u002Fentities\u002Fstatuses\u002Fcreate). 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.\n2. Move the items to the new stage by passing its code in `stageId`: for deals — [`PATCH \u002Fv1\u002Fdeals\u002F:id`](\u002Fdocs\u002Fentities\u002Fdeals\u002Fupdate), for smart process items — [`PATCH \u002Fv1\u002Fitems\u002F:entityTypeId\u002F:id`](\u002Fdocs\u002Fentities\u002Fitems\u002Fupdate).\n3. Delete the old stage with [`DELETE \u002Fv1\u002Fstatuses\u002F:id`](\u002Fdocs\u002Fentities\u002Fstatuses\u002Fdelete). While items remain in it, the deletion returns `422 BITRIX_ERROR`.\n\n## See also\n\n- [Get dictionary record](\u002Fdocs\u002Fentities\u002Fstatuses\u002Fget)\n- [Dictionary fields](\u002Fdocs\u002Fentities\u002Fstatuses\u002Ffields)\n- [CRM dictionaries](\u002Fdocs\u002Fentities\u002Fstatuses)\n","2026-10-22",{},1794739425894]