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

Create a CRM card layout

POST /v1/crm/card-layouts/:entityType

Create a named set of CRM card sections and fields for the selected audience.

These methods are rolling out — introduced in crm 26.1700.0. Cloud availability also depends on Bitrix24 enabling this capability. Until it is enabled for your Bitrix24 account, the API returns 422 METHOD_NOT_YET_AVAILABLE with error.release.

Requires crm scope. Writes require READWRITE.

Parameters

Parameter Type Required Default Description
ParameterentityType (path) Typestring Requiredyes Default— DescriptionType from the section index.

Request body fields

Field Type Required Description
FieldcategoryId Typeinteger Requiredyes DescriptionCategory from GET /v1/categories, 0 is accepted.
Fieldfields Typeobject Requiredyes DescriptionWritable fields.
Fieldfields.name Typestring Requiredyes DescriptionLayout name.
Fieldfields.configuration Typeobject[] Requiredyes DescriptionSections {name,title,elements}. Elements {name,optionFlags?,options?}, where options is an object.
Fieldfields.audience Typeobject[] Requiredyes DescriptionAudience {type,id}. Bitrix24 checks types and permissions. Employee IDs come from the user list.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm/card-layouts/deal" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"categoryId": 0, "fields": {"name": "VIBE-PROBE", "configuration": [{"name": "main", "title": "VIBE-PROBE", "elements": [{"name": "TITLE"}]}], "audience": [{"type": "user", "id": 1}]}}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm/card-layouts/deal" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"categoryId": 0, "fields": {"name": "VIBE-PROBE", "configuration": [{"name": "main", "title": "VIBE-PROBE", "elements": [{"name": "TITLE"}]}], "audience": [{"type": "user", "id": 1}]}}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm/card-layouts/deal', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"categoryId": 0, "fields": {"name": "VIBE-PROBE", "configuration": [{"name": "main", "title": "VIBE-PROBE", "elements": [{"name": "TITLE"}]}], "audience": [{"type": "user", "id": 1}]}}),
});
console.log(await res.json());

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm/card-layouts/deal', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"categoryId": 0, "fields": {"name": "VIBE-PROBE", "configuration": [{"name": "main", "title": "VIBE-PROBE", "elements": [{"name": "TITLE"}]}], "audience": [{"type": "user", "id": 1}]}}),
});
console.log(await res.json());

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue
Fielddata.id Typenumber DescriptionNumeric ID of the created layout.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 11
  }
}

Error response example

400 — category omitted:

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

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionCategory or required body fields missing.
HTTP400 CodeINVALID_PARAMS DescriptionUnsupported entity selector or malformed parameters.
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown query parameter.
HTTP401 CodeMISSING_API_KEY DescriptionAPI key missing.
HTTP401 CodeTOKEN_MISSING DescriptionBitrix24 credentials missing.
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks crm scope.
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key blocks writes to Bitrix24.
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionCapability disabled or method unavailable. error.release names the release.
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refusal. Original code in error.b24Code, text in error.message.
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionNo valid response from Bitrix24. After a write error, reread before retrying.

Common errors: Errors.

Known specifics

Supplied arrays replace their previous contents. Bitrix24 may refuse an empty array as a missing field, and the original refusal is included in the response.

See also