## List payer types

`GET /v1/person-types`

Retrieves online store payer types with filtering, sorting, and pagination.

## Parameters

| Parameter | Type | Default | Description |
|----------|-----|-----------|---------|
| `filter` (query) | object | — | Filter by fields from [`GET /v1/person-types/fields`](/docs/entities/person-types/fields).<br>[Filtering syntax](/docs/filtering). Example: `?filter[id]=21` |
| `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` |
| `sort` (query) | string | — | Sort by field: `?sort=id`, or `?sort=-id` for descending order |
| `order` (query) | object | — | Sort using an object: `?order[id]=desc` |
| `limit` (query) | number | `50` | Number of records, from 1 to 5000. Values above 5000 are capped at 5000 |
| `offset` (query) | number | `0` | Number of records to skip |
| `withTotal` (query) | string | — | 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 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`.

## Examples

### curl — personal key

```bash
curl -g "https://vibecode.bitrix24.com/v1/person-types?filter[id]=21" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -g "https://vibecode.bitrix24.com/v1/person-types?filter[id]=21" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/person-types?filter[id]=21', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/person-types?filter[id]=21', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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.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. In this case, `data` contains the records read before 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
  }
}
```

## Error response example

400 — sorting by an unknown field:

```json
{
  "success": false,
  "error": {
    "code": "UNKNOWN_SORT_FIELD",
    "message": "Unknown sort field 'unknownField' for entity 'person-types'. Available: id, name, code, sort, active, xmlId, lid"
  }
}
```

## 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` | The `filter` is not an object or a JSON string containing an object, or the two filter forms are mixed |
| 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

- [Search payer types](/docs/entities/person-types/search)
- [Get a payer type](/docs/entities/person-types/get)
- [Create a payer type](/docs/entities/person-types/create)
- [Payer type fields](/docs/entities/person-types/fields)
- [Payer types](/docs/entities/person-types)
- [Filtering syntax](/docs/filtering)
- [Limits and optimization](/docs/optimization)