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 required 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 URL:', data.handler)

Response fields

Response example

The passed handler URL 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 URL:

{
  "success": true,
  "data": {
    "placement": "PAGE_BACKGROUND_WORKER",
    "handler": "https://example.com/worker",
    "title": "Background worker",
    "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

• A placement can require a scope on the Bitrix24 application, not on the key. Bitrix24 offers an embedding point only to applications whose grant covers the module that placement belongs to: task card tabs need the tasks scope, profile menu items need the users scope, and so on. The scope each code requires is returned per placement in available placements as requiredScope, and the summary of the gates in key self-description as placements.bindPrerequisite. An application's scopes are fixed when it is installed: they cannot be changed on a live application — re-issue the authorization key instead.
• The platform fills in the options a placement requires. A chat widget's icon and the background worker's error page URL are filled in when you omit them. The list of filled-in fields is returned as optionsDefaulted.
• 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 URL and title take effect. This is the only way to change the title of an already bound placement.
• The technical URL of the application server is replaced with the platform one. If handler points to the technical URL of the application server, the platform application handler is registered on the account. External URLs 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.
• A successful response means the account accepted the write, not that the record stayed in place. The actual account state at any moment after binding is checked with the portalSync field in bound placements: ok — the account returned the code, drift — the code is listed in Vibecode but the account does not have it.
• One placement can be occupied by several applications. Bitrix24 distinguishes registrations by application, so binding the same code from a second application of the account is not rejected and does not remove the first registration. Sharing the same platform handler URL across applications does not change that.

See also

• Placements
• Available placements
• Bound placements
• Unbind a placement
• Key self-description
• Applications