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 an array of sections data — each section describes a card block and its fields.

Path parameter

Parameter Type Description
entityTypeId number CRM 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 Req. Description
data array yes Array of layout sections in display order
data[].name string yes Internal section name
data[].title string yes Displayed section title
data[].type string yes Always section
data[].elements array yes Section fields in display order
data[].elements[].name string yes CRM field name in Bitrix24 format: TITLE, NAME, PHONE, UF_CRM_1234567890 for custom fields. Source for custom fields: GET /v1/userfields/:entity
data[].elements[].optionFlags number no Field flag: 0 — regular, 1 — customer field
data[].elements[].options object no Options of a specific field, for example defaultCountry for PHONE or defaultAddressType for ADDRESS
scope string no Layout scope: P — personal (default), C — common
userId number no Employee whose personal layout to write. Defaults to the API key owner. Only meaningful with scope=P. Source: GET /v1/users
dealCategoryId number no Deal pipeline, deals only (entityTypeId=2). Source: GET /v1/categories/2
categoryId number no Smart process pipeline, smart processes only. Source: GET /v1/categories/:entityTypeId
leadCustomerType number no Lead 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
success boolean Always true on success
data object Write result
data.entityTypeId number Object type from the path
data.scope string Scope the layout was written to: P or C
data.updated boolean Always 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
400 INVALID_ENTITY_TYPE_ID entityTypeId in the path is not a positive integer
400 INVALID_DATA data is missing, is not an array, or is an empty array
400 INVALID_SCOPE scope is not P or C
400 INVALID_USER_ID userId is not a positive integer
400 INVALID_DEAL_CATEGORY_ID dealCategoryId is not a positive integer
400 INVALID_CATEGORY_ID categoryId is not a positive integer
400 INVALID_LEAD_CUSTOMER_TYPE leadCustomerType is not 1 or 2
502 CRM_CARD_CONFIG_SET_FAILED Bitrix24 did not confirm the write — for example, insufficient permissions or the target scope is unavailable
422 BITRIX_ERROR Bitrix24 rejected the body — for example, a section without name or title, an element without name. The message is in error.message
403 WRITE_BLOCKED_READONLY_KEY The app key is in read-only mode — writes are blocked
403 SCOPE_DENIED The API key does not have the crm scope
401 TOKEN_MISSING The API key has no configured tokens

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

Known specifics

A write fully replaces the scope layout. 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 optionFlags flag in the body is passed as a number. On write a number (0 or 1) is used. In the GET response for a saved layout the same flag is returned as a string.

See also