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)

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 reconciles this list with the Bitrix24 account and reports the outcome of that reconciliation in a dedicated field — matched, diverged, or not checked.

Call preconditions — what is required before binding.

Examples

curl — OAuth application

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

JavaScript — OAuth application

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

Response example

A session token was passed and the account returned both bound codes — portalSync equals ok:

{
  "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": "" }
        }
      },
      {
        "placement": "LEFT_MENU",
        "handler": "https://example.com/menu",
        "misbound": false,
        "title": "Sales dashboard",
        "options": [],
        "langAll": {}
      }
    ],
    "portalSync": "ok"
  }
}

The account did not return a bound code — a divergence, and the code is named in missingOnPortal:

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

No session token was passed — no reconciliation happened and handlers is absent:

{
  "success": true,
  "data": {
    "placements": ["LEFT_MENU"],
    "appId": "3d5f7a91-2b4c-4e8f-9a01-6c7d8e9f0a1b",
    "appTitle": "Sales dashboard",
    "portalSync": "unknown",
    "portalSyncReason": "no_oauth_session"
  }
}

Error response example

400 — the request was made with a personal key:

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

Errors

Full list of common API errors — Errors.

Known specifics

• A divergence is determined by portalSync, not by the presence or the length of handlers. An absent handlers field and an empty handlers array are different states. The empty array is returned when the account response was obtained and none of the bound codes were in it. An absent field means the account response was not read. Take the verdict from portalSync in both cases rather than from the array: for an application withdrawn from the catalog an empty handlers comes with unknown, not with drift.
• unknown is not equivalent to ok. The value means that the binding is not confirmed, and it splits into two cases. The account was not read — reasons no_oauth_session, empty_vibe_list, b24_unreachable, and the handlers field is absent from the response. The account was read but its state is not matched against our list — reason unpublished, and then handlers is present.
• An application withdrawn from the catalog is not treated as a divergence. With unpublished the verdict is suppressed: removed placements are the expected consequence of the operation. The account is still queried, because unpublishing does not guarantee that every placement was actually removed, so handlers and the misbound flag stay in the response. What remains in placements after a withdrawal, and how to remove the leftovers, is covered on the operation's own page.
• A divergence is resolved by binding again. The codes from missingOnPortal are returned to the account by calling Bind a placement.
• Codes that are absent from data.placements are not treated as a divergence. The account may hold placements of other applications, and that does not affect portalSync.
• A placement with misbound equal to true is a separate state, not a divergence. The account did return such a placement, so it never lands in missingOnPortal and portalSync stays ok — or unknown with the unpublished reason when the application is withdrawn from the catalog. A call to Bind a placement replaces the technical address of the application server with the platform handler address.

See also

• Placements
• Available placements
• Bind a placement
• Unbind a placement
• Applications
• Key data