For AI agents: markdown of this page — /docs-content-en/entities/requisite-links/register.md documentation index — /llms.txt

Register a requisite link

POST /v1/requisite-links

Creates or updates a requisite link to an owner entity. If a link for the given (entityTypeId, entityId) pair already exists, it is overwritten.

Request fields (body)

Field Type Required Description
entityTypeId number yes Link owner type: 2 — deal, 31 — invoice. List: GET /v1/requisite-links/fields
entityId number yes Owner entity ID. Source: GET /v1/deals or GET /v1/invoices
requisiteId number yes Client requisite ID. Source: GET /v1/requisites. Pass 0 to skip linking
bankDetailId number yes Client bank requisite ID. Source: GET /v1/bank-details. Pass 0 to skip linking
mcRequisiteId number yes Your company's requisite ID. Source: GET /v1/requisites. Pass 0 to skip linking
mcBankDetailId number yes Your company's bank requisite ID. Source: GET /v1/bank-details. Pass 0 to skip linking

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/requisite-links" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 2,
    "entityId": 3773,
    "requisiteId": 45,
    "bankDetailId": 12,
    "mcRequisiteId": 3,
    "mcBankDetailId": 7
  }'

curl — OAuth app

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/requisite-links" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 2,
    "entityId": 3773,
    "requisiteId": 45,
    "bankDetailId": 12,
    "mcRequisiteId": 3,
    "mcBankDetailId": 7
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/requisite-links', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityTypeId: 2,
    entityId: 3773,
    requisiteId: 45,
    bankDetailId: 12,
    mcRequisiteId: 3,
    mcBankDetailId: 7,
  }),
})

const { success, data } = await res.json()
console.log('Registered link for entityId:', data.entityId)

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/requisite-links', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityTypeId: 2,
    entityId: 3773,
    requisiteId: 45,
    bankDetailId: 12,
    mcRequisiteId: 3,
    mcBankDetailId: 7,
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data object Registration result
data.entityTypeId number The entity type that was passed
data.entityId number The entity ID that was passed
data.registered boolean Always true on success

Response example

HTTP status: 201 Created

JSON 
{
  "success": true,
  "data": {
    "entityTypeId": 2,
    "entityId": 3773,
    "registered": true
  }
}

Error response example

400 — required fields missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_FIELDS",
    "message": "POST /v1/requisite-links requires entityTypeId, entityId, requisiteId, bankDetailId, mcRequisiteId and mcBankDetailId in the body (use 0 for ids you don't want to link). Missing: requisiteId, bankDetailId, mcRequisiteId, mcBankDetailId. Raw UPPER_SNAKE names from /v1/requisite-links/fields (ENTITY_TYPE_ID, …) are accepted too."
  }
}

Errors

HTTP Code Description
400 MISSING_FIELDS One or more of the six required fields not provided
422 BITRIX_ERROR Bitrix24 rejected the operation — for example, the requisite does not belong to the deal's client
403 SCOPE_DENIED API key lacks the crm scope. Required message: This endpoint requires 'crm' scope
401 TOKEN_MISSING API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Pass 0 for unused links. All six fields are required in the request body. If a requisite or bank requisite should not be linked, pass 0.

The requisite must belong to the deal's client. To register a link for a deal, it must have a contact or company selected that owns the requisite. Without a selected client, the link returns 422 BITRIX_ERROR.

See also