Try a request

Loading API specification…

API keyBearer authentication

Held in memory for this tab only. Clear it or refresh to forget it.

Code examplecURLJavaScriptPython

curl --request GET \
  --url 'https://api.requidex.com/api/open/v1/invoices/summary' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Accept: application/json'

Requests go directly to the production API and use your key’s scopes and rate limits. GET requests only.

Summarise Invoices

GET/invoices/summary

Access

Requirement	Value
Scope	read:invoices
Company-scoped keys	Supported
Agency-scoped keys	Supported within agency access

Summary

Returns grouped non-draft invoice counts, hours and financial totals, separated by currency. Requires read:invoices. Company and agency keys are supported, within their existing data access. Filtering or grouping by another agency does not expand an agency key's access.

Draft invoices and applications for payment are excluded. Agency keys see only their agency’s invoices and cannot retrieve MSP-to-client invoices. Currency is always part of each group: totals in different currencies are never combined or converted. When grouping by project, an invoice linked to several projects contributes its full values to each project group; those groups must not be summed as an apportioned programme total.

Query Parameters

Name	Type	Required	Description
company	string	No	Filter by company id(s). Pass a single id or comma-separated ids. If omitted, data for all companies linked to the API key is returned.
agency	string	No	Filter by agency id
project	string	No	Filter by project id
status	enum(pending, confirmed)	No	Filter by invoice status
invoiceType	enum(supplierToClient, supplierToMsp, mspToClient)	No	Filter by invoice flow type. supplierToClient is direct client-billable supplier invoice value; mspToClient is client-billable MSP invoice value; supplierToMsp is supplier-to-MSP payable value.
mspInvoiceType	enum(receivable, payable)	No	Filter by MSP invoice subtype
query	string	No	Case-insensitive text search across the resource’s supported reference and name fields
groupBy	string	No	Comma-separated grouping dimensions: agency, company, project, status, invoiceType, month, week. Combine dimensions, for example company,month. Duplicate dimensions are ignored. Default: agency.
dateField	enum(createdAt, issueDate, confirmedDate, due, weekEnding, we)	No	Date used for range filtering and month/week groups. Choose a date populated on the source records. Default: createdAt.
from	string	No	Date range start (YYYY-MM-DD), applied to dateField
to	string	No	Date range end (YYYY-MM-DD), applied to dateField
sortBy	enum(count, grossHours, netHours, subtotal, vat, total, cis, finalTotal, expenses, creditNotes, netValue)	No	Metric used to sort groups Default: finalTotal.
sortOrder	enum(asc, desc)	No	Group sort direction Default: desc.
limit	integer	No	Maximum groups returned; capped at 500. No page parameter or continuation token is provided. Default: 500.

Aggregation rules

• Results contain at most 500 groups. There is no pagination or continuation token; narrow the filters or split date ranges when more groups are needed.
• meta.total is the number of groups returned after limiting, not the total matching records or all possible groups.
• Month groups use YYYY-MM; ISO week groups use YYYY-Www. Both use UTC and the selected dateField; a missing selected date produces a null date bucket when no date range excludes it.
• Measures are reported from stored values without currency conversion. Invoice groups are always separated by currency.

Request Example

curl --get 'https://api.requidex.com/api/open/v1/invoices/summary' \
  --header "Authorization: Bearer ${REQUIDEX_API_KEY}" \
  --header 'Accept: application/json' \
  --data-urlencode 'groupBy=agency' \
  --data-urlencode 'limit=50' \
  --max-time 30

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
data	array of objects	Returned groups Show child attributes group object — Selected grouping dimensions Show child attributes agency object or null — Selected agency dimension; present only when included in groupBy Show child attributes id string or null — Resource identifier name string or null — Resource name company object or null — Selected company dimension; present only when included in groupBy Show child attributes id string or null — Resource identifier name string or null — Resource name project object or null — Selected project dimension; present only when included in groupBy Show child attributes id string or null — Resource identifier name string or null — Resource name status string or null — Selected status dimension; present only when included in groupBy invoiceType string or null — Selected invoiceType dimension; present only when included in groupBy month string or null — Selected month dimension; present only when included in groupBy week string or null — Selected week dimension; present only when included in groupBy count integer — Number of matching records represented in the group values object — Aggregated measures for the group Show child attributes grossHours number — Gross hours netHours number — Net hours subtotal number — Subtotal before VAT vat number — VAT amount total number — Total amount cis number — CIS deduction amount finalTotal number — Final total expenses number — Expense amount creditNotes number — Credit-note amount netValue number — Net value after the stored adjustments currency string — Currency of this group; no conversion is performed
meta	object	Applied summary settings Show child attributes total integer — Groups returned after applying limit; not the total source records or all possible groups groupBy array — Selected grouping dimensions dateField string — Date field used for filtering and date buckets sortBy string — Applied metric sort sortOrder string — Applied sort direction limit integer — Applied group limit

Response Example (200)

{
  "success": true,
  "data": [
    {
      "group": {
        "agency": {
          "id": "507f1f77bcf86cd799439011",
          "name": "Example agency"
        }
      },
      "count": 2,
      "values": {
        "grossHours": 80,
        "netHours": 75,
        "subtotal": 1800,
        "vat": 360,
        "total": 2160,
        "cis": 0,
        "finalTotal": 2160,
        "expenses": 0,
        "creditNotes": 0,
        "netValue": 2160
      },
      "currency": "GBP"
    }
  ],
  "meta": {
    "total": 1,
    "groupBy": ["agency"],
    "dateField": "createdAt",
    "sortBy": "finalTotal",
    "sortOrder": "desc",
    "limit": 50
  }
}

The example is illustrative. An empty result has data: [] and meta.total: 0.

MCP Tool

The corresponding MCP tool is summarize_invoices. It uses this server-side summary operation and retains the caller’s scopes and tenant restrictions.

Errors

HTTP status	Code	Meaning
400	BAD_REQUEST	Invalid grouping dimension, date field, filter or date range
401	UNAUTHORIZED	Missing, invalid, expired or revoked key
403	FORBIDDEN	Missing scope or disallowed access
429	RATE_LIMITED or DAILY_RATE_LIMITED	Key quota exceeded
500	INTERNAL_ERROR	Unable to return the summary

See Responses and Errors for shared handling, and List Invoices for record-level access and detail queries.