# Placements

A placement is a point in the Bitrix24 interface where your application opens: a tab in a deal card, a left-menu item, a button on a list toolbar, a panel in a chat. Binding registers the application at such a point on the account, unbinding removes it from there.

**Scope:** `placement` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key` (application authorization key)

## Operations

- [Bound placements](./placements/list.md) — `GET /v1/placements`
- [Available placements](./placements/available.md) — `GET /v1/placements/available`
- [Bind a placement](./placements/bind.md) — `POST /v1/placements/bind`
- [Unbind a placement](./placements/unbind.md) — `POST /v1/placements/unbind`

## What is required before binding

**Application authorization key.** Binding, unbinding and the list of bound placements work only with a `vibe_app_…` key; a personal `vibe_api_…` key returns `400 OAUTH_APP_REQUIRED` on them. The [Available placements](./placements/available.md) reference is an exception — it is open to any valid key. How to obtain an application key — [Keys and authorization](/docs/keys-auth).

**The `placement` scope on the key.** Without it, binding and unbinding return `403 PLACEMENT_SCOPE_MISSING`. Reading the lists does not require this scope.

**A Bitrix24 scope for the placement group.** The account gives the application only the placements the application has rights to: placements of the CRM group require the `crm` scope, chat — `im`, tasks — `task`, Contact Center — `contact_center`. Without the required scope, Bitrix24 replies that the placement was not found, and binding returns `502 BITRIX_UNAVAILABLE`. Scopes are set when the application is created and are changed by [updating the application](/docs/apps/update).

**A session token on some accounts.** Some accounts perform binding and unbinding with the application authorization key alone, others additionally require the `Authorization: Bearer` header with a session token, and without it return `401 SESSION_REQUIRED`. Send the token together with the key — then the call succeeds in both cases.

**A condition on the Bitrix24 side.** Binding requires the account to be on a commercial Bitrix24 plan. The exact condition is returned in advance by the `placements.bindPrerequisite` block in the [key data](/docs/keys-auth/me), which also lists the codes binding will reply with when the condition is not met.

## Placement groups

| Group | Where the application appears |
|--------|---------------------------|
| CRM Lists | Menu on the list pages of leads, contacts, companies, deals, quotes, invoices |
| CRM List Toolbars | Button toolbar on the same list pages |
| CRM Detail Tabs | Tab in a CRM item card |
| CRM Detail Toolbars | Dropdown menu item in the card toolbar |
| CRM Detail Activity | Activity button in the card |
| CRM Activity Timeline | Action in the timeline menu |
| Tasks | Context menu of the task list |
| User Profile | Menu and button toolbar in the employee profile |
| Menu | Left-menu item of the account |
| Universal | Link handler and background script on every page |
| Chat | Panel, navigation tab, input-field button and message context-menu item in a chat |
| Contact Center | Tile in the Contact Center section |

The reference is the same for all accounts and is extended over time, so read the list of codes with a live [Available placements](./placements/available.md) call instead of hardcoding it. What does depend on the account is whether Bitrix24 makes a particular placement available to the application — that is decided by the scopes granted to the application.

## Typical scenario

The application adds a tab to a deal card.

1. `GET /v1/placements/available` — find the code of the placement you need; for a tab in a deal card it is `CRM_DEAL_DETAIL_TAB`.
2. `POST /v1/placements/bind` with the body `{ placement, handler, title }` — the `title` value becomes the tab label on the account.
3. `GET /v1/placements` with a session token — make sure the placement is listed as bound and the handler address matches the expected one.
4. `POST /v1/placements/unbind` — remove the tab when the feature is no longer needed.

## See also

- [Applications](/docs/apps)
- [Publishing an application](/docs/apps/publish)
- [Key data](/docs/keys-auth/me)
- [Scopes](/docs/scopes)
- [Application runtime inside the account](/docs/infra/app-runtime)