#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 (for non-RU countries)
• 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 rqInn (or another identifier) is the fastest way to find duplicate requisites in a single call, without exporting 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 — for numeric functions; UF of any type — for groupBy. In practice a requisite usually has string-type UF fields (tax ID, phone number, address) — they can only be used in groupBy. The full list of a specific Bitrix24 account's UF fields comes in the text of the INVALID_PARAMS error 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 total number of requisites in the Bitrix24 account — the fastest request, without fetching records:

{}

Find duplicates by tax ID in a single call — groups with count > 1 hold the repeated values:

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

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, you can sum them without parsing.

Without the aggregate array — count only. If you do not pass aggregate, the method returns the count of records subject to 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.

5000-record limit. If more than 5000 records match the filter, the result is flagged meta.truncated: true. For an exact count of large result sets use meta.total in the GET /v1/requisites response with limit=1 — it holds the real count.

#See also

• List requisites — meta.total gives the exact record count
• Search requisites — POST request with filters
• Filtering syntax
• Limits and optimization — rate limits