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

CRM card layout

Manage field layout in cards of CRM entities: leads, deals, contacts, companies, smart processes. Lets you read the current configuration of sections and fields, overwrite it, reset it to defaults, or force a common layout onto all employees. A layout has no separate numeric id: it is addressed by a set of values — object type entityTypeId, scope scope, employee userId, and refinements extras.

Bitrix24 API: crm.item.details.configuration.* Scope: crm

Get card layout

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

Returns the current layout of card sections and fields for the given CRM object type and scope. Returns an array of sections or null if there was no explicit configuration yet.

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

Query parameters

Parameter Type Description
scope string Layout scope: P — personal (default), C — common
userId number Employee whose personal layout to read. Defaults to the API key owner. Only meaningful with scope=P. Source: GET /v1/users
dealCategoryId number Deal pipeline, deals only (entityTypeId=2). Source: GET /v1/categories/2
categoryId number Smart process pipeline, smart processes only. Source: GET /v1/categories/:entityTypeId
leadCustomerType number Lead type, leads only (entityTypeId=1): 1 — simple, 2 — repeat

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/crm/card-config/2?scope=C&dealCategoryId=9" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/crm/card-config/2?scope=C&dealCategoryId=9" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm/card-config/2?scope=C&dealCategoryId=9', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
if (data === null) {
  console.log('No explicit layout — the default layout is used')
} else {
  console.log('Sections in the layout:', data.length)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm/card-config/2?scope=C&dealCategoryId=9', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
success boolean Always true on success
data array | null Array of layout sections. null — there was no explicit configuration yet
data[].name string Internal section name
data[].title string Displayed section title
data[].type string Always section
data[].elements array Section fields in display order
data[].elements[].name string CRM field name in Bitrix24 format
data[].elements[].optionFlags string Field flag: "0" — regular, "1" — customer field
data[].elements[].options object Options of a specific field, if set

Response example

Layout set explicitly:

JSON 
{
  "success": true,
  "data": [
    {
      "name": "main",
      "title": "About the deal",
      "type": "section",
      "elements": [
        { "name": "TITLE", "optionFlags": "0" },
        { "name": "STAGE_ID", "optionFlags": "0" },
        { "name": "OPPORTUNITY_WITH_CURRENCY", "optionFlags": "0" }
      ]
    }
  ]
}

No explicit configuration for the scope yet:

JSON 
{
  "success": true,
  "data": null
}

Error response example

400 — invalid scope value:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_SCOPE",
    "message": "scope must be \"P\" (personal) or \"C\" (common)."
  }
}

Errors

HTTP Code Description
400 INVALID_ENTITY_TYPE_ID entityTypeId in the path is not a positive integer
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
422 BITRIX_ERROR Bitrix24 did not recognize the object type — for example, for a nonexistent entityTypeId. The message is in error.message
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

data: null differs from an empty layout. null means there was no explicit configuration for the given scope yet, and the card is drawn with the built-in default layout. An empty array [] means an explicitly saved empty layout. The data === null branch is worth handling separately in code.

In the response optionFlags comes as a string. For previously saved layouts the flag value is returned as the string "0" or "1". When writing via PUT the flag is passed as a number.

See also