## Search payer types

`POST /v1/person-types/search`

Searches payer types using filter and sort conditions in the JSON request body.

## Request body fields

| Field | Type | Default | Description |
|------|-----|-----------|---------|
| `filter` | object | — | Filter by fields from [`GET /v1/person-types/fields`](/docs/entities/person-types/fields).<br>[Filtering syntax](/docs/filtering). Example: `{ "id": 21 }` |
| `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` |
| `sort` | string \| object \| string[] | — | Sort: `"-id"`, `{ "id": "desc" }`, or `["id", "-sort"]` |
| `order` | object | — | Sort using an object: `{ "id": "desc" }`. If `sort` is provided, it takes precedence |
| `limit` | number | `50` | Number of records, from 1 to 5000. Values above 5000 are capped at 5000 |
| `offset` | number | `0` | Number of records to skip |
| `withTotal` | boolean | — | Accepts `true` or `false`, but does not change counting or the presence of `meta.total` for payer types |

**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.

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/person-types/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"id": 21}}'
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/person-types/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"id": 21}}'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/person-types/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ filter: { id: 21 } }),
})

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

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/person-types/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ filter: { id: 21 } }),
})

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

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of payer types |
| `data[].id` | number | Payer type ID, RO. List: [`GET /v1/person-types`](/docs/entities/person-types/list) |
| `data[].name` | string | Name |
| `data[].code` | string \| null | Unique code |
| `data[].sort` | number | Sort order |
| `data[].active` | boolean | Whether the type is active |
| `data[].xmlId` | string \| null | External ID |
| `meta.total` | number | Total number of types matching the filter. Omitted on an empty page when `offset > 0` |
| `meta.hasMore` | boolean | Whether more records exist beyond the current set |
| `meta.durationMs` | number | Request duration in milliseconds |
| `meta.warnings` | array | Parameter warnings with `code`, `message`, and `field`. Only included when warnings exist |
| `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 |

## Response example

```json
{
  "success": true,
  "data": [
    {
      "active": true,
      "code": "DOCS_PERSON_397F55D8FB1D",
      "id": 21,
      "name": "Updated documentation payer",
      "sort": 910,
      "xmlId": "DOCS_PERSON_397F55D8FB1D"
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false,
    "durationMs": 49
  }
}
```

## Error response example

400 — an object was provided instead of a field list:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_SELECT_TYPE",
    "message": "select must be a string (\"id,title\") or an array of strings ([\"id\",\"title\"]); got a object"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `UNKNOWN_FILTER_FIELD` | The filter uses a field absent from the schema. Field list: [`GET /v1/person-types/fields`](/docs/entities/person-types/fields) |
| 400 | `INVALID_FILTER_FIELD` | A filter field name starts with the unsupported prefix `@` or `!@` |
| 400 | `INVALID_FILTER_OPERATOR` | An unknown operator, an empty condition object, or a logical condition with `$or` or `$and` |
| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two conditions resolve to the same filter condition. Provide only one |
| 400 | `INVALID_SORT_FIELD` | Sorting uses a forbidden name: `__proto__`, `constructor`, or `prototype` |
| 400 | `UNKNOWN_SORT_FIELD` | Sorting by an unknown field |
| 400 | `INVALID_SORT_DIRECTION` | The sort direction is not one of `asc`, `desc`, `ASC`, `DESC`, `1`, `-1` |
| 400 | `INVALID_FILTER_SHAPE` | The `filter` is a string, number, array, or another value instead of a condition object |
| 400 | `INVALID_SORT_TYPE` | The sort value has an unsupported type |
| 400 | `INVALID_LIMIT` | The `limit` is neither a number nor a numeric string |
| 400 | `INVALID_SELECT_TYPE` | The `select` is neither a string nor an array of strings |
| 400 | `INVALID_REQUEST` | The request body is not a JSON object |
| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |

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

## See also

- [List payer types](/docs/entities/person-types/list)
- [Get a payer type](/docs/entities/person-types/get)
- [Aggregate payer types](/docs/entities/person-types/aggregate)
- [Payer type fields](/docs/entities/person-types/fields)
- [Payer types](/docs/entities/person-types)
- [Filtering syntax](/docs/filtering)
- [Limits and optimization](/docs/optimization)