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

Requisites

CRM requisite management: create, get, update, delete, filter. Requisites are always tied to a contact or company and hold legal information (name, tax IDs, director, accountant, etc.).

Bitrix24 API: crm.requisite.* Scope: crm

Look up requisites by number

POST /v1/requisites/lookup

Finds an organization's requisites by tax ID or a bank's details by bank code in a Bitrix24 external directory and returns fields ready for creating a requisite. The country and the directory are set by the requisite preset in options.presetId.

Request fields (body)

Field Type Required Description
FieldsearchQuery Typestring Requiredyes DescriptionThe number to look up. The string must contain 8–12 consecutive digits: tax ID — 10–12 digits, bank code — 9 digits, number in the register of self-regulatory organizations (SRO) — 8 digits
Fieldoptions.presetId Typenumber Requiredyes DescriptionRequisite preset ID, an integer greater than zero. The preset sets the lookup country. List: GET /v1/requisite-presets
Fieldoptions.typeId Typestring Requiredno DescriptionWhat to look up: ITIN — tax ID, BIC — bank code, SRO — number in the SRO register. The type must match the preset's country, see the table below

The body and options accept no other fields: an unknown field is rejected with 400 INVALID_PARAMS.

The search type depends on the preset's countryId. GET /v1/requisite-presets/:id returns the preset's country, and Requisite preset countries lists the country names.

Preset countryId Allowed typeId Without typeId
Preset countryId1 Allowed typeIdITIN, BIC Without typeIdsearch by tax ID
Preset countryId14 Allowed typeIdSRO Without typeIdsearch by SRO number
Preset countryIdother countries Allowed typeIddo not pass Without typeIdsearch without a specific type

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/requisites/lookup" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchQuery": "1234567890",
    "options": { "presetId": 1 }
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/requisites/lookup" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchQuery": "1234567890",
    "options": { "presetId": 1 }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/requisites/lookup', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    searchQuery: '1234567890',
    options: { presetId: 1 },
  }),
})

const { data } = await res.json()
for (const item of data) console.log(item.title, item.fields.rqInn)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/requisites/lookup', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    searchQuery: '1234567890',
    options: { presetId: 1 },
  }),
})

const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typearray DescriptionDirectory records found. An empty array means the directory found nothing
Fielddata[].title Typestring DescriptionName of the organization or bank
Fielddata[].subTitle Typestring DescriptionThe number the record was found by, for example Tax ID 1234567890
Fielddata[].fields Typeobject DescriptionRequisite fields in camelCase, for example rqInn, rqKpp, rqCompanyName. For a bank — bank detail fields: rqBik, rqCorAccNum, rqSwift. The set depends on the country and the directory. Field schemas: GET /v1/requisites/fields, GET /v1/bank-details/fields
Fielddata[].fields.presetId Typestring DescriptionPreset ID suggested by the directory. It may differ from options.presetId in the request
Fielddata[].address Typeobject DescriptionOrganization addresses. The key is the address type typeId, for example 6 — legal address. Absent when the directory returns no address
Fielddata[].address.<typeId>.fieldCollection Typeobject DescriptionAddress parts under numeric codes, for example 50 — postal code, 100 — country, 200 — city, 410 — street and building

Response example

Organization lookup by tax ID with a preset of a country that has a directory, countryId 1:

JSON 
{
  "success": true,
  "data": [
    {
      "title": "Acme LLC",
      "subTitle": "Tax ID 1234567890",
      "fields": {
        "rqInn": "1234567890",
        "rqKpp": "123456789",
        "rqOgrn": "1234567890123",
        "rqCompanyName": "Acme",
        "rqCompanyFullName": "Acme LLC",
        "presetId": "1",
        "rqCompanyRegDate": "06/20/1991",
        "rqDirector": "John Smith"
      },
      "address": {
        "6": {
          "id": 0,
          "latitude": "",
          "longitude": "",
          "languageId": "en",
          "fieldCollection": {
            "50": "10001",
            "100": "USA",
            "200": "New York",
            "410": "1 Main St."
          }
        }
      }
    }
  ]
}

Bank lookup by bank code, request body {"searchQuery": "123456789", "options": {"presetId": 1, "typeId": "BIC"}}:

JSON 
{
  "success": true,
  "data": [
    {
      "title": "Acme Bank",
      "subTitle": "Bank code 123456789",
      "fields": {
        "name": "Acme Bank",
        "rqBankName": "Acme Bank",
        "rqBik": "123456789",
        "rqBankAddr": "1 Main St., New York, 10001",
        "rqCorAccNum": "12345678901234567890",
        "rqSwift": "CHASUS33"
      }
    }
  ]
}

Error response example

400 — the search type does not match the preset's country:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "typeId is not supported for this preset country"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionoptions is missing or options.presetId is not an integer greater than zero
HTTP400 CodeINVALID_PARAMS DescriptionsearchQuery does not contain 8–12 consecutive digits, including when searchQuery is not passed. Checked before the lookup
HTTP400 CodeINVALID_PARAMS Descriptionoptions.typeId is not ITIN, BIC or SRO
HTTP400 CodeINVALID_PARAMS Descriptionoptions.typeId does not match the preset's country
HTTP400 CodeINVALID_PARAMS DescriptionThe number of digits in searchQuery does not match the search type, for example 8 digits with typeId: "BIC"
HTTP400 CodeINVALID_PARAMS DescriptionUnknown field in the body or in options
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo preset with this options.presetId
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied CRM access to the key's user
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the lookup. The error text is in error.message
HTTP502 CodeBITRIX_RESPONSE_INVALID DescriptionBitrix24 returned a lookup response in an unexpected format
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no connection to Bitrix24

Full list of common API errors — Errors.

Known specifics

An empty data array does not always mean the organization does not exist. For a preset of a country without a directory, for example Germany or Kazakhstan, the response is 200 with an empty array and no error. The built-in Company and Person presets of an international Bitrix24 account have countryId 122: lookup runs for them without a search type and can return an empty array.

How to create a requisite from the result. Pass the fields from data[].fields to POST /v1/requisites together with entityTypeId, entityId, name and the same presetId that was in options.presetId. Do not take presetId from the response: the directory may suggest a different preset. Check the fields against GET /v1/requisites/fields: the directory may return fields that the preset does not include.

The address is created separately. POST /v1/requisites does not accept an address. Create it with POST /v1/addresses using the typeId from the data[].address key, entityTypeId: 8 and the id of the created requisite.

A lookup by bank code returns a bank detail. Create it with POST /v1/bank-details using the fields from data[].fields and the entityId of the owner requisite.

A read-only key is accepted. The lookup writes nothing to the Bitrix24 account.

See also