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

Aggregate payer types

POST /v1/person-types/aggregate

Counts payer types with filtering and grouping by activity or code, and calculates the sum, average, minimum, and maximum of numeric fields.

Standard fields

Field Purpose
Fieldactive PurposeActivity flag for groupBy
Fieldcode PurposeUnique code for groupBy
Fieldsort PurposeSort order: a numeric field for sum, avg, min, max
Fieldid PurposePayer type ID from List payer types. A numeric field for sum, avg, min, max

Fields for groupBy are listed in data.aggregatable of GET /v1/person-types/fields. Numeric functions accept fields with the number type from the same schema: id and sort.

Request body fields

Field Type Required Description
Fieldaggregate Typearray Requiredno DescriptionAn 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" }]
Fieldfilter Typeobject Requiredno DescriptionFilter by fields from GET /v1/person-types/fields.
Filtering syntax. Example: { "id": 21 }
FieldgroupBy Typestring | string[] Requiredno DescriptionA field or array of up to 5 grouping fields. Allowed fields: active, code
FieldgroupOrderBy Typearray Requiredno DescriptionGroup sorting: [{ "field": "count", "direction": "desc" }]. The field is count, a field from groupBy, or <field>:<function> from aggregate. Directions: asc, desc. Defaults to desc when direction is omitted. Requires groupBy
FieldgroupLimit Typenumber Requiredno DescriptionNumber of groups to return: an integer from 1 to 1000. If omitted, groups are not truncated. Requires groupBy

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/person-types/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "id": 21 },
    "aggregate": [{ "field": "*", "function": "count" }],
    "groupBy": ["active", "code"],
    "groupOrderBy": [{ "field": "count", "direction": "desc" }],
    "groupLimit": 10
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/person-types/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "id": 21 },
    "aggregate": [{ "field": "*", "function": "count" }],
    "groupBy": ["active", "code"],
    "groupOrderBy": [{ "field": "count", "direction": "desc" }],
    "groupLimit": 10
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/person-types/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { id: 21 },
    aggregate: [{ field: '*', function: 'count' }],
    groupBy: ['active', 'code'],
    groupOrderBy: [{ field: 'count', direction: 'desc' }],
    groupLimit: 10,
  }),
})

const { data } = await res.json()
console.log('Payer type counts by activity and code:', data.groups)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/person-types/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { id: 21 },
    aggregate: [{ field: '*', function: 'count' }],
    groupBy: ['active', 'code'],
    groupOrderBy: [{ field: 'count', direction: 'desc' }],
    groupLimit: 10,
  }),
})

const { data } = await res.json()

Other scenarios

The blocks below are request bodies.

Count types matching the filter without grouping or numeric functions. Records are not fetched:

JSON 
{ "filter": { "id": 21 } }

Sum, average, minimum, and maximum sort order:

JSON 
{
  "filter": { "id": 21 },
  "aggregate": [
    { "field": "*", "function": "count" },
    { "field": "sort", "function": "sum" },
    { "field": "sort", "function": "avg" },
    { "field": "sort", "function": "min" },
    { "field": "sort", "function": "max" }
  ]
}

Sum of sort order grouped by activity when the filter matches no records:

JSON 
{
  "filter": { "id": 21, "code": "ABSENT_DOCS_PERSON_397F55D8FB1D" },
  "aggregate": [{ "field": "sort", "function": "sum" }],
  "groupBy": "active"
}

For the last request, data.count and the sum are 0, and data.groups is an empty array.

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.count Typenumber DescriptionTotal number of types matching the filter
Fielddata.aggregates Typeobject DescriptionNumeric results by field and function, for example { "sort": { "sum": 900 } }. An empty object when only count is used
Fielddata.aggregates.<field>.truncated Typeboolean DescriptionIncluded as true when numeric results are calculated from an incomplete set of records
Fielddata.groups Typearray DescriptionIncluded 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
Fielddata.groups[].count Typenumber DescriptionNumber of processed records in the group
Fielddata.groups[].aggregates Typeobject DescriptionNumeric results within the group, in the same format as data.aggregates
Fielddata.groups[].truncated Typeboolean DescriptionIncluded as true for an incomplete set of records. Group counts and calculations apply to processed records
Fielddata.meta.totalRecords Typenumber DescriptionTotal number of records matching the filter
Fielddata.meta.recordsProcessed Typenumber DescriptionNumber of processed records, up to 5000. 0 without grouping or numeric functions
Fielddata.meta.truncated Typeboolean Descriptiontrue 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
Fielddata.meta.recordsShortfall Typenumber DescriptionNumber of unread records: totalRecords - recordsProcessed. Included when there is a shortfall, including one caused by the 5000-record ceiling
Fielddata.meta.pageErrorSample Typeobject DescriptionA sample subpage error. Included when an error stopped the read
Fielddata.meta.warnings Typearray DescriptionContains a warning with the code AGGREGATE_TRUNCATED for an incomplete set of records
Fielddata.meta.groupTotal Typenumber DescriptionIncluded with groupBy: the number of groups before applying groupLimit
Fielddata.meta.groupsTruncated Typeboolean DescriptionIncluded with groupBy. true if groups were truncated by groupLimit

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 1,
    "aggregates": {},
    "groups": [
      {
        "active": false,
        "code": "DOCS_PERSON_397F55D8FB1D",
        "count": 1,
        "aggregates": {}
      }
    ],
    "meta": {
      "totalRecords": 1,
      "recordsProcessed": 1,
      "truncated": false,
      "groupTotal": 1,
      "groupsTruncated": false
    }
  }
}

Without groupBy, the response omits data.groups.

Error response example

400 — the string field name was passed to the numeric function sum:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'name' is not numeric (type: string). Only number fields support sum."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe aggregate is not an array or is an empty array
HTTP400 CodeINVALID_PARAMS DescriptionThe aggregate contains more than 5 expressions
HTTP400 CodeINVALID_PARAMS DescriptionThe function is unknown or missing
HTTP400 CodeINVALID_PARAMS DescriptionThe field for count differs from "*"
HTTP400 CodeINVALID_PARAMS DescriptionThe field for sum, avg, min, or max is missing or is "*"
HTTP400 CodeINVALID_PARAMS DescriptionA numeric function received a non-numeric field, such as name
HTTP400 CodeINVALID_PARAMS DescriptionThe numeric function field was not found. The message lists the allowed fields: id, sort
HTTP400 CodeINVALID_PARAMS DescriptionThe op, field, or function was provided at the root without an aggregate array
HTTP400 CodeINVALID_PARAMS DescriptionThe groupBy is neither a string nor an array of strings, or the array contains a value of another type
HTTP400 CodeINVALID_PARAMS DescriptionThe grouping field is neither active nor code
HTTP400 CodeINVALID_PARAMS DescriptionThe groupBy contains more than 5 fields
HTTP400 CodeINVALID_PARAMS DescriptionThe groupBy contains a reserved name: count, aggregates, meta, or groups
HTTP400 CodeINVALID_PARAMS DescriptionThe groupOrderBy was provided without groupBy
HTTP400 CodeINVALID_PARAMS DescriptionThe 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
HTTP400 CodeINVALID_PARAMS DescriptionThe groupLimit was provided without groupBy
HTTP400 CodeINVALID_PARAMS DescriptionThe groupLimit is not an integer from 1 to 1000
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionAn unknown field in filter
HTTP400 CodeINVALID_FILTER_FIELD DescriptionA field name in filter starts with the unsupported prefix @ or !@
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionAn unsupported operator, an empty condition object, or logical conditions with $or / $and
HTTP400 CodeINVALID_FILTER_SHAPE DescriptionThe filter is not a condition object, such as a string, number, or array
HTTP400 CodeINVALID_DUPLICATE_FILTER_FIELD DescriptionTwo filter conditions resolve to the same condition, such as $ne and $nin for one field
HTTP422 CodeAGGREGATION_LIMIT_EXCEEDED DescriptionWith 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
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRequest 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

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

Known specifics

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

See also