Get document counts

GET /v3/connect/invoices/counts returns company-wide Sales and Purchase document counts for usage reporting. The route retains the historical word invoices, but document counts is the canonical term.

This endpoint supports AE, SA, MY, BE, and DE. The company-onboarding POST documented in this section supports UAE only.

This is usage reporting, not an immutable billing ledger: date ranges use the document's latest processing update date.

Endpoint and base URL

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

There is no separate sandbox hostname. Select sandbox or production data with X-Environment.

Authentication and headers

Keep the key server-side and do not send workspaceId.

Counts do not accept simulation. The behavior of companies onboarded in simulation remains undocumented until Engineering confirms it.

Where companyId comes from

companyId is a system-generated opaque value. Obtain it from either:

• data.companyId in a successful UAE onboarding response; or
• data[].id from the Company List API, GET /v3/connect/companies.

Do not substitute sourceName, sourceVersion, sourceId, or branchId.

Query parameters

When dates are omitted, counts are all-time. The date range uses the selected country's local calendar-day boundaries: from at local 00:00:00.000 through to at local 23:59:59.999. It filters updatedAt, with createdAt as fallback, not the document issue date.

The endpoint does not accept sourceName, sourceVersion, sourceId, or branchId as filters. Supplying one returns 400 CONNECT_VALIDATION_ERROR.

Request examples

One onboarding company, both document types

This example uses data.companyId returned by the onboarding walkthrough.

curl --get 'https://prod.gets.complyance.io/v3/connect/invoices/counts' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Environment: sandbox' \
  --header 'Accept: application/json' \
  --data-urlencode 'countryCode=AE' \
  --data-urlencode 'companyId=66b9f0a1c2d3e4f567890123'

All companies, both document types

curl --get 'https://prod.gets.complyance.io/v3/connect/invoices/counts' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Environment: sandbox' \
  --header 'Accept: application/json' \
  --data-urlencode 'countryCode=AE'

Sales documents in a date range

curl --get 'https://prod.gets.complyance.io/v3/connect/invoices/counts' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Environment: sandbox' \
  --header 'Accept: application/json' \
  --data-urlencode 'countryCode=AE' \
  --data-urlencode 'companyId=66b9f0a1c2d3e4f567890123' \
  --data-urlencode 'documentType=sales' \
  --data-urlencode 'from=2026-07-01' \
  --data-urlencode 'to=2026-07-31'

Purchase documents in a date range

curl --get 'https://prod.gets.complyance.io/v3/connect/invoices/counts' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Environment: sandbox' \
  --header 'Accept: application/json' \
  --data-urlencode 'countryCode=AE' \
  --data-urlencode 'companyId=66b9f0a1c2d3e4f567890123' \
  --data-urlencode 'documentType=purchase' \
  --data-urlencode 'from=2026-07-01' \
  --data-urlencode 'to=2026-07-31'

Success response

The shape is stable for every documentType value.

{
  "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-08-14T12:00:00.000Z",
    "filters": {
      "countryCode": "AE",
      "environment": "sandbox",
      "companyId": null,
      "documentType": null,
      "from": null,
      "to": null
    }
  }
}

Response fields

meta.filters always includes countryCode, environment, companyId, documentType, from, and to. Unused optional values are null.

Zero counts and inactive companies

Managed companies with no matching documents remain in data.companies with all counts set to 0. Inactive managed companies remain visible so historical usage is preserved.

When the workspace has no managed companies for the selected country, the response keeps the same shape:

{
  "success": true,
  "data": {
    "totalCount": 0,
    "salesCount": 0,
    "purchaseCount": 0,
    "companies": []
  },
  "meta": {
    "requestId": "01K1EXAMPLE000000000000000",
    "timestamp": "2026-08-14T12:00:00.000Z",
    "filters": {
      "countryCode": "AE",
      "environment": "sandbox",
      "companyId": null,
      "documentType": null,
      "from": null,
      "to": null
    }
  }
}

Counting rules

1. A document counts only when its canonical user-facing status resolves to VALID through the existing country status mapping.
2. Sales and Purchase use the same workspace, country, environment, company, status, and date boundaries.
3. Omitting documentType returns both types.
4. documentType=sales counts only Sales and keeps Purchase fields at 0.
5. documentType=purchase counts only Purchase and keeps Sales fields at 0.
6. totalCount always equals salesCount + purchaseCount at aggregate and company levels.
7. Results are company-wide and scoped to the workspace from the API key.
8. A non-empty unknown, cross-workspace, unmanaged, or wrong-country companyId returns 403 CONNECT_COMPANY_ACCESS_DENIED; a blank value returns 400 CONNECT_COMPANY_ID_REQUIRED.

Whether VALID credit notes and debit notes are included in Sales or Purchase counts remains a Product publication dependency.

Errors

Count errors contain error.code and error.message; this contract does not define error.retryable, error.details, or meta.workspaceId.

{
  "success": false,
  "error": {
    "code": "CONNECT_INVALID_DOCUMENT_TYPE",
    "message": "documentType must be sales or purchase."
  },
  "meta": {
    "requestId": "01K1EXAMPLE000000000000000",
    "timestamp": "2026-08-14T12:00:00.000Z"
  }
}

See Errors and troubleshooting for caller actions.

Rate limit

The endpoint allows 120 requests per minute per workspace. A 429 response includes Retry-After; back off for that rate-limit interval.

Related pages

• Connect API v3 overview
• Onboard a UAE company
• List onboarded companies
• Errors and troubleshooting

Next step: Review error recovery and support information.