## Create requisite

`POST /v1/requisites`

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

## Required fields

Four fields are required 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 in the Bitrix24 interface |

## Popular fields

All fields use camelCase. For the full list, see [`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` | string | — | Symbolic code for external integrations |
| `xmlId` | string | — | External identifier for synchronization |
| `originatorId` | string | — | Source system ID |
| `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` | string | Code in the Russian Classifier of Enterprises and Organizations (OKPO) |
| `rqOkved` | string | Code in the Russian Classifier of Economic Activities (OKVED) |
| `rqOktmo` | string | Code in the Russian Classifier of Municipal Territories (OKTMO) |
| `rqDirector` | string | Director's full name |
| `rqAccountant` | string | Chief accountant's full name |
| `rqCeoName` | string | CEO's full name |
| `rqCeoWorkPos` | string | CEO's position |
| `rqContact` | string | Contact person |
| `rqEmail` | string | Organization email |
| `rqPhone` | string | Organization phone |
| `rqFax` | string | Fax |
| `rqVatPayer` | boolean | VAT payer |
| `rqVatId` | string | VAT ID (for foreign companies) |
| `rqBaseDoc` | string | Basis document for the organization's activity (for example, "Charter") |
| `rqResidenceCountry` | string | Country of registration |

### Individuals

| Parameter | Type | Description |
|----------|-----|---------|
| `rqFirstName` | string | First name |
| `rqLastName` | string | Last name |
| `rqSecondName` | string | Middle name |
| `rqIdentDocType` | string | Identity document name |
| `rqIdentDocSer` | string | Document series |
| `rqIdentDocNum` | string | Document 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 in on requisites that use 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 application

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

```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` | number | Parent entity type from the request |
| `data.entityId` | number | Parent entity ID from the request |
| `data.presetId` | number | Requisite preset ID from the request |
| `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` | datetime | Creation date |
| `data.updatedAt` | datetime | Modification date. Equal to `createdAt` 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 are `null`. For the full field list, see [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

422 — `presetId` not specified:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "PRESET_ID is not defined or invalid."
  }
}
```

## 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` / a message that the required "Name" field is not filled in |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the value of one of the fields (for example, a nonexistent `presetId`) |
| 403 | `BITRIX_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 |

For the full list of common API errors, see [Errors](/docs/errors).

## Known specifics

**A field with an unknown name is ignored.** A name that is not in [`GET /v1/requisites/fields`](/docs/entities/requisites/fields) is discarded without an error. A field from the schema is saved even when the chosen preset does not include it, for example, `rqInn` on a requisite with the `Company` preset.

## See also

- [List requisites](/docs/entities/requisites/list)
- [Requisite fields](/docs/entities/requisites/fields)
- [Update requisite](/docs/entities/requisites/update)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Limits and optimization](/docs/optimization)