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.

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

A personal key vibe_api_… receives 400 OAUTH_APP_REQUIRED. Use an OAuth application key vibe_app_….

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 — this is a divergence, and the code is listed 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"]
  },
  "warnings": [
    "Placements LEFT_MENU are listed as bound but were not returned by the Bitrix24 account; re-bind via POST /v1/placements/bind to restore them on the portal."
  ]
}

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

• unknown is not equivalent to ok. This value means the binding is unconfirmed and can occur in two cases. If the account response was not read, the reason is no_oauth_session, empty_vibe_list, or b24_unreachable, and the handlers field is absent from the response. If the account response was read but its state is not compared with our list, the reason is unpublished, and 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