For AI agents: markdown of this page — /docs-content-en/entities/person-types/search.md documentation index — /llms.txt

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
Fieldfilter Typeobject Default— DescriptionFilter by fields from GET /v1/person-types/fields.
Filtering syntax. Example: { "id": 21 }
Fieldselect Typestring[] | string Default— DescriptionA 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
Fieldsort Typestring | object | string[] Default— DescriptionSort: "-id", { "id": "desc" }, or ["id", "-sort"]
Fieldorder Typeobject Default— DescriptionSort using an object: { "id": "desc" }. If sort is provided, it takes precedence
Fieldlimit Typenumber Default50 DescriptionNumber of records, from 1 to 5000. Values above 5000 are capped at 5000
Fieldoffset Typenumber Default0 DescriptionNumber of records to skip
FieldwithTotal Typeboolean Default— DescriptionAccepts 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

Terminal 
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

Terminal 
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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of payer types
Fielddata[].id Typenumber DescriptionPayer type ID, RO. List: GET /v1/person-types
Fielddata[].name Typestring DescriptionName
Fielddata[].code Typestring | null DescriptionUnique code
Fielddata[].sort Typenumber DescriptionSort order
Fielddata[].active Typeboolean DescriptionWhether the type is active
Fielddata[].xmlId Typestring | null DescriptionExternal ID
Fieldmeta.total Typenumber DescriptionTotal number of types matching the filter. Omitted on an empty page when offset > 0
Fieldmeta.hasMore Typeboolean DescriptionWhether more records exist beyond the current set
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds
Fieldmeta.warnings Typearray DescriptionParameter warnings with code, message, and field. Only included when warnings exist
Fieldmeta.pageErrorSample Typeobject DescriptionThe 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
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionThe filter uses a field absent from the schema. Field list: GET /v1/person-types/fields
HTTP400 CodeINVALID_FILTER_FIELD DescriptionA filter field name starts with the unsupported prefix @ or !@
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionAn unknown operator, an empty condition object, or a logical condition with $or or $and
HTTP400 CodeINVALID_DUPLICATE_FILTER_FIELD DescriptionTwo conditions resolve to the same filter condition. Provide only one
HTTP400 CodeINVALID_SORT_FIELD DescriptionSorting uses a forbidden name: __proto__, constructor, or prototype
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting by an unknown field
HTTP400 CodeINVALID_SORT_DIRECTION DescriptionThe sort direction is not one of asc, desc, ASC, DESC, 1, -1
HTTP400 CodeINVALID_FILTER_SHAPE DescriptionThe filter is a string, number, array, or another value instead of a condition object
HTTP400 CodeINVALID_SORT_TYPE DescriptionThe sort value has an unsupported type
HTTP400 CodeINVALID_LIMIT DescriptionThe limit is neither a number nor a numeric string
HTTP400 CodeINVALID_SELECT_TYPE DescriptionThe select is neither a string nor an array of strings
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not a JSON object
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 access tokens are configured

For the full list of common API errors, see Error codes.

See also