Aggregate requisites

POST /v1/requisites/aggregate

Counts requisites with filtering and grouping.

Standard fields for groupBy:

• rqInn, rqKpp, rqOgrn, rqOgrnip, rqOkpo — tax/registration identifiers
• rqVatId — VAT / tax number (used by international account presets)
• rqResidenceCountry — country of residence
• rqCompanyName — company name
• entityTypeId — owner type (1 — lead, 3 — contact, 4 — company)
• presetId — requisite preset
• active — active flag

All fields in aggregatable are identifiers and categorical codes, so groupBy works on them. Grouping by rqVatId (or another identifier) is the fastest way to find duplicate requisites in a single call, without fetching every record. Numeric functions (sum/avg/min/max) are not available on these fields (they are strings) — use numeric-typed custom UF fields for those.

The count contract. The count function accepts ONLY field: "*" — { "field": "*", "function": "count" }. Passing field: "id" (or any other name) returns 400 INVALID_PARAMS with the message count aggregate requires field "*". This is intentional: count counts rows, not the values of a specific field.

Custom fields (UF): UF fields of type integer, double, money work with numeric functions; UF fields of any type work with groupBy. String-type UF fields of a requisite — tax ID, phone number, address — are available only in groupBy. The full list of UF fields for a specific Bitrix24 account is returned in the INVALID_PARAMS error message if you pass a nonexistent name.

Request fields (body)

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/requisites/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "active": true },
    "groupBy": "entityTypeId"
  }'

curl — OAuth app

curl -X POST "https://vibecode.bitrix24.com/v1/requisites/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "active": true },
    "groupBy": "entityTypeId"
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/requisites/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { active: true },
    groupBy: 'entityTypeId',
  }),
})

const { success, data } = await res.json()
console.log('Total active requisites:', data.count)
console.log('By owner type:', data.groups)

JavaScript — OAuth app

const res = await fetch('https://vibecode.bitrix24.com/v1/requisites/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { active: true },
    groupBy: 'entityTypeId',
  }),
})

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

To group by multiple fields, pass an array: "groupBy": ["entityTypeId", "presetId"] (max 5).

Other scenarios

The blocks below are request bodies.

The total number of requisites in the Bitrix24 account — the fastest request, without fetching records:

{}

Find duplicates by VAT ID in a single call — groups with count > 1 contain the duplicated VAT IDs:

{ "aggregate": [{ "field": "*", "function": "count" }], "groupBy": "rqVatId" }

Grouping by a UF field (any type — for example, a custom classifier):

{ "groupBy": "UF_CRM_CLASSIFIER" }

Response fields

Response example

Response to the main request (groupBy: "entityTypeId"):

{
  "success": true,
  "data": {
    "count": 164,
    "aggregates": {},
    "groups": [
      { "entityTypeId": 4, "count": 120 },
      { "entityTypeId": 3, "count": 40 },
      { "entityTypeId": 1, "count": 4 }
    ],
    "meta": {
      "totalRecords": 164,
      "recordsProcessed": 164,
      "truncated": false
    }
  }
}

Without groupBy, the data.groups field is absent from the response.

Error response example

403 — no scope:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "Requires 'crm' scope"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

Money fields. UF fields of type money are stored in the format "amount|currency" ("1500|USD") — the aggregate extracts the numeric part automatically, so you can sum them without parsing.

Without the aggregate array — only count. If you do not pass aggregate, the method returns the count of records matching the filter.

Filtering by UF works. In filter you can pass any fields — standard and custom, of any type. For example, { "filter": { "UF_CRM_1234": "value" } } returns the number of requisites with that UF value.

The 5000-record ceiling. Numeric functions and grouping fetch records page by page, up to 5000. If more records match the filter, the response arrives with meta.truncated: true. Take the exact count from data.count — it comes from a separate count and is correct at any result-set size. The ceiling is not the only reason for this marker: it also appears when fewer records were read than data.count promised, and the size of the gap is reported in data.meta.recordsShortfall.

The truncation marker travels with the number itself. When a response arrives with meta.truncated: true, the marker truncated: true sits inside every field object in data.aggregates and on every element of data.groups, and data.meta.warnings gains a warning with the code AGGREGATE_TRUNCATED. A client that reads only the number itself therefore sees that it was computed over only some of the records. None of these markers appear on a complete response. Full details — Aggregation POST — the 5000-record ceiling.

See also

• List requisites
• Search requisites
• Filtering syntax
• Limits and optimization