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

Search requisite links

POST /v1/requisite-links/search

Search requisite links with filters and auto-pagination. Equivalent to GET /v1/requisite-links, but the parameters are passed in the request body — more convenient for complex filters with many conditions and for assembling requests programmatically.

Request fields (body)

Parameter Type Default Description
filter object — Filtering. Allowed keys: entityTypeId, entityId, requisiteId, bankDetailId, mcRequisiteId, mcBankDetailId. Comparison operators ($gt/$gte/$lt/$lte) and set operators ($in/$nin) are supported. Logical $or/$and are not supported.
Filtering syntax. Example: { "entityTypeId": 2, "entityId": 3773 }
sort string — Sort field — one of the filter keys
order string | object asc Direction for sort (asc/desc), or the { "field": "asc|desc" } form
limit number 50 Number of records, up to 5000
offset number 0 Skip N records

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/requisite-links/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityTypeId": 2, "requisiteId": 45 },
    "limit": 20
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/requisite-links/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityTypeId": 2, "requisiteId": 45 },
    "limit": 20
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/requisite-links/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityTypeId: 2, requisiteId: 45 },
    limit: 20,
  }),
})

const { success, data } = await res.json()
console.log('Found:', data.length)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/requisite-links/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityTypeId: 2, requisiteId: 45 },
    limit: 20,
  }),
})

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

Other scenarios

The blocks below are request bodies.

All links for a specific deal:

JSON 
{ "filter": { "entityTypeId": 2, "entityId": 3773 } }

All links for a specific requisite — which entities the requisite with ID 45 is attached to:

JSON 
{ "filter": { "requisiteId": 45 } }

Only deals whose client requisite is actually attached:

JSON 
{
  "filter": { "entityTypeId": 2, "requisiteId": { "$gt": 0 } },
  "limit": 100
}

Response fields

Field Type Description
success boolean Always true on success
data array Array of links
data[].entityTypeId number Owner type. Values — Link fields
data[].entityId number Owner ID
data[].requisiteId number Client requisite ID, 0 — not linked. Source: GET /v1/requisites
data[].bankDetailId number Client bank detail ID, 0 — not linked. Source: GET /v1/bank-details
data[].mcRequisiteId number Your company's requisite ID, 0 — not linked
data[].mcBankDetailId number Your company's bank detail ID, 0 — not linked
meta.total number How many records matched the filter
meta.hasMore boolean Whether more records exist beyond limit

The meta fields sit next to data, not inside it. Page through the results using meta.hasMore: a data length equal to limit does not rule out the last page.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "entityTypeId": 2,
      "entityId": 3773,
      "requisiteId": 45,
      "bankDetailId": 0,
      "mcRequisiteId": 0,
      "mcBankDetailId": 0
    },
    {
      "entityTypeId": 2,
      "entityId": 3913,
      "requisiteId": 225,
      "bankDetailId": 0,
      "mcRequisiteId": 0,
      "mcBankDetailId": 0
    }
  ],
  "meta": {
    "total": 40,
    "hasMore": true
  }
}

Error response example

400 — top-level logical operator:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_FILTER_OPERATOR",
    "message": "'$or' is not supported. OR/AND logic cannot be expressed in a single requisite-links filter. For same-field set membership use { field: { $in: [v1, v2] } }; for cross-field OR run parallel requests. AND is the default — combine conditions as sibling keys in one filter object."
  }
}

Errors

HTTP Code Description
400 INVALID_FILTER_OPERATOR Top-level logical operator $or or $and
400 MISSING_ENTITY_TYPE_ID Filtering by entityId without entityTypeId
400 UNKNOWN_FILTER_FIELD Unknown filter field; the message lists the allowed ones
400 UNKNOWN_SORT_FIELD Unknown sort field; the message lists the allowed ones
403 SCOPE_DENIED API key lacks the crm scope
401 TOKEN_MISSING API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

A link in the result does not mean an attachment exists. A row where all four identifiers equal 0 is a registered link with no attachment at all. To select only real attachments, add the condition { "requisiteId": { "$gt": 0 } }.

Set membership on a single field instead of $or. Several values of one field are specified with $in — for example { "entityTypeId": { "$in": [2, 31] } }. Conditions on different fields inside one filter are combined with AND.

See also