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
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)

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

Field Type Req. Description
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 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
success boolean Always true on success
data object Operation result
data.entityTypeId number Object type from the path
data.forced boolean Always 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
400 INVALID_ENTITY_TYPE_ID entityTypeId in the path 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_FORCE_COMMON_FAILED Bitrix24 did not confirm the operation — for example, insufficient permissions or the target scope is unavailable
422 BITRIX_ERROR Bitrix24 did not recognize the object type. 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

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