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

Set card layout

PUT /v1/crm/card-config/:entityTypeId

Writes the layout of card sections and fields for the given scope. Fully replaces the previous layout of this scope. The body contains data, an array of sections — each section describes a card block and its fields.

Path parameter

Parameter Type Description
ParameterentityTypeId Typenumber DescriptionCRM object type:
1 — lead
2 — deal
3 — contact
4 — company
7 — quote
31 — invoice
smart process — numeric type ID from GET /v1/smart-processes, field entityTypeId

Request fields (body)

Field Type Required Description
Fielddata Typearray Requiredyes DescriptionArray of layout sections in display order
Fielddata[].name Typestring Requiredyes DescriptionInternal section name
Fielddata[].title Typestring Requiredyes DescriptionDisplayed section title
Fielddata[].type Typestring Requiredno DescriptionAlways section. If omitted, section is saved
Fielddata[].elements Typearray Requiredno DescriptionSection fields in display order. If omitted or empty, an empty section is saved
Fielddata[].elements[].name Typestring Requiredyes DescriptionCRM field name in Bitrix24 format: TITLE, NAME, PHONE, UF_CRM_1234567890 for custom fields. Source for custom fields: GET /v1/userfields/:entity
Fielddata[].elements[].optionFlags Typenumber Requiredno DescriptionField flag: 0 — regular, 1 — customer field. The strings "0" and "1" are accepted too
Fielddata[].elements[].options Typeobject Requiredno DescriptionOptions for a specific field, for example defaultCountry for PHONE or defaultAddressType for ADDRESS
Fieldscope Typestring Requiredno DescriptionLayout scope: P — personal (default), C — common
FielduserId Typenumber Requiredno DescriptionEmployee whose personal layout to write. Defaults to the API key owner. Only meaningful with scope=P. Source: GET /v1/users
FielddealCategoryId Typenumber Requiredno DescriptionDeal pipeline, deals only (entityTypeId=2). Source: GET /v1/categories/2
FieldcategoryId Typenumber Requiredno DescriptionSmart process pipeline, smart processes only. Source: GET /v1/categories/:entityTypeId
FieldleadCustomerType Typenumber Requiredno DescriptionLead type, leads only (entityTypeId=1): 1 — simple, 2 — repeat

Examples

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/crm/card-config/3" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "C",
    "data": [
      {
        "name": "section_1",
        "title": "Personal data",
        "type": "section",
        "elements": [
          { "name": "NAME", "optionFlags": 1 },
          { "name": "LAST_NAME", "optionFlags": 1 }
        ]
      }
    ]
  }'

curl — OAuth application

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/crm/card-config/3" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "C",
    "data": [
      {
        "name": "section_1",
        "title": "Personal data",
        "type": "section",
        "elements": [
          { "name": "NAME", "optionFlags": 1 },
          { "name": "LAST_NAME", "optionFlags": 1 }
        ]
      }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm/card-config/3', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    scope: 'C',
    data: [
      {
        name: 'section_1',
        title: 'Personal data',
        type: 'section',
        elements: [
          { name: 'NAME', optionFlags: 1 },
          { name: 'LAST_NAME', optionFlags: 1 },
        ],
      },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Layout updated:', data.updated)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm/card-config/3', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    scope: 'C',
    data: [
      {
        name: 'section_1',
        title: 'Personal data',
        type: 'section',
        elements: [
          { name: 'NAME', optionFlags: 1 },
          { name: 'LAST_NAME', optionFlags: 1 },
        ],
      },
    ],
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionWrite result
Fielddata.entityTypeId Typenumber DescriptionObject type from the path
Fielddata.scope Typestring DescriptionScope the layout was written to: P or C
Fielddata.updated Typeboolean DescriptionAlways true on success

Response example

JSON 
{
  "success": true,
  "data": {
    "entityTypeId": 3,
    "scope": "C",
    "updated": true
  }
}

Error response example

400 — body without data:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_DATA",
    "message": "data must be a non-empty array of section objects. Each section: { name, title, type: \"section\", elements: [...] }."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ENTITY_TYPE_ID DescriptionentityTypeId in the path is not a positive integer
HTTP400 CodeINVALID_DATA Descriptiondata is missing, is not an array, or is an empty array
HTTP400 CodeINVALID_SCOPE Descriptionscope is not P or C
HTTP400 CodeINVALID_USER_ID DescriptionuserId is not a positive integer
HTTP400 CodeINVALID_DEAL_CATEGORY_ID DescriptiondealCategoryId is not a positive integer
HTTP400 CodeINVALID_CATEGORY_ID DescriptioncategoryId is not a positive integer
HTTP400 CodeINVALID_LEAD_CUSTOMER_TYPE DescriptionleadCustomerType is not 1 or 2
HTTP502 CodeCRM_CARD_CONFIG_SET_FAILED DescriptionBitrix24 did not confirm the write — for example, insufficient permissions or the target scope is unavailable
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the body — for example, a section without name or title, or an element without name. The message is in error.message
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe app key is in read-only mode — writes are blocked
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

For the full list of common API errors, see Errors.

Known specifics

A write fully replaces the layout of a scope. PUT overwrites the entire layout of the chosen scope, not individual sections. To change part of the card, read the current layout via GET, modify the array, and write it back. The layout read back after a write differs from the body in shape — the GET page lists what changes and how to compare.

The type of optionFlags is preserved. A flag sent as a number comes back from GET as a number, and a flag sent as a string comes back as a string.

See also