## 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 |
|------|-----|:-----:|---------|
| `searchQuery` | string | yes | The 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 |
| `options.presetId` | number | yes | Requisite preset ID, an integer greater than zero. The preset sets the lookup country. List: [`GET /v1/requisite-presets`](/docs/entities/requisite-presets/list) |
| `options.typeId` | string | no | What 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`](/docs/entities/requisite-presets/get) returns the preset's country, and [Requisite preset countries](/docs/entities/requisite-presets/countries) lists the country names.

| Preset `countryId` | Allowed `typeId` | Without `typeId` |
|---|---|---|
| `1` | `ITIN`, `BIC` | search by tax ID |
| `14` | `SRO` | search by SRO number |
| other countries | do not pass | search without a specific type |

## Examples

### curl — personal key

```bash
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

```bash
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 |
|------|-----|---------|
| `success` | boolean | `true` on success |
| `data` | array | Directory records found. An empty array means the directory found nothing |
| `data[].title` | string | Name of the organization or bank |
| `data[].subTitle` | string | The number the record was found by, for example `Tax ID 1234567890` |
| `data[].fields` | object | Requisite 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`](/docs/entities/requisites/fields), [`GET /v1/bank-details/fields`](/docs/entities/bank-details/fields) |
| `data[].fields.presetId` | string | Preset ID suggested by the directory. It may differ from `options.presetId` in the request |
| `data[].address` | object | Organization addresses. The key is the address type `typeId`, for example `6` — legal address. Absent when the directory returns no address |
| `data[].address.<typeId>.fieldCollection` | object | Address 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 |
|------|-----|----------|
| 400 | `MISSING_REQUIRED_FIELDS` | `options` is missing or `options.presetId` is not an integer greater than zero |
| 400 | `INVALID_PARAMS` | `searchQuery` does not contain 8–12 consecutive digits, including when `searchQuery` is not passed. Checked before the lookup |
| 400 | `INVALID_PARAMS` | `options.typeId` is not `ITIN`, `BIC` or `SRO` |
| 400 | `INVALID_PARAMS` | `options.typeId` does not match the preset's country |
| 400 | `INVALID_PARAMS` | The number of digits in `searchQuery` does not match the search type, for example 8 digits with `typeId: "BIC"` |
| 400 | `INVALID_PARAMS` | Unknown field in the body or in `options` |
| 404 | `ENTITY_NOT_FOUND` | No preset with this `options.presetId` |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied CRM access to the key's user |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the lookup. The error text is in `error.message` |
| 502 | `BITRIX_RESPONSE_INVALID` | Bitrix24 returned a lookup response in an unexpected format |
| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |
| 401 | `TOKEN_MISSING` | The key has no connection to Bitrix24 |

Full list of common API errors — [Errors](/docs/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`](/docs/entities/requisites/create) 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`](/docs/entities/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`](/docs/entities/addresses/create) 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`](/docs/entities/bank-details/create) 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

- [Create requisite](/docs/entities/requisites/create)
- [Requisite fields](/docs/entities/requisites/fields)
- [Create bank detail](/docs/entities/bank-details/create)
- [Create address](/docs/entities/addresses/create)
- [List requisite presets](/docs/entities/requisite-presets/list)
- [Requisite preset countries](/docs/entities/requisite-presets/countries)
- [Search CRM records](/docs/entities/crm-search/search)