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

Update a pipeline

PATCH /v1/categories/:entityTypeId/:id

Updates the fields of an existing pipeline of the specified CRM entity type. Pass only the fields being changed, flat at the root of the JSON — without a fields wrapper.

Parameters

Parameter Type Required Description
ParameterentityTypeId (path) Typenumber Requiredyes DescriptionCRM entity type ID. 2 for deals, 3 for contacts, 4 for companies, 31 for invoices, and for a smart process, the value from GET /v1/smart-processes
Parameterid (path) Typenumber Requiredyes DescriptionPipeline identifier

Fields to update (body)

Field Bitrix24 Type Description
Fieldname Bitrix24name Typestring DescriptionPipeline name
Fieldsort Bitrix24sort Typenumber DescriptionSort order among the pipelines of this type

Examples

In the examples, entityTypeId = 2 (deals), id = 15 — replace with your values.

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/categories/2/15" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partners pipeline — updated",
    "sort": 700
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/categories/2/15" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partners pipeline — updated",
    "sort": 700
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2/15', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Partners pipeline — updated',
    sort: 700,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2/15', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Partners pipeline — updated',
    sort: 700,
  }),
})

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

Response fields

Returns the full pipeline object with the applied changes.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata Typeobject DescriptionThe updated pipeline
Fielddata.id Typenumber DescriptionPipeline identifier
Fielddata.entityTypeId Typenumber DescriptionCRM entity type ID, mirrors the path parameter
Fielddata.name Typestring DescriptionPipeline name
Fielddata.sort Typenumber DescriptionSort order
Fielddata.isDefault Typeboolean DescriptionWhether this is the type's main pipeline
Fielddata.originId Typestring | null DescriptionExternal source identifier. null for pipelines with no external binding. Deal pipelines only
Fielddata.originatorId Typestring | null DescriptionExternal system identifier. null for pipelines with no external binding. Deal pipelines only
Fielddata.isSystem Typestring DescriptionSystem pipeline: Y — created by Bitrix24, N — created by a user. Contact and company pipelines only
Fielddata.code Typestring | null DescriptionSymbolic code of a system pipeline, for example CATALOG_CONTRACTOR_CONTACT. null for user-created ones. Contact and company pipelines only

The field set depends on the entity type. Deals return originId and originatorId. Contacts (3) and companies (4) return isSystem and code. Invoices and smart processes return only the common fields. The createdDate field from the pipeline schema is not returned.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 15,
    "name": "Partners pipeline — updated",
    "sort": 700,
    "entityTypeId": 2,
    "isDefault": false,
    "originId": null,
    "originatorId": null
  }
}

Error response example

404 — pipeline with the specified id not found:

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

Errors

HTTP Code Description
HTTP400 CodeREADONLY_FIELD DescriptionA read-only field was sent: id, entityTypeId, isDefault, code, createdDate, originId or originatorId. The message names the specific field
HTTP404 CodeENTITY_NOT_FOUND DescriptionPipeline with the specified id not found — message Item not found
HTTP404 CodeENTITY_NOT_FOUND DescriptionentityTypeId does not match an existing type — message Smart process not found
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Only name and sort are writable. All other pipeline fields except isSystem are read-only — leave them out of the request body, or the request returns 400 READONLY_FIELD. isSystem is passed to Bitrix24, which does not apply it on update. The type's main pipeline is assigned in the Bitrix24 interface.

See also