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/requisitions/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 Requisitions

GET/requisitions/summary

Access

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

Summary

Returns grouped requisition counts, requested quantity, assigned quantity and remaining demand. Requires read:requisitions. 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.

When grouped by agency, assignedQuantity counts that agency’s non-cancelled assignments, and openQuantity is demand minus that count, floored at zero. Shared demand can appear in more than one agency group: do not sum those groups to calculate programme-wide open demand. Without agency grouping, totals remain at requisition level. Agency keys see only approved requisitions available to their agencies; status restrictions and the open alias match the list endpoint.

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(s). Pass a single id or comma-separated ids.
project	string	No	Filter by project id(s). Pass a single id or comma-separated ids.
site	string	No	Filter by site id(s). Pass a single id or comma-separated ids.
trade	string	No	Filter by trade id(s). Pass a single id or comma-separated ids.
status	enum(open, raised, approved, filled, cancelled, rejected)	No	Filter by derived requisition status. open is an alias for approved and returns approved, active, unfilled requisitions. Agency-scoped API keys may use only open, approved, filled, or cancelled because raised and rejected requisitions are not available to agencies.
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, trade, status, 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, quantity, assignedQuantity, openQuantity)	No	Metric used to sort groups Default: quantity.
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/requisitions/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 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 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 quantity number — Requested worker quantity assignedQuantity number — Assigned worker quantity openQuantity number — Unfilled requested quantity, floored at zero per requisition
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": "approved"
      },
      "count": 2,
      "values": {
        "quantity": 6,
        "assignedQuantity": 4,
        "openQuantity": 2
      }
    }
  ],
  "meta": {
    "total": 1,
    "groupBy": ["status"],
    "dateField": "createdAt",
    "sortBy": "quantity",
    "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_requisitions. 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 Requisitions for record-level access and detail queries.