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 placement appears in the interface under the title passed in the request.

Call preconditions — what is required before binding.

On a cloud account, the platform first uses the transport selected for that account. If Bitrix24 rejects the developer key with a credential-only HTTP 401 and the app key is accompanied by a live Authorization: Bearer session, the bind is retried through OAuth automatically. A response that explicitly names a non-credential cause, such as an account-policy refusal or a missing scope, remains authoritative at every HTTP status and is never retried through OAuth. A successful response means one of these independent channels confirmed the write.

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

Rebinding 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

`B24_ACCESS_DENIED` fields

These fields are diagnostics, not a selector for another client-side transport attempt: the platform has already performed or declined the OAuth fallback. Clients branch on the outer error.code; the set of internal Bitrix24 codes is not a stable API enum.

The full list of common API errors — Errors.

The error table is segment-specific and documents the codes of this deployment. On the international surface, an account-access refusal is represented by INT_TARIFF_REQUIRED; do not copy codes from another deployment segment into a shared client enum.

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.
• Rebinding 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.
• LEFT_MENU adds a second menu item. The application appears in the account menu as soon as it is created. Binding LEFT_MENU adds a second item with its own URL rather than replacing the first one. To remove the extra item, unbind the LEFT_MENU code — the item that appeared at creation stays in place.
• A credential-only developer-key HTTP 401 does not mean a different plan is required. It rejects that credential channel. With a live OAuth session the platform tries the independent channel; without one it returns B24_ACCESS_DENIED with the safe Bitrix24 machine code and status. A named account-policy or missing-scope refusal remains authoritative regardless of HTTP status and never enters the OAuth fallback.
• 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. This call does not set a separate translation. 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. Check the actual account state at any moment after binding 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 on the same 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