For AI agents: markdown of this page — /docs-content-en/apps/placements/available.md documentation index — /llms.txt

Available placements

GET /v1/placements/available

Returns a reference list of placement codes, grouped by Bitrix24 interface section. This is where you take the code of the placement you need before binding.

Call preconditions — what is required before binding.

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/placements/available \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/placements/available \
  -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/placements/available', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Groups:', Object.keys(data.groups))
console.log('CRM card tabs:', data.groups['CRM Detail Tabs'].map(p => p.code))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/placements/available', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
console.log('Total codes accepted on binding:', data.total)

Response fields

Field Type Description
success boolean Always true on success
data.groups object Placement groups. The key is the group name, the value is an array of the codes in that group
data.groups[group][].code string Placement code. This value is passed in placement on binding
data.groups[group][].title string Human-readable name of the code
data.groups[group][].description string Description of the interface point where the application opens
data.groups[group][].module string Bitrix24 module the code belongs to: crm, tasks, user, im, contact_center, main
data.total number Number of codes accepted on binding

Response example

3 of the 12 groups are shown, the rest are arranged the same way.

JSON 
{
  "success": true,
  "data": {
    "groups": {
      "Menu": [
        {
          "code": "LEFT_MENU",
          "title": "Left Menu",
          "description": "Item in the portal left menu (the \"tab in menu\" placement most callers want)",
          "module": "main"
        }
      ],
      "Chat": [
        {
          "code": "IM_SIDEBAR",
          "title": "Im Sidebar",
          "description": "Chat sidebar panel embed (requires options.iconName)",
          "module": "im"
        },
        {
          "code": "IM_NAVIGATION",
          "title": "Im Navigation",
          "description": "Chat navigation tab embed (requires options.iconName)",
          "module": "im"
        },
        {
          "code": "IM_TEXTAREA",
          "title": "Im Textarea",
          "description": "Chat message-input button embed (requires options.iconName)",
          "module": "im"
        },
        {
          "code": "IM_CONTEXT_MENU",
          "title": "Im Context Menu",
          "description": "Chat message context-menu item embed (options: context, role, extranet)",
          "module": "im"
        }
      ],
      "Contact Center": [
        {
          "code": "CONTACT_CENTER",
          "title": "Contact Center",
          "description": "Tile in the Contact Center section (requires scope contact_center)",
          "module": "contact_center"
        }
      ]
    },
    "total": 55
  }
}

Error response example

401 — the X-Api-Key header was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

HTTP Code Description
401 MISSING_API_KEY The X-Api-Key header was not passed
401 INVALID_API_KEY Invalid key

Full list of common API errors — Errors.

Known specifics

  • total is greater than the sum of the group lengths. In the verified response total equals 55, while all groups together hold 44 codes. These are different sets: total counts a broader list of codes allowed for binding than the groups show.
  • Smart process codes are not included in the reference list. In addition to the listed codes, binding accepts codes of the form CRM_DYNAMIC_<entityTypeId>_DETAIL_TAB and CRM_SMART_<entityTypeId>_DETAIL_TAB with the suffixes DETAIL_TAB, DETAIL_ACTIVITY, DETAIL_TOOLBAR, LIST_MENU, LIST_TOOLBAR, ACTIVITY_TIMELINE_MENU. The numeric part depends on the account, so such codes cannot be listed in advance.
  • A code from the reference list does not yet mean the placement will open on the account. The account gives the application only the placements the application has rights to — see what is required before binding.

See also