## Bound placements

`GET /v1/placements`

Returns the placements that are listed as bound for the application. When a session token is passed together with the application key, Vibecode additionally reconciles this list with the Bitrix24 account.

Call preconditions — [what is required before binding](/docs/apps#placements).

## Examples

### curl — OAuth application

```bash
curl https://vibecode.bitrix24.com/v1/placements \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/placements', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
console.log('Confirmed by the account:', data.handlers)
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.placements` | string[] | Placement codes bound by the application |
| `data.appId` | string | Application identifier. List of applications — `GET /v1/apps` |
| `data.appTitle` | string | Application name |
| `data.handlers` | array | Handler data received from the account. The field is optional — it is returned only when a session token is passed |
| `data.handlers[].placement` | string | Placement code |
| `data.handlers[].handler` | string | Handler address registered on the account |
| `data.handlers[].misbound` | boolean | `true` when the handler is registered to the technical address of the application server. Such a placement will not pass authorization inside Bitrix24 |
| `data.handlers[].title` | string | Placement caption on the account |
| `data.handlers[].options` | array \| object | Placement settings. An empty array when there are no settings |
| `data.handlers[].langAll` | object | Placement captions by language. The key is the language code, the values are `TITLE`, `DESCRIPTION`, `GROUP_NAME` |
| `warnings` | string[] | Appears when at least one placement has `misbound` equal to `true` |

## Response example

A session token was passed and the account confirmed the tab in the deal card:

```json
{
  "success": true,
  "data": {
    "placements": ["LEFT_MENU", "CRM_DEAL_DETAIL_TAB"],
    "appId": "3d5f7a91-2b4c-4e8f-9a01-6c7d8e9f0a1b",
    "appTitle": "Sales dashboard",
    "handlers": [
      {
        "placement": "CRM_DEAL_DETAIL_TAB",
        "handler": "https://example.com/tab",
        "misbound": false,
        "title": "Deal documents",
        "options": [],
        "langAll": {
          "en": { "TITLE": "Deal documents", "DESCRIPTION": "", "GROUP_NAME": "" },
          "ru": { "TITLE": "Deal documents", "DESCRIPTION": "", "GROUP_NAME": "" }
        }
      }
    ]
  }
}
```

The account returned none of the bound codes — `handlers` is returned empty:

```json
{
  "success": true,
  "data": {
    "placements": ["LEFT_MENU"],
    "appId": "3d5f7a91-2b4c-4e8f-9a01-6c7d8e9f0a1b",
    "appTitle": "Sales dashboard",
    "handlers": []
  }
}
```

## Error response example

400 — the request was made with a personal key:

```json
{
  "success": false,
  "error": {
    "code": "OAUTH_APP_REQUIRED",
    "message": "Placement management is only available for OAuth app keys"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `OAUTH_APP_REQUIRED` | The request was made with a personal `vibe_api_` key |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `INVALID_API_KEY` | Invalid key |
| 404 | `APP_NOT_FOUND` | No application is linked to the key |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **An empty `handlers` with a non-empty `placements` indicates a discrepancy.** The placement is listed as bound in Vibecode, but the account did not return it: there is no such placement on the Bitrix24 side. It is restored by calling [Bind a placement](/docs/apps/placements/bind) again.
- **The `handlers` field may be absent even when a session token is passed** — when the application has no bound placements or the response from the account could not be obtained. The absence of the field does not mean there are no placements — check against `data.placements`.
- **A placement with `misbound` equal to `true` is fixed by binding it again.** A call to [Bind a placement](/docs/apps/placements/bind) replaces the technical address of the application server with the platform handler address.

## See also

- [Placements](/docs/apps/placements)
- [Available placements](/docs/apps/placements/available)
- [Bind a placement](/docs/apps/placements/bind)
- [Unbind a placement](/docs/apps/placements/unbind)
- [Applications](/docs/apps)
- [Key data](/docs/keys-auth/me)