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/timesheets/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 Timesheets

GET/timesheets/summary

Access

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

Summary

Returns grouped timesheet counts, hours, charge and pay values, expenses and worker counts. 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.

Date ranges intersect the current-week cutoff; a later to does not include future timesheets beyond that cutoff. startDate, endDate and we are compatibility aliases for start, end and weekEnding. Gross hours and netHours are separate measures. Trade and purchase-order groups use the related assignment; purchaseOrder contains the purchase-order reference. Distinct workers are counted within each group.

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
site	string	No	Filter by site id
assignment	string	No	Filter by assignment id
worker	string	No	Filter by worker id
status	enum(pending, pending_approval, approved, cancelled, absent)	No	Filter by timesheet status
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, site, worker, trade, purchaseOrder, status, month, week. Combine dimensions, for example company,month. Duplicate dimensions are ignored. Default: status.
dateField	enum(createdAt, updatedAt, start, startDate, end, endDate, approvedDate, weekEnding, we)	No	Date used for range filtering and month/week groups. Choose a date populated on the source records. Default: weekEnding.
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, hours, netHours, chargeValue, payValue, expenseValue, distinctWorkers, chargeWdBasic, chargeWdOvertime, chargeNightwork, chargeWeekend, chargeBankHoliday, payWdBasic, payWdOvertime, payNightwork, payWeekend, payBankHoliday)	No	Metric used to sort groups Default: chargeValue.
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/timesheets/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 site object or null — Selected site dimension; present only when included in groupBy Show child attributes id string or null — Resource identifier name string or null — Resource name worker object or null — Selected worker dimension; present only when included in groupBy Show child attributes id string or null — Resource identifier name string or null — Resource name trade object or null — Selected trade dimension; present only when included in groupBy Show child attributes id string or null — Resource identifier name string or null — Resource name purchaseOrder string or null — Selected purchaseOrder dimension; present only when included in groupBy status string or null — Selected status 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 hours number — Gross hours netHours number — Net hours chargeValue number — Charge value payValue number — Pay value expenseValue number — Expense value distinctWorkers number — Number of distinct workers in this group chargeWdBasic number — Charge wd basic value chargeWdOvertime number — Charge wd overtime value chargeNightwork number — Charge nightwork value chargeWeekend number — Charge weekend value chargeBankHoliday number — Charge bank holiday value payWdBasic number — Pay wd basic value payWdOvertime number — Pay wd overtime value payNightwork number — Pay nightwork value payWeekend number — Pay weekend value payBankHoliday number — Pay bank holiday value
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": {
        "hours": 80,
        "netHours": 75,
        "chargeValue": 1800,
        "payValue": 1350,
        "expenseValue": 50,
        "distinctWorkers": 2,
        "chargeWdBasic": 1800,
        "chargeWdOvertime": 0,
        "chargeNightwork": 0,
        "chargeWeekend": 0,
        "chargeBankHoliday": 0,
        "payWdBasic": 1350,
        "payWdOvertime": 0,
        "payNightwork": 0,
        "payWeekend": 0,
        "payBankHoliday": 0
      }
    }
  ],
  "meta": {
    "total": 1,
    "groupBy": ["status"],
    "dateField": "weekEnding",
    "sortBy": "chargeValue",
    "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_timesheets. 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 Timesheets for record-level access and detail queries.