## Create requisite

`POST /v1/requisites`

Creates a new requisite and binds it to a CRM contact or company.

## Required fields

Bitrix24 requires four fields to create a requisite:

| Field | Type | Allowed values | Description |
|------|-----|--------------------|---------|
| `entityTypeId` | number | `3` (contact), `4` (company) | Parent entity type |
| `entityId` | number | any existing ID | Parent entity ID. Lookup: `GET /v1/contacts` or `GET /v1/companies` |
| `presetId` | number | any existing preset ID | ID of the [requisite preset](/docs/entities/requisite-presets) (defines the field set). Source: `GET /v1/requisite-presets` |
| `name` | string | non-empty string | Requisite name. Without it Bitrix24 rejects the creation: 422 `BITRIX_ERROR` "Required field "Name" is not filled" |

## Popular fields

All fields in camelCase. Full list — [`GET /v1/requisites/fields`](./fields.md).

### Common

| Parameter | Type | Default | Description |
|----------|-----|-----------|---------|
| `active` | boolean | `true` | Whether the requisite is active |
| `sort` | number | `500` | Sort order (lower values come first) |
| `code` / `xmlId` / `originatorId` | string | — | External identifiers for synchronization |
| `addressOnly` | boolean | `false` | "Address only" flag (for address directories) |

### Legal entities

| Parameter | Type | Description |
|----------|-----|---------|
| `rqName` | string | Full name |
| `rqCompanyName` | string | Short name |
| `rqCompanyFullName` | string | Full legal-entity name |
| `rqCompanyRegDate` | date | Registration date |
| `rqInn` | string | INN |
| `rqKpp` | string | KPP |
| `rqOgrn` | string | OGRN |
| `rqOgrnip` | string | OGRNIP (for sole proprietors) |
| `rqOkpo` / `rqOkved` / `rqOktmo` | string | Classifiers |
| `rqDirector` | string | Director's full name |
| `rqAccountant` | string | Chief accountant's full name |
| `rqCeoName` / `rqCeoWorkPos` | string | Head's full name and position |
| `rqContact` / `rqEmail` / `rqPhone` / `rqFax` | string | Organization contacts |
| `rqVatPayer` | boolean | VAT payer |
| `rqVatId` | string | VAT ID (foreign) |
| `rqBaseDoc` | string | Document the activity is based on (for example, "Charter") |
| `rqResidenceCountry` | string | Country of registration |

### Individuals

| Parameter | Type | Description |
|----------|-----|---------|
| `rqFirstName` / `rqLastName` / `rqSecondName` | string | First name / Last name / Patronymic |
| `rqIdentDocType` | string | Identity document name |
| `rqIdentDocSer` / `rqIdentDocNum` | string | Document series / number |
| `rqIdentDocDate` | date | Issue date |
| `rqIdentDocIssuedBy` | string | Issued by |
| `rqIdentDocDepCode` | string | Department code |

### International presets

Fields of other countries' presets — `rqEdrpou`, `rqKbe`, `rqRegon`, `rqSiret`, `rqCnpj` — are passed in camelCase, like the other schema fields. Fill them on requisites of the corresponding country preset.

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/requisites" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 4,
    "entityId": 15,
    "presetId": 1,
    "name": "Primary",
    "rqName": "Acme LLC",
    "rqInn": "1234567890",
    "rqKpp": "123456789",
    "rqOgrn": "1234567890123",
    "rqCompanyName": "Acme",
    "rqDirector": "John Smith",
    "rqVatPayer": true
  }'
```

### curl — OAuth app

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/requisites" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 4,
    "entityId": 15,
    "presetId": 1,
    "name": "Primary",
    "rqName": "Acme LLC",
    "rqInn": "1234567890"
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/requisites', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityTypeId: 4,
    entityId: 15,
    presetId: 1,
    name: 'Primary',
    rqName: 'Acme LLC',
    rqInn: '1234567890',
    rqKpp: '123456789',
    rqOgrn: '1234567890123',
    rqCompanyName: 'Acme',
    rqDirector: 'John Smith',
    rqVatPayer: true,
  }),
})

const { success, data } = await res.json()
console.log('Created requisite ID:', data.id)
```

### JavaScript — OAuth app

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/requisites', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityTypeId: 4,
    entityId: 15,
    presetId: 1,
    name: 'Primary',
    rqName: 'Acme LLC',
    rqInn: '1234567890',
  }),
})

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

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | The created requisite |
| `data.id` | number | New record identifier |
| `data.entityTypeId` / `data.entityId` / `data.presetId` | number | Passed values |
| `data.name` | string \| null | Requisite name |
| `data.active` | boolean | Whether the requisite is active (`true` by default) |
| `data.sort` | number | Sort order (`500` by default) |
| `data.createdAt` / `data.updatedAt` | datetime | Equal at creation |
| `data.createdBy` | number | Creator ID |
| `data.modifyBy` | number \| null | `null` right after creation |

The response contains all requisite preset fields in camelCase. Unfilled fields — `null`. Full field list — [Requisite fields](/docs/entities/requisites/fields).

## Response example

HTTP status: `201 Created`

```json
{
  "success": true,
  "data": {
    "id": 42,
    "entityTypeId": 4,
    "entityId": 15,
    "presetId": 1,
    "name": "Primary",
    "active": true,
    "sort": 500,
    "createdAt": "2026-04-19T14:30:00+00:00",
    "updatedAt": "2026-04-19T14:30:00+00:00",
    "createdBy": 1,
    "modifyBy": null,
    "rqName": "Acme LLC",
    "rqInn": "1234567890",
    "rqKpp": "123456789",
    "rqOgrn": "1234567890123",
    "rqCompanyName": "Acme",
    "rqDirector": "John Smith",
    "rqVatPayer": true,
    "rqAccountant": null,
    "rqCeoName": null,
    "rqOkpo": null,
    "rqOkved": null
  }
}
```

## Error response example

400 — `presetId` not specified:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "PRESET_ID field value is not specified"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 422 | `BITRIX_ERROR` | A required field is not specified — Bitrix24 responds with text like `PRESET_ID is not defined or invalid` / "Required field "Name" is not filled" |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the value of one of the fields (for example, a nonexistent `presetId`) |
| 403 | `ACCESS_DENIED` | No access to the parent company/contact |
| 403 | `SCOPE_DENIED` | API key does not have the `crm` scope |
| 401 | `TOKEN_MISSING` | API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Fields not in the preset are ignored.** If you pass a field that is not in the chosen preset, Bitrix24 silently ignores it — no error is raised, but the value is not saved either.

## See also

- [List requisites](/docs/entities/requisites/list) — get existing ones
- [Requisite fields](/docs/entities/requisites/fields) — full list
- [Update requisite](/docs/entities/requisites/update) — change after creation
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch) — bulk creation
- [Limits and optimization](/docs/optimization) — rate limits