# Document counts

Return valid sales and purchase document counts by company, country, environment and date range.

## Endpoint

```http
GET https://prod.gets.complyance.io/v3/connect/invoices/counts
```

## Authentication

Send `X-API-Key`. Send `X-Environment: sandbox` or `X-Environment: production` explicitly; the default is `production`. `simulation` is not accepted.

## Parameters

| Query | Required | Description |
| - | - | - |
| `countryCode` | Yes | `AE`, `SA`, `MY`, `BE` or `DE` |
| `companyId` | No | Returned company identifier; omit to include all managed companies in the country |
| `peppolId` | No | Buyer Peppol participant ID, including its scheme, such as `0235:100000000000003`. Applies to both sales and purchase documents. |
| `source` | No | Exact source name, such as `acme-erp` |
| `version` | No | Exact source version, such as `1.0.0`; can be used with or without `source` |
| `documentType` | No | `sales` or `purchase`; omit for both. `purchase` is singular here, while the [documents API](https://docs.complyance.io/api-reference/purchases/list/) takes `type=purchases`. |
| `from` | With `to` | Inclusive start date, `YYYY-MM-DD` |
| `to` | With `from` | Inclusive end date, `YYYY-MM-DD` |

Dates use the country’s local calendar days and the document’s latest processing update, not its invoice issue date. Omit both dates for all-time counts. These counts support usage reporting; they are not an immutable billing ledger.

The endpoint counts valid documents. All supplied filters must match. Source names and versions are case-sensitive. A source name without a version includes all its versions; a version without a source name includes all sources with that version.

Use `source` and `version` for source filtering. Other source and branch parameters are not accepted: sending `sourceName`, `sourceVersion`, `sourceId`, `branchId` or `transactionType` returns `400`. Use `data.companyId` from onboarding or `data[].companyId` from company listing.

```bash title="Count sandbox documents for September"
curl --get 'https://prod.gets.complyance.io/v3/connect/invoices/counts' \
  --header "X-API-Key: ${COMPLYANCE_API_KEY}" \
  --header 'X-Environment: sandbox' \
  --data-urlencode 'countryCode=AE' \
  --data-urlencode 'from=2026-09-01' \
  --data-urlencode 'to=2026-09-30'
```

```bash title="Count one company's purchases by buyer and source"
curl --get 'https://prod.gets.complyance.io/v3/connect/invoices/counts' \
  --header "X-API-Key: ${COMPLYANCE_API_KEY}" \
  --header 'X-Environment: sandbox' \
  --data-urlencode 'countryCode=AE' \
  --data-urlencode 'companyId=66b9f0a1c2d3e4f567890123' \
  --data-urlencode 'documentType=purchase' \
  --data-urlencode 'peppolId=0235:100000000000003' \
  --data-urlencode 'source=acme-erp' \
  --data-urlencode 'version=1.0.0'
```

## Response

HTTP `200` returns `success: true`, `data` and `meta`. `data` contains `salesCount`, `purchaseCount` and `totalCount`. `data.companies[]` contains per-company counts. When you set `documentType`, only that count is returned: `salesCount` for `sales`, `purchaseCount` for `purchase`, both overall and per company. Companies with no matching documents have zero counts; historical counts remain relevant for inactive companies.

`meta` includes the request identifier, timestamp and applied filters. An omitted filter is represented by `null`.

Example counts for the September date-range request:

```json title="Document counts — HTTP 200"
{
  "success": true,
  "data": {
    "totalCount": 25,
    "salesCount": 17,
    "purchaseCount": 8,
    "companies": [
      {
        "companyId": "66b9f0a1c2d3e4f567890123",
        "totalCount": 20,
        "salesCount": 14,
        "purchaseCount": 6
      },
      {
        "companyId": "66b9f0a1c2d3e4f567890456",
        "totalCount": 5,
        "salesCount": 3,
        "purchaseCount": 2
      }
    ]
  },
  "meta": {
    "requestId": "01K1EXAMPLE000000000000000",
    "timestamp": "2026-09-22T10:00:00.000Z",
    "filters": {
      "countryCode": "AE",
      "environment": "sandbox",
      "companyId": null,
      "peppolId": null,
      "source": null,
      "version": null,
      "documentType": null,
      "from": "2026-09-01",
      "to": "2026-09-30"
    }
  }
}
```

## Errors

| Code | Correction |
| - | - |
| `CONNECT_UNSUPPORTED_COUNTRY` | Use one of the supported country codes |
| `CONNECT_INVALID_ENVIRONMENT` | Send `sandbox` or `production` |
| `CONNECT_VALIDATION_ERROR` | Use a Peppol ID with its scheme and identifier. Do not send blank `source` or `version` values or unsupported filters. |
| `CONNECT_INVALID_DOCUMENT_TYPE` | Send lowercase `sales` or singular `purchase` |
| `CONNECT_DATE_RANGE_INCOMPLETE` | Supply both dates or neither |
| `CONNECT_INVALID_DATE_RANGE` | Ensure `from` is not later than `to` |
| `CONNECT_COMPANY_ACCESS_DENIED` | Use a company managed by this workspace in this country |
| `CONNECT_RATE_LIMIT_EXCEEDED` | Respect `Retry-After`; the limit is 120 requests per workspace per minute |

See [Connect errors](https://docs.complyance.io/api-reference/connect/errors/) for authentication and temporary failures.

Last updated 23 October 2026

Source: https://docs.complyance.io/api-reference/connect/invoice-counts/