Unbind a placement

POST /v1/placements/unbind

Removes the application from the Bitrix24 interface point where it was registered and detaches that placement code from the application. The call is safe to repeat: a code that is not listed as bound to the application is treated as already detached.

Call preconditions — what is required before binding.

Request fields (body)

Examples

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/placements/unbind \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"placement": "CRM_DEAL_DETAIL_TAB"}'

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/placements/unbind', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ placement: 'CRM_DEAL_DETAIL_TAB' }),
})
const { data } = await res.json()
if (data.alreadyUnbound) {
  console.log('The placement is already unbound from the application')
}

Response fields

Response example

Unbinding a bound placement:

{
  "success": true,
  "data": {
    "placement": "CRM_DEAL_DETAIL_TAB"
  }
}

The placement code is not bound to the application:

{
  "success": true,
  "data": {
    "placement": "CRM_QUOTE_DETAIL_TAB",
    "alreadyUnbound": true
  }
}

Error response example

400 — the placement code is not recognized:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "placement: Placement must be in VALID_PLACEMENTS or match the dynamic CRM pattern CRM_(DYNAMIC|SMART)_<entityTypeId>_(DETAIL_TAB|DETAIL_ACTIVITY|LIST_MENU|LIST_TOOLBAR|DETAIL_TOOLBAR|ACTIVITY_TIMELINE_MENU)"
  }
}

Errors

The full list of common API errors — Errors.

Unbinding runs over ONE transport, not two. The platform selects it based on the account and the application: on a self-hosted account, and on a cloud account switched to the developer key, it is the developer-key transport, otherwise it is the application's OAuth transport. A call never uses both at once, so "removed over one, confirmed over the other" does not happen here.

Waiting for confirmation is being rolled out account by account, so there are two cases:

• While the capability is not enabled on the account — an unconfirmed response does not stop the unbind: the placement is dropped from the application's list and the request returns success. The registration may still remain on the account.
• Once enabled — an unconfirmed response returns 502 BITRIX_UNAVAILABLE and keeps the code in the application's list so that the list does not drift from the account. Retry the request.

The check applies to all three unbind transports alike — the self-hosted one, the cloud developer-key one and the application's OAuth transport. Confirmation means the number of removed registrations that Bitrix24 names; an answer without it is not a confirmation. So once the check is enabled, success on this request means "Bitrix24 confirmed the removal", not "Bitrix24 accepted the call".

Known specifics

• Pass the same handler value as when binding. The URL is normalized to the registered handler by the same rules as when binding, so unbinding finds the registration and removes the placement from the account.

See also

• Placements
• Bound placements
• Available placements
• Bind a placement
• Keys and authorization