---
title: "Aggregate Invoices"
method: POST
path: "/crm/invoices/aggregate"
tags: ["CRM Service Calls", "CRM Aggregate"]
---

# Aggregate Invoices

`POST /crm/invoices/aggregate`

## Request

- Base URL: `https://fapi.ambivo.com` (the document declares no server; this is the origin it was published from)
- URL: `https://fapi.ambivo.com/crm/invoices/aggregate`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/ambivo/apis/ambivo-api/docs/crm/invoices/aggregate/post.ts> (a function with typed inputs; its response is checked against the schema)

Aggregate invoices by group-by fields — ideal for dashboards, charts, and analytics.

Use this endpoint to build invoice status distributions, revenue charts by stage,
or AR (accounts receivable) dashboards.

**Request Body (AggregateRequest):** Same as leads/aggregate.

**Examples:**
- Invoices by stage: `{"group_by_fields": ["stage"]}`
- Invoices by stage with amount: `{"group_by_fields": ["stage"], "aggregate_field": "total_amount"}`

## Request body

- AggregateRequest: Request body for aggregate/group-by queries.
  - `group_by_fields` string[], required: Fields to group by, e.g. ["lead_status"], ["stage", "marketing_source"]
  - `aggregate_field` string, nullable: Numeric field to aggregate, e.g. "value_of_sale", "estimated_budget"
  - `match_filter_dict` string, nullable: JSON-stringified MongoDB filter to narrow the dataset before aggregation
  - `sort_dict` string, nullable: JSON-stringified sort criteria, e.g. {"count": -1}
  - `page_size` integer: Maximum number of groups to return
  - `page_num` integer: Page number (1-indexed)

## Response `200`

Successful Response

- AggregateResponse: Response for aggregate queries.
  - `groups` AggregateGroup[]: List of aggregate groups
    - `group_by` string: Human-readable label e.g. "Status: contacted"
    - `group_by_values` object, nullable: Programmatic values e.g. {"lead_status": "contacted"}
    - `count` integer: Number of records in this group
    - `total_value` number, nullable: Sum of aggregate_field
    - `avg_value` number, nullable: Average of aggregate_field
    - `max_value` number, nullable: Max of aggregate_field
    - `min_value` number, nullable: Min of aggregate_field
    - `entity_ids_list` unknown[], nullable: List of entity IDs in this group
      - unknown
  - `total_groups` integer: Total number of groups returned
  - `aggregate_field` string, nullable: The numeric field that was aggregated
  - `group_by_fields` string[]: Fields that were grouped by

## Other responses

- `422`: Validation Error

## Changes

- **2026-08-06** `165a6d16a9a0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ambivo/apis/ambivo-api/changes/crm/invoices/aggregate/post.md)

---

[API](https://skmtc.dev/ambivo/apis/ambivo-api.md) - [All operations](https://skmtc.dev/ambivo/apis/ambivo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ambivo/apis/ambivo-api/revisions/165a6d16a9a0?raw)