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. Numeric functions (sum/avg/min/max) accept any field of type number, but on a contact those are identifiers — a meaningful sum usually comes from 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 Bitrix24 account is returned in the INVALID_PARAMS error text if you pass a non-existent name.

Request fields (body)

Examples

curl — personal key

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

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/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

const res = await fetch('https://vibecode.bitrix24.com/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 application

const res = await fetch('https://vibecode.bitrix24.com/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 Bitrix24 account — the fastest query, with no record retrieval:

{}

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

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

Response fields

Response example

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

{
  "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:

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

Errors

Full list of common API errors — Errors.

Known specifics

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

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

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 contacts
• Search contacts
• Filtering syntax
• Limits and optimization