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

Common layout for all employees

POST /v1/crm/card-config/:entityTypeId/force-common

Removes the personal card layouts of all employees and keeps only the common layout of the chosen scope. After the call all employees see a single card layout. The method does not accept scope or userId — by design it acts on everyone at once.

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)

The body can be empty or {}. Scope refinements are passed as needed.

Field Type Required Description
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 POST "https://vibecode.bitrix24.com/v1/crm/card-config/2/force-common" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "dealCategoryId": 9 }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm/card-config/2/force-common" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "dealCategoryId": 9 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm/card-config/2/force-common', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ dealCategoryId: 9 }),
})

const { success, data } = await res.json()
console.log('Common layout applied to everyone:', data.forced)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm/card-config/2/force-common', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ dealCategoryId: 9 }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionOperation result
Fielddata.entityTypeId Typenumber DescriptionObject type from the path
Fielddata.forced Typeboolean DescriptionAlways true on success

Response example

JSON 
{
  "success": true,
  "data": {
    "entityTypeId": 2,
    "forced": true
  }
}

Error response example

400 — invalid dealCategoryId value:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_DEAL_CATEGORY_ID",
    "message": "dealCategoryId must be a positive integer."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ENTITY_TYPE_ID DescriptionentityTypeId in the path 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_FORCE_COMMON_FAILED DescriptionBitrix24 did not confirm the operation — for example, insufficient permissions or the target scope is unavailable
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not recognize the object type. 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

The method removes the personal layouts of all employees. Personal card settings made by employees for the chosen scope are lost, and everyone switches to the common layout. The action is meant for the initial rollout of a single card layout across the Bitrix24 account.

scope and userId are not accepted. By design the method works on all employees. To write a common layout without removing personal ones, use PUT with scope: "C".

See also