#Aggregate contacts

POST /v1/contacts/aggregate

Count contacts with filtering and grouping.

Standard fields:

  • typeId — contact type (for groupBy)
  • sourceId — source (for groupBy)
  • assignedById — assigned user (for groupBy)

All fields in aggregatable are categorical identifiers, so count and groupBy work on the standard fields. For numeric functions (sum/avg/min/max) use user fields.

User fields (UF): UF fields of types integer, double, money — for numeric functions; UF of any type — for groupBy. The full list of UF fields for a specific portal is returned in the INVALID_PARAMS error text if you pass a non-existent name.

#Request fields (body)

Parameter Type Required Description
aggregate array no Array of aggregations. Each element: { "field": "*", "function": "count" }. Without the array — only count
filter object no Filtering by GET /v1/contacts/fields fields. Filtering syntax
groupBy string | string[] no Field or array of fields to group by (maximum 5). Allowed values — from the list above

#Examples

#curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/contacts/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "assignedById": 1 },
    "groupBy": "typeId"
  }'

#curl — OAuth app

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/contacts/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "assignedById": 1 },
    "groupBy": "typeId"
  }'

#JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/contacts/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { assignedById: 1 },
    groupBy: 'typeId',
  }),
})

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

#JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/contacts/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { assignedById: 1 },
    groupBy: 'typeId',
  }),
})

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

To group by multiple fields, pass an array: "groupBy": ["typeId", "sourceId"] (maximum 5).

#Other scenarios

Total number of contacts in the portal — the fastest query, with no record retrieval:

JSON 
{}

Working with user fields (UF) — sum over a UF + grouping by another UF:

JSON 
{
  "aggregate": [{ "field": "UF_CRM_LTV", "function": "sum" }],
  "groupBy": "UF_CRM_SEGMENT"
}

#Response fields

Field Type Description
success boolean Always true on success
data.count number Total number of records matching the filter
data.aggregates object Aggregation results (usually empty for contacts)
data.groups array Groups (only with groupBy). Each element: grouping fields + count
data.meta.totalRecords number Total number of records matching the filter
data.meta.recordsProcessed number How many records were processed (for count — 0, records are not retrieved)
data.meta.truncated boolean true if more than 5000 records matched the filter

#Response example

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

JSON 
{
  "success": true,
  "data": {
    "count": 1200,
    "aggregates": {},
    "groups": [
      { "typeId": "CLIENT", "count": 800 },
      { "typeId": "SUPPLIER", "count": 300 },
      { "typeId": "PARTNER", "count": 100 }
    ],
    "meta": {
      "totalRecords": 1200,
      "recordsProcessed": 1200,
      "truncated": false
    }
  }
}

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

#Error response example

400 — groupBy by a non-aggregatable or non-existent field:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'name' is not aggregatable on this entity. Available: typeId, sourceId, assignedById"
  }
}

#Errors

HTTP Code Description
400 INVALID_PARAMS groupBy by a non-aggregatable field or more than 5 fields in groupBy
401 TOKEN_MISSING API key has no configured tokens
403 SCOPE_DENIED API key lacks the crm scope

Full list of common API errors — Errors.

#Known specifics

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

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

#See also