## Available placements

`GET /v1/placements/available`

Returns a reference list of placement codes, grouped by Bitrix24 interface section. This is where you take the code of the placement you need before binding.

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

## Examples

### curl — personal key

```bash
curl https://vibecode.bitrix24.com/v1/placements/available \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

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

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/placements/available', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Groups:', Object.keys(data.groups))
console.log('CRM card tabs:', data.groups['CRM Detail Tabs'].map(p => p.code))
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/placements/available', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
console.log('Total codes accepted on binding:', data.total)
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.groups` | object | Placement groups. The key is the group name, the value is an array of the codes in that group |
| `data.groups[group][].code` | string | Placement code. This value is passed in `placement` on binding |
| `data.groups[group][].title` | string | Human-readable name of the code |
| `data.groups[group][].description` | string | Description of the interface point where the application opens |
| `data.groups[group][].module` | string | Bitrix24 module the code belongs to: `crm`, `tasks`, `user`, `im`, `contact_center`, `main` |
| `data.total` | number | Number of codes accepted on binding |

## Response example

3 of the 12 groups are shown, the rest are arranged the same way.

```json
{
  "success": true,
  "data": {
    "groups": {
      "Menu": [
        {
          "code": "LEFT_MENU",
          "title": "Left Menu",
          "description": "Item in the portal left menu (the \"tab in menu\" placement most callers want)",
          "module": "main"
        }
      ],
      "Chat": [
        {
          "code": "IM_SIDEBAR",
          "title": "Im Sidebar",
          "description": "Chat sidebar panel embed (requires options.iconName)",
          "module": "im"
        },
        {
          "code": "IM_NAVIGATION",
          "title": "Im Navigation",
          "description": "Chat navigation tab embed (requires options.iconName)",
          "module": "im"
        },
        {
          "code": "IM_TEXTAREA",
          "title": "Im Textarea",
          "description": "Chat message-input button embed (requires options.iconName)",
          "module": "im"
        },
        {
          "code": "IM_CONTEXT_MENU",
          "title": "Im Context Menu",
          "description": "Chat message context-menu item embed (options: context, role, extranet)",
          "module": "im"
        }
      ],
      "Contact Center": [
        {
          "code": "CONTACT_CENTER",
          "title": "Contact Center",
          "description": "Tile in the Contact Center section (requires scope contact_center)",
          "module": "contact_center"
        }
      ]
    },
    "total": 55
  }
}
```

## Error response example

401 — the `X-Api-Key` header was not passed:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `INVALID_API_KEY` | Invalid key |

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

## Known specifics

- **`total` is greater than the sum of the group lengths.** In the verified response `total` equals 55, while all groups together hold 44 codes. These are different sets: `total` counts a broader list of codes allowed for binding than the groups show.
- **Smart process codes are not included in the reference list.** In addition to the listed codes, binding accepts codes of the form `CRM_DYNAMIC_<entityTypeId>_DETAIL_TAB` and `CRM_SMART_<entityTypeId>_DETAIL_TAB` with the suffixes `DETAIL_TAB`, `DETAIL_ACTIVITY`, `DETAIL_TOOLBAR`, `LIST_MENU`, `LIST_TOOLBAR`, `ACTIVITY_TIMELINE_MENU`. The numeric part depends on the account, so such codes cannot be listed in advance.
- **A code from the reference list does not yet mean the placement will open on the account.** The account gives the application only the placements the application has rights to — see [what is required before binding](/docs/apps#placements).

## See also

- [Placements](/docs/apps/placements)
- [Bound placements](/docs/apps/placements/list)
- [Bind a placement](/docs/apps/placements/bind)
- [Unbind a placement](/docs/apps/placements/unbind)
- [Scopes](/docs/scopes)