For AI agents: markdown of this page — /docs-content-en/apps/placements/unbind.md documentation index — /llms.txt

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 prerequisites — what is required before binding.

Request fields (body)

Field Type Req. Description
placement string yes Placement code. Codes bound to the application — Bound placements, the full list — Available placements
handler string no Handler URL whose registration must be removed. Without this field all registrations of the application on the specified placement are removed

Examples

curl — OAuth application

Terminal 
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

javascript 
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

Field Type Description
success boolean true on successful execution
data.placement string Placement code that was unbound
data.alreadyUnbound boolean Present with the value true when the specified code was not listed as bound to the application

Response example

Unbinding a bound placement:

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

The placement code is not bound to the application:

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

Error response example

400 — the placement code is not recognized:

JSON 
{
  "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

HTTP Code Description
400 OAUTH_APP_REQUIRED The request was made with a personal key vibe_api_…. Unbinding is available only to an application authorization key
400 VALIDATION_ERROR The body failed validation: the placement code is not recognized or handler is not a URL
400 APP_NOT_REGISTERED The application has no Bitrix24 client identifier, so there is no registration to remove
400 BOX_NO_DEVELOPER_KEY The account is self-hosted and the application author has no developer key configured
401 SESSION_REQUIRED The Authorization: Bearer header with a session token was not passed where it is required
403 PLACEMENT_SCOPE_MISSING The key has no placement scope
403 WRITE_BLOCKED_READONLY_KEY The key works in read-only mode. Switch the mode in the API Keys section
404 APP_NOT_FOUND No application is bound to the key
413 FST_ERR_CTP_BODY_TOO_LARGE The body was not sent as JSON and is longer than one byte. Set the Content-Type: application/json header
415 FST_ERR_CTP_INVALID_MEDIA_TYPE The body was not sent as JSON and equals one byte — the same cause, a different validation branch
502 BITRIX_UNAVAILABLE Bitrix24 rejected the registration removal

The full list of common API errors — Errors.

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