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/expenses/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 Expenses

GET/expenses/summary

Access

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

Summary

Returns grouped expense counts, expense value, hours and working-rule-agreement days paid. Requires read:timesheets. 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.

Expenses remain subject to the related timesheet’s current-week cutoff. category uses an exact category filter; query searches category and description. Hour and day values are separate measures and must not be combined.

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
timesheet	string	No	Filter by timesheet id
worker	string	No	Filter by worker id
status	enum(pending, approved, rejected)	No	Filter by expense status
category	enum(Accommodation, Bonus, Driving hours, Flat rate hours, Fuel, Manager authorised hours, Mileage, On-call, Other, Out-of-hours callout, Parking, Plant, Price work, Training hours, Vehicles)	No	Filter by exact expense category. Supported values: Accommodation, Bonus, Driving hours, Flat rate hours, Fuel, Manager authorised hours, Mileage, On-call, Other, Out-of-hours callout, Parking, Plant, Price work, Training hours, Vehicles.
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, category, month, week. Combine dimensions, for example company,month. Duplicate dimensions are ignored. Default: category.
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: date.
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, value, hours, wraDaysPaid)	No	Metric used to sort groups Default: value.
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/expenses/summary' \
  --header "Authorization: Bearer ${REQUIDEX_API_KEY}" \
  --header 'Accept: application/json' \
  --data-urlencode 'groupBy=category' \
  --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 category string or null — Selected category 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 value number — Expense value hours number — Gross hours wraDaysPaid number — Working-rule-agreement days paid
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": {
        "category": "Travel"
      },
      "count": 2,
      "values": {
        "value": 50,
        "hours": 2,
        "wraDaysPaid": 0
      }
    }
  ],
  "meta": {
    "total": 1,
    "groupBy": ["category"],
    "dateField": "date",
    "sortBy": "value",
    "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_expenses. 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 Expenses for record-level access and detail queries.