#Bind a placement

POST /v1/placements/bind

Registers the application at the selected interface point of a Bitrix24 account — a card tab, a menu item, a chat panel. After the call the point appears in the interface with the title passed in the request.

Call preconditions — what is needed before binding.

#Request fields (body)

#Examples

#curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/placements/bind \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "placement": "CRM_DEAL_DETAIL_TAB",
    "handler": "https://example.com/deal-tab",
    "title": "Deal analytics"
  }'

#JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/placements/bind', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    placement: 'CRM_DEAL_DETAIL_TAB',
    handler: 'https://example.com/deal-tab',
    title: 'Deal analytics',
  }),
})

const { data } = await res.json()
console.log('Registered handler address:', data.handler)

#Response fields

#Response example

The passed handler address was replaced with the platform one:

{
  "success": true,
  "data": {
    "placement": "CRM_DEAL_DETAIL_TAB",
    "handler": "https://vibecode.bitrix24.com/v1/bitrix-handler",
    "title": "Deal analytics",
    "requestedHandler": "https://app-a1b2c3d4.vibecode.bitrix24.com/deal-tab",
    "handlerRewritten": true
  }
}

Repeated binding of the same code:

{
  "success": true,
  "data": {
    "placement": "CRM_DEAL_DETAIL_TAB",
    "handler": "https://example.com/deal-tab",
    "title": "Deal: summary",
    "alreadyBound": true
  }
}

Binding the PAGE_BACKGROUND_WORKER placement without options — the platform substituted the error page address:

{
  "success": true,
  "data": {
    "placement": "PAGE_BACKGROUND_WORKER",
    "handler": "https://example.com/worker",
    "title": "Background scenario",
    "options": {
      "errorHandlerUrl": "https://example.com/worker"
    }
  }
}

#Error response example

400 — a required field is missing in the request body:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Required"
  }
}

#Errors

The full list of common API errors — Errors.

#Known specifics

• Repeated binding re-registers the placement. A call for an already bound code is not rejected: the platform removes the previous registration and binds the placement again, so the new handler address and title take effect. This is the only way to change the title of an already bound placement.
• The technical address of the application server is replaced with the platform one. If handler points to the technical address of the application server, the platform application handler is registered on the account. External addresses are registered unchanged.
• Bitrix24 augments options with its own values. For chat widgets the account stores its own settings alongside the passed ones — display area, role and the extranet flag. They are returned in bound placements even when you did not pass them.
• One title for all interface languages. The title value goes to the account as a single label. A separate translation is not set by this call. In bound placements the langAll field returns the same title for every language.

#See also

• Placements
• Available placements
• Bound placements
• Unbind a placement
• Key data
• Applications