Integration Workflows
These workflows show how the API and webhooks can support programme reporting, workforce synchronisation and finance integrations. Each uses existing operations; the endpoint reference defines the exact fields, permissions and restrictions.
Programme and supplier reporting
Use a company-scoped key assigned to the hiring companies in the programme. Aggregate records on the server instead of downloading every page for a dashboard.
| Question | Endpoint | Scope |
|---|---|---|
| How much demand remains unfilled? | Summarise Requisitions | read:requisitions |
| What is the assignment count, worker count and pay/charge value? | Summarise Assignments | read:assignments |
| What are the hours, charge, pay and expenses by period or supplier? | Summarise Timesheets | read:timesheets |
| How do expense values vary by category? | Summarise Expenses | read:timesheets |
| What are invoice and credit-note totals? | Summarise Invoices and Summarise Credit Notes | read:invoices, read:credit-notes |
| What are the recruitment turnaround metrics? | List Recruitment Metrics | read:requisitions; stage tracking must be enabled |
Combine supported grouping dimensions, such as company,agency,month, and restrict date ranges. Summary responses contain up to 500 groups with no continuation token, so split large reports into smaller date ranges or company sets.
Read the aggregation notes before combining results. Requisition demand can repeat across agency groups; multi-project invoice groups are not apportioned. Invoice summaries separate currency, while other summaries do not automatically separate or convert currencies. Filter financial comparisons to compatible records and retain the currency context in downstream reports.
Event-driven record synchronisation
- Subscribe to the relevant webhook events for each hiring company or agency.
- Verify signatures and deduplicate by event ID, then enqueue the accepted notification.
- Fetch the affected record using its detail endpoint and an API key with the required read scope.
- Update your system using the Requidex record ID as the external reference.
- Reconcile important datasets periodically to detect notifications that could not be delivered.
Webhooks contain resource IDs rather than a full change history. Handle deletion events without fetching the removed record. A delayed event may lead to a detail response containing a later state; design updates to be repeatable and safe when notifications arrive out of order.
Agency workforce and document integration
Agency keys with write:workers can create or update their workers. Discover valid trade and qualification IDs through Master Trades and Master Qualifications.
Worker creation checks for existing matches. A potential match returns 409 WORKER_MATCH_REQUIRES_REVIEW; it must be reviewed in Requidex rather than linked automatically by the integration. For existing-worker document updates, follow File Uploads, including the replacement semantics for file arrays.
Company keys with read:workers can query permitted workers and supported document-expiry filters. Authorised company callers with write:workers can validate worker documents. These are distinct access models; company keys cannot use agency worker create/update operations.
Finance reconciliation
Read invoices, applications for payment, payment notices and credit notes using their existing references and relationships to reconcile with a finance system.
Use write:invoices only when the integration must update invoice status. Agency callers also need the hiring company's permitted invoice-status action. A paid update requires a payment date and reference; its remittance attachment is optional. Check the current state before retrying an uncertain write, as repeating the paid state does not replace existing payment details.
Company keys can also create and update purchase orders with write:purchase-orders, subject to the endpoint's permissions and validation rules.
Plan the integration boundary
Keep an explicit mapping between your client or programme identifiers and Requidex company, project, agency and worker IDs. Grant each integration only its required companies or agencies and scopes. Company-level reporting access is not interchangeable with an agency key's supplier-specific access.
Choose the supported workflow before selecting write scopes. The endpoint catalogue is the current API surface; portal actions that have no documented endpoint are not implied to be available through the API. Confirm additional lifecycle actions before making them part of your integration design.