# 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`

## Operations

- [Get layout](./crm-card-config/get.md) — `GET /v1/crm/card-config/:entityTypeId`
- [Set layout](./crm-card-config/set.md) — `PUT /v1/crm/card-config/:entityTypeId`
- [Reset layout](./crm-card-config/reset.md) — `DELETE /v1/crm/card-config/:entityTypeId`
- [Common layout for everyone](./crm-card-config/force-common.md) — `POST /v1/crm/card-config/:entityTypeId/force-common`

## Key fields

| Field | Description |
|------|---------|
| `entityTypeId` | CRM object type in the path:<br>`1` — lead<br>`2` — deal<br>`3` — contact<br>`4` — company<br>`7` — quote<br>`31` — invoice<br>smart process — numeric type ID from [`GET /v1/smart-processes`](/docs/entities/smart-processes), field `entityTypeId` |
| `scope` | Layout scope: `P` — personal (default), `C` — common |
| `userId` | Employee whose personal layout is read or written. Defaults to the API key owner. Only meaningful with `scope=P` |
| `dealCategoryId` | Deal pipeline, deals only (`entityTypeId=2`). Source: [`GET /v1/categories/2`](/docs/entities/categories) |
| `categoryId` | Smart process pipeline, smart processes only. Source: [`GET /v1/categories/:entityTypeId`](/docs/entities/categories) |
| `leadCustomerType` | Lead type, leads only (`entityTypeId=1`): `1` — simple, `2` — repeat |

The `dealCategoryId`, `categoryId`, and `leadCustomerType` values can be passed at the top level of the request or inside the `extras` object. Both options give the same result.

## Layout structure

The `PUT` body contains an array of sections `data`. Each section describes a card block and its fields.

```json
{
  "name": "section_1",
  "title": "Personal data",
  "type": "section",
  "elements": [
    { "name": "NAME", "optionFlags": 1 },
    { "name": "LAST_NAME", "optionFlags": 1 },
    { "name": "PHONE", "optionFlags": 1, "options": { "defaultCountry": "GB" } }
  ]
}
```

| Section field | Description |
|------|---------|
| `name` | Internal section name |
| `title` | Displayed section title |
| `type` | Always `section` |
| `elements` | Array of fields in display order |
| `elements[].name` | CRM field name in Bitrix24 format: `TITLE`, `NAME`, `PHONE`, `UF_CRM_1234567890` for custom fields. Source for custom fields: [`GET /v1/userfields/:entity`](/docs/userfields) |
| `elements[].optionFlags` | Field flag: `0` — regular, `1` — customer field |
| `elements[].options` | Options of a specific field, for example `defaultCountry` for `PHONE` or `defaultAddressType` for `ADDRESS` |

## What to know before you start

1. **`scope` is case-sensitive.** Only `P` (personal) and `C` (common) are allowed. Any other value returns `400 INVALID_SCOPE` rather than falling back to the default.
2. **`userId` is only meaningful with `scope=P`.** For a common layout (`scope=C`) the server accepts it but does not use it.
3. **`data: null` in the response is not an empty layout.** `null` means there was no explicit configuration for the given scope yet, and Bitrix24 shows the built-in default layout. An empty array `[]` means an explicitly saved empty layout.
4. **Field names in `elements[].name` are in Bitrix24 format, UPPER_SNAKE_CASE.** For example `TITLE`, `STAGE_ID`, `OPPORTUNITY_WITH_CURRENCY`, `UF_CRM_1234567890`.
5. **`force-common` does not accept `scope` or `userId`.** The method removes the personal layouts of all employees and keeps the common one.

## Typical scenario

Set up a single contact card for a partner program and apply it to all employees.

1. Add custom fields: [`POST /v1/userfields/contacts`](/docs/userfields).
2. Read the current common layout: [`GET /v1/crm/card-config/3?scope=C`](./crm-card-config/get.md).
3. Write a new common layout with a "Partner" section and the needed fields: [`PUT /v1/crm/card-config/3`](./crm-card-config/set.md) with `scope: "C"`.
4. Reset the personal layouts of employees so everyone sees the single layout: [`POST /v1/crm/card-config/3/force-common`](./crm-card-config/force-common.md).

## Limits

A layout is stored one per scope: `scope` plus `userId` for personal, and `extras` for pipeline or lead type. There is no pagination — `GET` returns the whole layout in a single fetch. For the overall Vibecode API rate limit, see [Limits and optimization](/docs/optimization).

## See also

- [Smart processes](/docs/entities/smart-processes)
- [CRM categories](/docs/entities/categories)
- [CRM custom fields](/docs/userfields)
- [Deals](/docs/entities/deals)
- [Contacts](/docs/entities/contacts)
- [Entity reference](/docs/entities-index)