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

Change a CRM setting

PATCH /v1/crm-settings/:id

Change a CRM setting for the entire Bitrix24 account. Use a key with write access and check the value schema first.

Parameters

Parameter Type Required Description
Parameterid (path) Typestring Requiredyes DescriptionIdentifier from the settings list.

Request body

Field Type Required Description
Fieldvalue Typeany JSON Requiredyes DescriptionComplete value matching meta.schema from get. Required even for null, false or 0.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/crm-settings/crm.layout.file_previewer.enabled" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": true}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/crm-settings/crm.layout.file_previewer.enabled" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": true}'

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/crm-settings/crm.layout.file_previewer.enabled', {
  method: 'PATCH',
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"value": true}),
})
const result = await response.json()

JavaScript — OAuth application

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/crm-settings/crm.layout.file_previewer.enabled', {
  method: 'PATCH',
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"value": true}),
})
const result = await response.json()

Response fields

Field Description
Fielddata.id DescriptionIdentifier.
Fielddata.value DescriptionJSON value with its original type.
Fielddata.meta.title DescriptionSetting title.
Fielddata.meta.description DescriptionSetting description.
Fielddata.meta.schema DescriptionAccepted value schema, validated by Bitrix24.

Response example

Response structure with neutral sample data.

JSON 
{
  "success": true,
  "data": {
    "id": "crm.layout.file_previewer.enabled",
    "value": true,
    "meta": {
      "title": "File preview",
      "description": "Preview files",
      "schema": {
        "type": "boolean"
      }
    }
  }
}

Error response example

400 — unknown query parameter or a missing required field:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "value is required"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid type or identifier.
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown query parameter.
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionMissing required body field.
HTTP400 CodeUNKNOWN_FIELD DescriptionUnknown body field.
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 credentials.
HTTP403 CodeSCOPE_DENIED DescriptionThe crm scope is required.
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key access mode forbids writes.
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe record is absent or inaccessible.
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe method is absent on the account. error.release names the required release.
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned an invalid response shape.

Other Bitrix24 refusals retain their original code and message. Common API errors.

Known behavior

An object in value replaces the complete setting value. A successful write is not rolled back if its readback fails. Never blindly retry an ambiguous write failure: read the setting first.

See also