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/credit-notes/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 Credit Notes

GET/credit-notes/summary

Access

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

Summary

Returns grouped non-draft credit-note counts, hours and financial totals. Requires read:credit-notes. 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 credit notes are excluded. Agency keys see only their agency’s records and cannot retrieve MSP-to-client credit notes. creditNoteType filters the stored invoice type; invoiceType is a compatibility alias, and creditNoteType takes precedence if both are supplied.

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, processed)	No	Filter by credit note status
creditNoteType	enum(supplierToClient, supplierToMsp, mspToClient)	No	Filter by credit note flow type
invoiceType	string	No	Invoice type; compatibility alias for creditNoteType
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, creditNoteType, month, week. Combine dimensions, for example company,month. Duplicate dimensions are ignored. Default: status.
dateField	enum(createdAt, updatedAt, startDate, endDate, completedDate, approvedDate, date, 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)	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. These groups do not separate currencies automatically. Restrict financial comparisons to records known to use the same currency.

Request Example

curl --get 'https://api.requidex.com/api/open/v1/credit-notes/summary' \
  --header "Authorization: Bearer ${REQUIDEX_API_KEY}" \
  --header 'Accept: application/json' \
  --data-urlencode 'groupBy=status' \
  --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 creditNoteType string or null — Selected creditNoteType 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
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": {
        "status": "pending"
      },
      "count": 2,
      "values": {
        "grossHours": 0,
        "netHours": 0,
        "subtotal": 100,
        "vat": 20,
        "total": 120,
        "cis": 0,
        "finalTotal": 120
      }
    }
  ],
  "meta": {
    "total": 1,
    "groupBy": ["status"],
    "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_credit_notes. 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 Credit Notes for record-level access and detail queries.