[{"data":1,"prerenderedAt":15},["ShallowReactive",2],{"docs-entities\u002Fperson-types":3,"docs-tabs-entities\u002Fperson-types":6},{"content":4,"lastmod":5},"# Payer types\n\nA list of payer types for an online store. The type ID is passed in the `personTypeId` field of an order or order property.\n\nTypes with the codes `CRM_CONTACT` and `CRM_COMPANY` are protected from deletion. Include `name` whenever you update a type, even if you are only changing other fields.\n\nBitrix24 API: `sale.persontype.*`\nScope: `sale`\n\n## Operations\n\n- [Create a payer type](.\u002Fperson-types\u002Fcreate.md) — `POST \u002Fv1\u002Fperson-types`\n- [List payer types](.\u002Fperson-types\u002Flist.md) — `GET \u002Fv1\u002Fperson-types`\n- [Get a payer type](.\u002Fperson-types\u002Fget.md) — `GET \u002Fv1\u002Fperson-types\u002F:id`\n- [Update a payer type](.\u002Fperson-types\u002Fupdate.md) — `PATCH \u002Fv1\u002Fperson-types\u002F:id`\n- [Delete a payer type](.\u002Fperson-types\u002Fdelete.md) — `DELETE \u002Fv1\u002Fperson-types\u002F:id`\n- [Search payer types](.\u002Fperson-types\u002Fsearch.md) — `POST \u002Fv1\u002Fperson-types\u002Fsearch`\n- [Payer type fields](.\u002Fperson-types\u002Ffields.md) — `GET \u002Fv1\u002Fperson-types\u002Ffields`\n- [Aggregate payer types](.\u002Fperson-types\u002Faggregate.md) — `POST \u002Fv1\u002Fperson-types\u002Faggregate`\n\n## Key fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | number | Payer type ID. List: [`GET \u002Fv1\u002Fperson-types`](.\u002Fperson-types\u002Flist.md) |\n| `name` | string | Name. Include it when creating a type and in every update |\n| `code` | string \\| null | Unique code. `CRM_CONTACT` and `CRM_COMPANY` identify system types |\n| `active` | boolean | Whether the type is active |\n| `sort` | number | Sort order |\n| `xmlId` | string \\| null | External ID |\n\nFor the full field list, see [`GET \u002Fv1\u002Fperson-types\u002Ffields`](.\u002Fperson-types\u002Ffields.md).\n\n## Before you start\n\n1. **Choose a payer type for the order from the list.** The `personTypeId` field is used in [orders](\u002Fdocs\u002Fentities\u002Forders) and [order properties](\u002Fdocs\u002Fentities\u002Forder-properties).\n2. **The code must be unique.** Creating or updating a type with a `code` that is already in use returns `422 BITRIX_ERROR`.\n3. **Every update requires the name.** To keep the name, read it with [`GET \u002Fv1\u002Fperson-types\u002F:id`](.\u002Fperson-types\u002Fget.md) and include it in [`PATCH`](.\u002Fperson-types\u002Fupdate.md) alongside the fields to change. Without `name`, Bitrix24 returns `422 BITRIX_ERROR`.\n4. **System types cannot be deleted.** [`DELETE`](.\u002Fperson-types\u002Fdelete.md) for `code: \"CRM_CONTACT\"` or `code: \"CRM_COMPANY\"` returns `422 BITRIX_ERROR` with `b24Code: \"200750000003\"`. To deactivate your own type, send its name and `active: false` in [`PATCH`](.\u002Fperson-types\u002Fupdate.md).\n5. **The assigned site is separate from the returned data.** The `lid` field appears in the [field metadata](.\u002Fperson-types\u002Ffields.md), but is absent from response objects. Writing `id` or `lid` returns `400 READONLY_FIELD`.\n\n## Typical workflow\n\n1. Check existing types: [`GET \u002Fv1\u002Fperson-types`](.\u002Fperson-types\u002Flist.md) or [`POST \u002Fv1\u002Fperson-types\u002Fsearch`](.\u002Fperson-types\u002Fsearch.md).\n2. Create your own type with a name and unique code: [`POST \u002Fv1\u002Fperson-types`](.\u002Fperson-types\u002Fcreate.md).\n3. Pass the returned `id` in `personTypeId` when [creating an order](\u002Fdocs\u002Fentities\u002Forders\u002Fcreate) or [creating an order property](\u002Fdocs\u002Fentities\u002Forder-properties\u002Fcreate).\n4. To update the type, send its `name` and the new values: [`PATCH \u002Fv1\u002Fperson-types\u002F:id`](.\u002Fperson-types\u002Fupdate.md).\n5. When your type is no longer needed, deactivate it with `active: false`. To delete it, use [`DELETE \u002Fv1\u002Fperson-types\u002F:id`](.\u002Fperson-types\u002Fdelete.md).\n\n## Limits\n\n| Limit | Value |\n|-------|-------|\n| Records per list or search request | Up to 5000 (`limit`), 50 by default. Request the following records with `offset` |\n| Aggregation | Up to 5 expressions: `count`, `sum`, `avg`, `min`, `max`. Up to 5000 records are read for calculations and grouping |\n| Grouping | By `active` and `code`, up to 5 dimensions. `groupLimit` ranges from 1 to 1000 |\n| Batch writes | `create`, `update`, `delete` — see [Batch](\u002Fdocs\u002Fbatch) |\n| Request rate | Shared across the Vibecode API — see [Limits and optimization](\u002Fdocs\u002Foptimization) |\n\n## See also\n\n- [Orders](\u002Fdocs\u002Fentities\u002Forders)\n- [Order properties](\u002Fdocs\u002Fentities\u002Forder-properties)\n- [Entity API](\u002Fdocs\u002Fentity-api)\n- [Batch](\u002Fdocs\u002Fbatch)\n","2026-10-09",{"person-types\u002Fcreate.md":7,"person-types\u002Flist.md":8,"person-types\u002Fget.md":9,"person-types\u002Fupdate.md":10,"person-types\u002Fdelete.md":11,"person-types\u002Fsearch.md":12,"person-types\u002Ffields.md":13,"person-types\u002Faggregate.md":14},"## Create a payer type\n\n`POST \u002Fv1\u002Fperson-types`\n\nAdds a payer type to the online store list for use in orders and order properties.\n\nPass fields at the root of the JSON object, without a `fields` wrapper.\n\n## Request body fields\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `name` | string | yes | Payer type name |\n| `code` | string \\| null | no | Unique code. Must differ from the code of any other type |\n| `sort` | number | no | Sort order |\n| `active` | boolean | no | Whether the type is active |\n| `xmlId` | string \\| null | no | External ID |\n\nFor the full field list, see [`GET \u002Fv1\u002Fperson-types\u002Ffields`](.\u002Ffields.md).\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n  \"name\": \"Documentation payer type\",\n  \"code\": \"DOCS_PERSON_397F55D8FB1D\",\n  \"xmlId\": \"DOCS_PERSON_397F55D8FB1D\",\n  \"sort\": 900,\n  \"active\": false\n}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n  \"name\": \"Documentation payer type\",\n  \"code\": \"DOCS_PERSON_397F55D8FB1D\",\n  \"xmlId\": \"DOCS_PERSON_397F55D8FB1D\",\n  \"sort\": 900,\n  \"active\": false\n}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    name: 'Documentation payer type',\n    code: 'DOCS_PERSON_397F55D8FB1D',\n    xmlId: 'DOCS_PERSON_397F55D8FB1D',\n    sort: 900,\n    active: false,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    name: 'Documentation payer type',\n    code: 'DOCS_PERSON_397F55D8FB1D',\n    xmlId: 'DOCS_PERSON_397F55D8FB1D',\n    sort: 900,\n    active: false,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | `true` on success. The HTTP status is `201` |\n| `data` | object | Created payer type |\n| `data.id` | number | RO. Payer type ID |\n| `data.name` | string | Name |\n| `data.code` | string \\| null | Unique code |\n| `data.sort` | number | Sort order |\n| `data.active` | boolean | Whether the type is active |\n| `data.xmlId` | string \\| null | External ID |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"active\": false,\n    \"code\": \"DOCS_PERSON_397F55D8FB1D\",\n    \"id\": 21,\n    \"name\": \"Documentation payer type\",\n    \"sort\": 900,\n    \"xmlId\": \"DOCS_PERSON_397F55D8FB1D\"\n  }\n}\n```\n\n## Error response example\n\n422 — the code is already used by another payer type:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"person type code exists\",\n    \"b24Code\": \"200750000005\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `MISSING_REQUIRED_FIELDS` | The `name` field is missing or empty |\n| 400 | `READONLY_FIELD` | A read-only field was provided: `id` or `lid` |\n| 400 | `INVALID_PARAMS` | A scalar field received an object or array, such as an object in `active` |\n| 422 | `BITRIX_ERROR` | The `code` is already in use. Message: `person type code exists`, `b24Code`: `200750000005` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected creation for another reason. The reason is in `message` |\n| 403 | `BITRIX_ACCESS_DENIED` | The key owner lacks permission to modify payer types in Bitrix24 |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Payer types](\u002Fdocs\u002Fentities\u002Fperson-types)\n- [Get a payer type](.\u002Fget.md)\n- [Update a payer type](.\u002Fupdate.md)\n- [Delete a payer type](.\u002Fdelete.md)\n- [Payer type fields](.\u002Ffields.md)\n- [Orders](\u002Fdocs\u002Fentities\u002Forders)\n","## List payer types\n\n`GET \u002Fv1\u002Fperson-types`\n\nRetrieves online store payer types with filtering, sorting, and pagination.\n\n## Parameters\n\n| Parameter | Type | Default | Description |\n|----------|-----|-----------|---------|\n| `filter` (query) | object | — | Filter by fields from [`GET \u002Fv1\u002Fperson-types\u002Ffields`](\u002Fdocs\u002Fentities\u002Fperson-types\u002Ffields).\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `?filter[id]=21` |\n| `select` (query) | string | — | Comma-separated fields, for example `?select=id,name,active`. Only selected fields remain in `data`. Unknown names are reported in `meta.warnings` with the code `UNKNOWN_SELECT_FIELD` |\n| `sort` (query) | string | — | Sort by field: `?sort=id`, or `?sort=-id` for descending order |\n| `order` (query) | object | — | Sort using an object: `?order[id]=desc` |\n| `limit` (query) | number | `50` | Number of records, from 1 to 5000. Values above 5000 are capped at 5000 |\n| `offset` (query) | number | `0` | Number of records to skip |\n| `withTotal` (query) | string | — | Accepts `true` or `false`, but does not change counting or the presence of `meta.total` for payer types |\n\n**Pagination.** When `limit > 50`, Vibecode automatically reads multiple pages of 50 records and combines them into one response. To fetch the next set, increase `offset` by the number of records received. Continue while `meta.hasMore` is `true`.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -g \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types?filter[id]=21\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -g \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types?filter[id]=21\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types?filter[id]=21', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types?filter[id]=21', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | array | Array of payer types |\n| `data[].id` | number | Payer type ID, RO. List: [`GET \u002Fv1\u002Fperson-types`](\u002Fdocs\u002Fentities\u002Fperson-types\u002Flist) |\n| `data[].name` | string | Name |\n| `data[].code` | string \\| null | Unique code |\n| `data[].sort` | number | Sort order |\n| `data[].active` | boolean | Whether the type is active |\n| `data[].xmlId` | string \\| null | External ID |\n| `meta.total` | number | Total number of types matching the filter. Omitted on an empty page when `offset > 0` |\n| `meta.hasMore` | boolean | Whether more records exist beyond the current set |\n| `meta.warnings` | array | Parameter warnings with `code`, `message`, and `field`. Only included when warnings exist |\n| `meta.pageErrorSample` | object | The code and message of an error that stopped automatic pagination early. In this case, `data` contains the records read before the error |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"active\": true,\n      \"code\": \"DOCS_PERSON_397F55D8FB1D\",\n      \"id\": 21,\n      \"name\": \"Updated documentation payer\",\n      \"sort\": 910,\n      \"xmlId\": \"DOCS_PERSON_397F55D8FB1D\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 1,\n    \"hasMore\": false\n  }\n}\n```\n\n## Error response example\n\n400 — sorting by an unknown field:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"UNKNOWN_SORT_FIELD\",\n    \"message\": \"Unknown sort field 'unknownField' for entity 'person-types'. Available: id, name, code, sort, active, xmlId, lid\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `UNKNOWN_FILTER_FIELD` | The filter uses a field absent from the schema. Field list: [`GET \u002Fv1\u002Fperson-types\u002Ffields`](\u002Fdocs\u002Fentities\u002Fperson-types\u002Ffields) |\n| 400 | `INVALID_FILTER_FIELD` | A filter field name starts with the unsupported prefix `@` or `!@` |\n| 400 | `INVALID_FILTER_OPERATOR` | An unknown operator, an empty condition object, or a logical condition with `$or` or `$and` |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two conditions resolve to the same filter condition. Provide only one |\n| 400 | `INVALID_SORT_FIELD` | Sorting uses a forbidden name: `__proto__`, `constructor`, or `prototype` |\n| 400 | `UNKNOWN_SORT_FIELD` | Sorting by an unknown field |\n| 400 | `INVALID_SORT_DIRECTION` | The sort direction is not one of `asc`, `desc`, `ASC`, `DESC`, `1`, `-1` |\n| 400 | `INVALID_FILTER` | The `filter` is not an object or a JSON string containing an object, or the two filter forms are mixed |\n| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Search payer types](\u002Fdocs\u002Fentities\u002Fperson-types\u002Fsearch)\n- [Get a payer type](\u002Fdocs\u002Fentities\u002Fperson-types\u002Fget)\n- [Create a payer type](\u002Fdocs\u002Fentities\u002Fperson-types\u002Fcreate)\n- [Payer type fields](\u002Fdocs\u002Fentities\u002Fperson-types\u002Ffields)\n- [Payer types](\u002Fdocs\u002Fentities\u002Fperson-types)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","## Get a payer type\n\n`GET \u002Fv1\u002Fperson-types\u002F:id`\n\nRetrieves details of a payer type selected for an order or its properties.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Payer type ID. List: [`GET \u002Fv1\u002Fperson-types`](\u002Fdocs\u002Fentities\u002Fperson-types\u002Flist) |\n| `select` (query) | string | no | Comma-separated fields, for example `?select=id,name,active`. Field list: [`GET \u002Fv1\u002Fperson-types\u002Ffields`](\u002Fdocs\u002Fentities\u002Fperson-types\u002Ffields). Only selected fields remain in `data` |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | object | Payer type |\n| `data.id` | number | Payer type ID, RO. List: [`GET \u002Fv1\u002Fperson-types`](\u002Fdocs\u002Fentities\u002Fperson-types\u002Flist) |\n| `data.name` | string | Name |\n| `data.code` | string \\| null | Unique code |\n| `data.sort` | number | Sort order |\n| `data.active` | boolean | Whether the type is active |\n| `data.xmlId` | string \\| null | External ID |\n| `meta.warnings` | array | Warnings about unknown names in `select`, with `code`, `message`, and `field`. Only included when warnings exist |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"active\": false,\n    \"code\": \"DOCS_PERSON_397F55D8FB1D\",\n    \"id\": 21,\n    \"name\": \"Documentation payer type\",\n    \"sort\": 900,\n    \"xmlId\": \"DOCS_PERSON_397F55D8FB1D\"\n  }\n}\n```\n\n## Error response example\n\n404 — the payer type was not found:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"person type is not exists\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | The `id` is not a non-negative integer |\n| 404 | `ENTITY_NOT_FOUND` | No type exists with this `id`. Message: `person type is not exists` |\n| 404 | `ENTITY_NOT_FOUND` | The request completed, but the response contains no object. Message: `personType \u003Cid> not found` |\n| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [List payer types](\u002Fdocs\u002Fentities\u002Fperson-types\u002Flist)\n- [Search payer types](\u002Fdocs\u002Fentities\u002Fperson-types\u002Fsearch)\n- [Update a payer type](\u002Fdocs\u002Fentities\u002Fperson-types\u002Fupdate)\n- [Payer type fields](\u002Fdocs\u002Fentities\u002Fperson-types\u002Ffields)\n- [Payer types](\u002Fdocs\u002Fentities\u002Fperson-types)\n","## Update a payer type\n\n`PATCH \u002Fv1\u002Fperson-types\u002F:id`\n\nUpdates an existing online store payer type used in orders and order properties.\n\nPass fields at the root of the JSON object, without a `fields` wrapper.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Payer type ID, a non-negative integer. List: [`GET \u002Fv1\u002Fperson-types`](.\u002Flist.md) |\n\n## Request body fields\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `name` | string | yes | Name. To keep the existing name, read it with [`GET \u002Fv1\u002Fperson-types\u002F:id`](.\u002Fget.md) |\n| `code` | string \\| null | no | Unique code. `null` keeps the existing code |\n| `sort` | number | no | Sort order |\n| `active` | boolean | no | Whether the type is active |\n| `xmlId` | string \\| null | no | External ID. `null` keeps the existing ID |\n\nFor the full field list, see [`GET \u002Fv1\u002Fperson-types\u002Ffields`](.\u002Ffields.md).\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n  \"name\": \"Updated documentation payer\",\n  \"sort\": 910,\n  \"active\": true\n}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n  \"name\": \"Updated documentation payer\",\n  \"sort\": 910,\n  \"active\": true\n}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    name: 'Updated documentation payer',\n    sort: 910,\n    active: true,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    name: 'Updated documentation payer',\n    sort: 910,\n    active: true,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | `true` on success. The HTTP status is `200` |\n| `data` | object | Updated payer type |\n| `data.id` | number | RO. Payer type ID |\n| `data.name` | string | Name |\n| `data.code` | string \\| null | Unique code |\n| `data.sort` | number | Sort order |\n| `data.active` | boolean | Whether the type is active |\n| `data.xmlId` | string \\| null | External ID |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"active\": true,\n    \"code\": \"DOCS_PERSON_397F55D8FB1D\",\n    \"id\": 21,\n    \"name\": \"Updated documentation payer\",\n    \"sort\": 910,\n    \"xmlId\": \"DOCS_PERSON_397F55D8FB1D\"\n  }\n}\n```\n\n## Error response example\n\n422 — `active` was provided, but `name` is missing:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Required fields: name\",\n    \"b24Code\": \"0\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `EMPTY_UPDATE_BODY` | The request body is empty |\n| 400 | `NO_RECOGNIZED_UPDATE_FIELDS` | The body contains no writable payer type fields |\n| 400 | `READONLY_FIELD` | A read-only field was provided: `id` or `lid` |\n| 400 | `INVALID_PARAMS` | A scalar field received an object or array, such as an object in `active` |\n| 400 | `INVALID_PARAMS` | The path `id` is not a non-negative integer |\n| 404 | `ENTITY_NOT_FOUND` | No payer type exists with this `id`. Message: `person type is not exists` |\n| 422 | `BITRIX_ERROR` | The `name` field is missing. Message: `Required fields: name`, `b24Code`: `0` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the update for another reason, including a `code` already in use. The reason is in `message` |\n| 403 | `BITRIX_ACCESS_DENIED` | The key owner lacks permission to modify payer types in Bitrix24 |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Payer types](\u002Fdocs\u002Fentities\u002Fperson-types)\n- [Get a payer type](.\u002Fget.md)\n- [Create a payer type](.\u002Fcreate.md)\n- [Payer type fields](.\u002Ffields.md)\n- [Delete a payer type](.\u002Fdelete.md)\n","## Delete a payer type\n\n`DELETE \u002Fv1\u002Fperson-types\u002F:id`\n\nDeletes a payer type from the online store list by ID. You cannot restore a deleted type through the API. Create a new type if needed.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Payer type ID, a non-negative integer. List: [`GET \u002Fv1\u002Fperson-types`](.\u002Flist.md) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Payer type deleted')\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002F21', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Payer type deleted')\n}\n```\n\n## Response\n\nSuccessful deletion returns HTTP `204 No Content` with an empty body. Check the status code to confirm success.\n\n## Response example\n\n```http\nHTTP\u002F1.1 204 No Content\n```\n\n## Error response example\n\n404 — the payer type has already been deleted:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"person type is not exists\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | The path `id` is not a non-negative integer |\n| 404 | `ENTITY_NOT_FOUND` | The payer type with this `id` does not exist or has already been deleted. Message: `person type is not exists` |\n| 422 | `BITRIX_ERROR` | A type with `code: \"CRM_CONTACT\"` or `code: \"CRM_COMPANY\"` is protected from deletion. Message: `person type code is protected`, `b24Code`: `200750000003` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected deletion for another reason. The reason is in `message` |\n| 403 | `BITRIX_ACCESS_DENIED` | The key owner lacks permission to modify payer types in Bitrix24 |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\nTo deactivate your own type instead of deleting it, send its name and `active: false` in [`PATCH \u002Fv1\u002Fperson-types\u002F:id`](.\u002Fupdate.md).\n\n## See also\n\n- [Payer types](\u002Fdocs\u002Fentities\u002Fperson-types)\n- [Update a payer type](.\u002Fupdate.md)\n- [Get a payer type](.\u002Fget.md)\n- [Create a payer type](.\u002Fcreate.md)\n","## Search payer types\n\n`POST \u002Fv1\u002Fperson-types\u002Fsearch`\n\nSearches payer types using filter and sort conditions in the JSON request body.\n\n## Request body fields\n\n| Field | Type | Default | Description |\n|------|-----|-----------|---------|\n| `filter` | object | — | Filter by fields from [`GET \u002Fv1\u002Fperson-types\u002Ffields`](\u002Fdocs\u002Fentities\u002Fperson-types\u002Ffields).\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `{ \"id\": 21 }` |\n| `select` | string[] \\| string | — | A field list, for example `[\"id\", \"name\", \"active\"]`, or a comma-separated string. Only selected fields remain in `data`. Unknown names are reported in `meta.warnings` with the code `UNKNOWN_SELECT_FIELD` |\n| `sort` | string \\| object \\| string[] | — | Sort: `\"-id\"`, `{ \"id\": \"desc\" }`, or `[\"id\", \"-sort\"]` |\n| `order` | object | — | Sort using an object: `{ \"id\": \"desc\" }`. If `sort` is provided, it takes precedence |\n| `limit` | number | `50` | Number of records, from 1 to 5000. Values above 5000 are capped at 5000 |\n| `offset` | number | `0` | Number of records to skip |\n| `withTotal` | boolean | — | Accepts `true` or `false`, but does not change counting or the presence of `meta.total` for payer types |\n\n**Pagination.** When `limit > 50`, Vibecode automatically reads multiple pages of 50 records. Increase `offset` to fetch the next set. Check `meta.hasMore` after each response.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"filter\": {\"id\": 21}}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"filter\": {\"id\": 21}}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ filter: { id: 21 } }),\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ filter: { id: 21 } }),\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | array | Array of payer types |\n| `data[].id` | number | Payer type ID, RO. List: [`GET \u002Fv1\u002Fperson-types`](\u002Fdocs\u002Fentities\u002Fperson-types\u002Flist) |\n| `data[].name` | string | Name |\n| `data[].code` | string \\| null | Unique code |\n| `data[].sort` | number | Sort order |\n| `data[].active` | boolean | Whether the type is active |\n| `data[].xmlId` | string \\| null | External ID |\n| `meta.total` | number | Total number of types matching the filter. Omitted on an empty page when `offset > 0` |\n| `meta.hasMore` | boolean | Whether more records exist beyond the current set |\n| `meta.durationMs` | number | Request duration in milliseconds |\n| `meta.warnings` | array | Parameter warnings with `code`, `message`, and `field`. Only included when warnings exist |\n| `meta.pageErrorSample` | object | The code and message of an error that stopped automatic pagination early. Included when `data` contains fewer records than `limit` because of the error |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"active\": true,\n      \"code\": \"DOCS_PERSON_397F55D8FB1D\",\n      \"id\": 21,\n      \"name\": \"Updated documentation payer\",\n      \"sort\": 910,\n      \"xmlId\": \"DOCS_PERSON_397F55D8FB1D\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 1,\n    \"hasMore\": false,\n    \"durationMs\": 49\n  }\n}\n```\n\n## Error response example\n\n400 — an object was provided instead of a field list:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_SELECT_TYPE\",\n    \"message\": \"select must be a string (\\\"id,title\\\") or an array of strings ([\\\"id\\\",\\\"title\\\"]); got a object\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `UNKNOWN_FILTER_FIELD` | The filter uses a field absent from the schema. Field list: [`GET \u002Fv1\u002Fperson-types\u002Ffields`](\u002Fdocs\u002Fentities\u002Fperson-types\u002Ffields) |\n| 400 | `INVALID_FILTER_FIELD` | A filter field name starts with the unsupported prefix `@` or `!@` |\n| 400 | `INVALID_FILTER_OPERATOR` | An unknown operator, an empty condition object, or a logical condition with `$or` or `$and` |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two conditions resolve to the same filter condition. Provide only one |\n| 400 | `INVALID_SORT_FIELD` | Sorting uses a forbidden name: `__proto__`, `constructor`, or `prototype` |\n| 400 | `UNKNOWN_SORT_FIELD` | Sorting by an unknown field |\n| 400 | `INVALID_SORT_DIRECTION` | The sort direction is not one of `asc`, `desc`, `ASC`, `DESC`, `1`, `-1` |\n| 400 | `INVALID_FILTER_SHAPE` | The `filter` is a string, number, array, or another value instead of a condition object |\n| 400 | `INVALID_SORT_TYPE` | The sort value has an unsupported type |\n| 400 | `INVALID_LIMIT` | The `limit` is neither a number nor a numeric string |\n| 400 | `INVALID_SELECT_TYPE` | The `select` is neither a string nor an array of strings |\n| 400 | `INVALID_REQUEST` | The request body is not a JSON object |\n| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [List payer types](\u002Fdocs\u002Fentities\u002Fperson-types\u002Flist)\n- [Get a payer type](\u002Fdocs\u002Fentities\u002Fperson-types\u002Fget)\n- [Aggregate payer types](\u002Fdocs\u002Fentities\u002Fperson-types\u002Faggregate)\n- [Payer type fields](\u002Fdocs\u002Fentities\u002Fperson-types\u002Ffields)\n- [Payer types](\u002Fdocs\u002Fentities\u002Fperson-types)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","## Payer type fields\n\n`GET \u002Fv1\u002Fperson-types\u002Ffields`\n\nDescribes payer type fields for creation, updates, selection, and filtering, and lists the available grouping fields.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { data } = await res.json()\nconsole.log('Payer type fields:', Object.keys(data.fields))\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data.fields` | object | Field definitions. Each key is a field name, and its value contains the field properties |\n| `data.fields.\u003Cfield>.type` | string | Value type: `number`, `string`, or `boolean` |\n| `data.fields.\u003Cfield>.readonly` | boolean | `true` means the field is read-only |\n| `data.fields.\u003Cfield>.required` | boolean | Included as `true` for `name`, which is required for creation |\n| `data.fields.\u003Cfield>.nullable` | boolean | Included as `true` for `code` and `xmlId`, which allow `null` |\n| `data.fields.\u003Cfield>.notReturned` | boolean | Included as `true` for `lid`: the field is in the schema but omitted from response objects |\n| `data.fields.\u003Cfield>.label` | string | Field label |\n| `data.fields.\u003Cfield>.description` | string | Field description |\n| `data.aggregatable` | array | Fields for `groupBy` in [Aggregate payer types](.\u002Faggregate.md): `active`, `code` |\n| `data.batch` | array | Batch write operations: `create`, `update`, `delete` |\n\n### Payer type fields\n\nAll fields from the schema. The RO column marks read-only fields.\n\n| Field | Type | RO | Description |\n|------|-----|:--:|---------|\n| `id` | number | yes | Payer type ID. List: [`GET \u002Fv1\u002Fperson-types`](.\u002Flist.md) |\n| `name` | string | no | Name. Required for creation and [updates](.\u002Fupdate.md) |\n| `code` | string \\| null | no | Unique code. `null` if not set |\n| `sort` | number | no | Sort order |\n| `active` | boolean | no | Whether the type is active |\n| `xmlId` | string \\| null | no | External ID. `null` if not set |\n| `lid` | string | yes | Site assigned by Bitrix24. Marked `notReturned` and omitted from response objects |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"fields\": {\n      \"id\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"ID\",\n        \"description\": \"ID.\"\n      },\n      \"name\": {\n        \"type\": \"string\",\n        \"readonly\": false,\n        \"required\": true,\n        \"label\": \"Name\",\n        \"description\": \"Name.\"\n      },\n      \"code\": {\n        \"type\": \"string\",\n        \"readonly\": false,\n        \"nullable\": true,\n        \"label\": \"Unique code\",\n        \"description\": \"Unique code.\"\n      },\n      \"sort\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"label\": \"Sort order\",\n        \"description\": \"Sort order.\"\n      },\n      \"active\": {\n        \"type\": \"boolean\",\n        \"readonly\": false,\n        \"label\": \"Active\",\n        \"description\": \"Active.\"\n      },\n      \"xmlId\": {\n        \"type\": \"string\",\n        \"readonly\": false,\n        \"nullable\": true,\n        \"label\": \"External ID\",\n        \"description\": \"External ID.\"\n      },\n      \"lid\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"notReturned\": true,\n        \"label\": \"Site assigned by Bitrix24\",\n        \"description\": \"Site assigned by Bitrix24.\"\n      }\n    },\n    \"aggregatable\": [\n      \"active\",\n      \"code\"\n    ],\n    \"batch\": [\n      \"create\",\n      \"update\",\n      \"delete\"\n    ]\n  }\n}\n```\n\n## Error response example\n\n401 — the API key is missing:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"MISSING_API_KEY\",\n    \"message\": \"API key required. Pass via X-Api-Key header.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n| 429 | `RATE_LIMITED` | Request limit exceeded: 300 per minute per portal, shared by all API keys for the portal. The exact value is in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [List payer types](.\u002Flist.md)\n- [Get a payer type](.\u002Fget.md)\n- [Create a payer type](.\u002Fcreate.md)\n- [Update a payer type](.\u002Fupdate.md)\n- [Aggregate payer types](.\u002Faggregate.md)\n- [Payer types](\u002Fdocs\u002Fentities\u002Fperson-types)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Entity API](\u002Fdocs\u002Fentity-api)\n","## Aggregate payer types\n\n`POST \u002Fv1\u002Fperson-types\u002Faggregate`\n\nCounts payer types with filtering and grouping by activity or code, and calculates the sum, average, minimum, and maximum of numeric fields.\n\n## Standard fields\n\n| Field | Purpose |\n|------|------------|\n| `active` | Activity flag for `groupBy` |\n| `code` | Unique code for `groupBy` |\n| `sort` | Sort order: a numeric field for `sum`, `avg`, `min`, `max` |\n| `id` | Payer type ID from [List payer types](.\u002Flist.md). A numeric field for `sum`, `avg`, `min`, `max` |\n\nFields for `groupBy` are listed in `data.aggregatable` of [`GET \u002Fv1\u002Fperson-types\u002Ffields`](.\u002Ffields.md). Numeric functions accept fields with the `number` type from the same schema: `id` and `sort`.\n\n## Request body fields\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `aggregate` | array | no | An array of 1 to 5 expressions such as `{ \"field\": \"sort\", \"function\": \"sum\" }`. Functions: `count`, `sum`, `avg`, `min`, `max`. For `count`, the field is `\"*\"`. Defaults to `[{ \"field\": \"*\", \"function\": \"count\" }]` |\n| `filter` | object | no | Filter by fields from [`GET \u002Fv1\u002Fperson-types\u002Ffields`](.\u002Ffields.md).\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `{ \"id\": 21 }` |\n| `groupBy` | string \\| string[] | no | A field or array of up to 5 grouping fields. Allowed fields: `active`, `code` |\n| `groupOrderBy` | array | no | Group sorting: `[{ \"field\": \"count\", \"direction\": \"desc\" }]`. The `field` is `count`, a field from `groupBy`, or `\u003Cfield>:\u003Cfunction>` from `aggregate`. Directions: `asc`, `desc`. Defaults to `desc` when `direction` is omitted. Requires `groupBy` |\n| `groupLimit` | number | no | Number of groups to return: an integer from 1 to 1000. If omitted, groups are not truncated. Requires `groupBy` |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"id\": 21 },\n    \"aggregate\": [{ \"field\": \"*\", \"function\": \"count\" }],\n    \"groupBy\": [\"active\", \"code\"],\n    \"groupOrderBy\": [{ \"field\": \"count\", \"direction\": \"desc\" }],\n    \"groupLimit\": 10\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"id\": 21 },\n    \"aggregate\": [{ \"field\": \"*\", \"function\": \"count\" }],\n    \"groupBy\": [\"active\", \"code\"],\n    \"groupOrderBy\": [{ \"field\": \"count\", \"direction\": \"desc\" }],\n    \"groupLimit\": 10\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { id: 21 },\n    aggregate: [{ field: '*', function: 'count' }],\n    groupBy: ['active', 'code'],\n    groupOrderBy: [{ field: 'count', direction: 'desc' }],\n    groupLimit: 10,\n  }),\n})\n\nconst { data } = await res.json()\nconsole.log('Payer type counts by activity and code:', data.groups)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fperson-types\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { id: 21 },\n    aggregate: [{ field: '*', function: 'count' }],\n    groupBy: ['active', 'code'],\n    groupOrderBy: [{ field: 'count', direction: 'desc' }],\n    groupLimit: 10,\n  }),\n})\n\nconst { data } = await res.json()\n```\n\n## Other scenarios\n\nThe blocks below are request bodies.\n\nCount types matching the filter without grouping or numeric functions. Records are not fetched:\n\n```json\n{ \"filter\": { \"id\": 21 } }\n```\n\nSum, average, minimum, and maximum sort order:\n\n```json\n{\n  \"filter\": { \"id\": 21 },\n  \"aggregate\": [\n    { \"field\": \"*\", \"function\": \"count\" },\n    { \"field\": \"sort\", \"function\": \"sum\" },\n    { \"field\": \"sort\", \"function\": \"avg\" },\n    { \"field\": \"sort\", \"function\": \"min\" },\n    { \"field\": \"sort\", \"function\": \"max\" }\n  ]\n}\n```\n\nSum of sort order grouped by activity when the filter matches no records:\n\n```json\n{\n  \"filter\": { \"id\": 21, \"code\": \"ABSENT_DOCS_PERSON_397F55D8FB1D\" },\n  \"aggregate\": [{ \"field\": \"sort\", \"function\": \"sum\" }],\n  \"groupBy\": \"active\"\n}\n```\n\nFor the last request, `data.count` and the sum are `0`, and `data.groups` is an empty array.\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data.count` | number | Total number of types matching the filter |\n| `data.aggregates` | object | Numeric results by field and function, for example `{ \"sort\": { \"sum\": 900 } }`. An empty object when only `count` is used |\n| `data.aggregates.\u003Cfield>.truncated` | boolean | Included as `true` when numeric results are calculated from an incomplete set of records |\n| `data.groups` | array | Included with `groupBy`. Each group contains grouping field values, `count`, and `aggregates`. The `active` value is a `boolean`; the `code` value is a `string` or `null` |\n| `data.groups[].count` | number | Number of processed records in the group |\n| `data.groups[].aggregates` | object | Numeric results within the group, in the same format as `data.aggregates` |\n| `data.groups[].truncated` | boolean | Included as `true` for an incomplete set of records. Group counts and calculations apply to processed records |\n| `data.meta.totalRecords` | number | Total number of records matching the filter |\n| `data.meta.recordsProcessed` | number | Number of processed records, up to 5000. `0` without grouping or numeric functions |\n| `data.meta.truncated` | boolean | `true` if fewer records were read than the total count, including because of the 5000-record ceiling, or a subpage error stopped the read. `false` for a complete response. Always `false` without grouping or numeric functions |\n| `data.meta.recordsShortfall` | number | Number of unread records: `totalRecords - recordsProcessed`. Included when there is a shortfall, including one caused by the 5000-record ceiling |\n| `data.meta.pageErrorSample` | object | A sample subpage error. Included when an error stopped the read |\n| `data.meta.warnings` | array | Contains a warning with the code `AGGREGATE_TRUNCATED` for an incomplete set of records |\n| `data.meta.groupTotal` | number | Included with `groupBy`: the number of groups before applying `groupLimit` |\n| `data.meta.groupsTruncated` | boolean | Included with `groupBy`. `true` if groups were truncated by `groupLimit` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"count\": 1,\n    \"aggregates\": {},\n    \"groups\": [\n      {\n        \"active\": false,\n        \"code\": \"DOCS_PERSON_397F55D8FB1D\",\n        \"count\": 1,\n        \"aggregates\": {}\n      }\n    ],\n    \"meta\": {\n      \"totalRecords\": 1,\n      \"recordsProcessed\": 1,\n      \"truncated\": false,\n      \"groupTotal\": 1,\n      \"groupsTruncated\": false\n    }\n  }\n}\n```\n\nWithout `groupBy`, the response omits `data.groups`.\n\n## Error response example\n\n400 — the string field `name` was passed to the numeric function `sum`:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"Field 'name' is not numeric (type: string). Only number fields support sum.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | The `aggregate` is not an array or is an empty array |\n| 400 | `INVALID_PARAMS` | The `aggregate` contains more than 5 expressions |\n| 400 | `INVALID_PARAMS` | The function is unknown or missing |\n| 400 | `INVALID_PARAMS` | The field for `count` differs from `\"*\"` |\n| 400 | `INVALID_PARAMS` | The field for `sum`, `avg`, `min`, or `max` is missing or is `\"*\"` |\n| 400 | `INVALID_PARAMS` | A numeric function received a non-numeric field, such as `name` |\n| 400 | `INVALID_PARAMS` | The numeric function field was not found. The message lists the allowed fields: `id`, `sort` |\n| 400 | `INVALID_PARAMS` | The `op`, `field`, or `function` was provided at the root without an `aggregate` array |\n| 400 | `INVALID_PARAMS` | The `groupBy` is neither a string nor an array of strings, or the array contains a value of another type |\n| 400 | `INVALID_PARAMS` | The grouping field is neither `active` nor `code` |\n| 400 | `INVALID_PARAMS` | The `groupBy` contains more than 5 fields |\n| 400 | `INVALID_PARAMS` | The `groupBy` contains a reserved name: `count`, `aggregates`, `meta`, or `groups` |\n| 400 | `INVALID_PARAMS` | The `groupOrderBy` was provided without `groupBy` |\n| 400 | `INVALID_PARAMS` | The `groupOrderBy` is not an array, an item has no string `field`, the field is absent from grouping or aggregate expressions, or `direction` is neither `asc` nor `desc` |\n| 400 | `INVALID_PARAMS` | The `groupLimit` was provided without `groupBy` |\n| 400 | `INVALID_PARAMS` | The `groupLimit` is not an integer from 1 to 1000 |\n| 400 | `UNKNOWN_FILTER_FIELD` | An unknown field in `filter` |\n| 400 | `INVALID_FILTER_FIELD` | A field name in `filter` starts with the unsupported prefix `@` or `!@` |\n| 400 | `INVALID_FILTER_OPERATOR` | An unsupported operator, an empty condition object, or logical conditions with `$or` \u002F `$and` |\n| 400 | `INVALID_FILTER_SHAPE` | The `filter` is not a condition object, such as a string, number, or array |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two filter conditions resolve to the same condition, such as `$ne` and `$nin` for one field |\n| 422 | `AGGREGATION_LIMIT_EXCEEDED` | With the limit enabled for the account, more than 5000 records match the filter and the request requires numeric calculations or grouping. No records are fetched. Narrow the filter |\n| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n| 429 | `RATE_LIMITED` | Request limit exceeded: 300 per minute per portal, shared by all API keys for the portal. The exact value is in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\nA request without grouping or numeric functions counts records without fetching them. Numeric calculations and any grouping, including grouping with only `count`, are subject to a 5000-record limit. If the account is configured to reject requests above this limit and more records match the filter, the request returns `422 AGGREGATION_LIMIT_EXCEEDED` without fetching them. Otherwise, records are read page by page, up to 5000. For an exact count over a large set, use a request without grouping or numeric functions. Narrow the filter to calculate over the entire set. See [Aggregation POST — the 5000-record ceiling](\u002Fdocs\u002Fentity-api#aggregation-post-the-5000-record-ceiling).\n\n## See also\n\n- [List payer types](.\u002Flist.md)\n- [Search payer types](.\u002Fsearch.md)\n- [Payer type fields](.\u002Ffields.md)\n- [Payer types](\u002Fdocs\u002Fentities\u002Fperson-types)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n",1795000362999]