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
filter object — Filter by fields from GET /v1/person-types/fields.
Filtering syntax. 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

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
success boolean Always true on success
data array Array of payer types
data[].id number Payer type ID, RO. List: GET /v1/person-types
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
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.

See also