FAQ
This page answers common questions about integrating with the Requidex Open API, webhooks, and MCP tools.
Access and authentication
How do I get an API key?
Request access through your Requidex account manager. Each key is issued for an approved purpose with an access type, tenant access, and explicit scopes.
Is the full API key shown again after creation?
No. The full key is shown once when it is created. Copy it into an approved secret manager at that point. Requidex stores a hash of the key and cannot display the original value later.
Where should I send API requests?
Use the production base URL:
https://api.requidex.com/api/open/v1
Do not add another /api/open/v1 segment when using this base URL.
What authentication type is supported?
Send the API key as a Bearer token on every request:
Authorization: Bearer <API_KEY>
Never put an API key in a URL, browser application, mobile application, source repository, log, support ticket, or other location where it may be exposed.
How can I check which key and permissions I am using?
Call GET /me. It returns information about the authenticated key and its effective access without exposing the key secret.
Is there a sandbox environment?
No. Open API access is production-only. Use narrowly scoped keys, conservative filters, small page sizes, and non-destructive test cases when validating a new integration.
Can one key access more than one company or agency?
Yes, when those entities have been assigned to the key. A key can be company-scoped or agency-scoped, but not both. Requests remain limited to the entities and scopes attached to that key.
What is the difference between company-scoped and agency-scoped keys?
Company-scoped keys can access permitted data for their assigned companies. Agency-scoped keys are limited to their assigned agencies and to data for companies connected to those agencies. Some company-level endpoints and write operations are not available to agency-scoped keys. See Authorization and Scopes and the warning on each restricted endpoint.
Scopes and write access
How do scopes work?
Every endpoint checks for a specific scope, such as read:workers or write:workers. A key receives no implicit access outside its configured scopes. Use the smallest set of scopes required for the integration.
Does a read scope allow data to be changed?
No. Read scopes authorize supported GET operations only. They can still expose sensitive business or personal data, so read keys must be protected and governed carefully.
Are write methods supported?
Most endpoints are read-only. A write operation is available only when it is documented and the key has the corresponding write scope. Unsupported methods return 405 METHOD_NOT_ALLOWED.
Why does Requidex show a warning when I grant a write scope?
A write-enabled key can change data in the platform. If it is exposed, misused, or configured incorrectly, the impact may be serious or difficult to reverse. Grant write access only to a trusted system, store the key securely, and test the integration with particular care.
Can an agency-scoped key use write scopes?
Only where the scope and endpoint explicitly support agency access. For example, write:workers and the worker-document validation endpoint are company-scoped and are not available to agency-scoped keys.
Can I use an undocumented POST, PUT, PATCH, or DELETE operation?
No. Internal application routes are not part of the Open API contract. Use only operations listed in the Endpoint Reference.
Querying and responses
How does pagination work?
List endpoints use page and limit. The default page is 1, the default limit is 50, and the maximum limit is 200. Paginated responses include meta.page, meta.limit, and meta.total.
How do I retrieve more than 200 records?
Request consecutive pages and stop when the returned data and pagination metadata show that there are no more records. Keep the same filters and sorting across the paging run so that results remain predictable.
Can I reduce the response payload?
Yes. List endpoints that document fields accept a comma-separated field list. Request only the fields your integration needs, especially when handling workers, documents, financial records, or other sensitive data.
Which filters, date fields, and sort values can I use?
They vary by endpoint. The relevant Endpoint Reference page is authoritative. Common controls include query, from, to, sortBy, and sortOrder, while some endpoints also expose entity, status, or dateField filters. See Querying.
What date format should I send?
Date-only query parameters use YYYY-MM-DD unless the endpoint says otherwise. Response timestamps are returned in ISO 8601 format. Do not infer a local timezone from a timestamp ending in Z; it represents UTC.
Can response fields be null or absent?
Yes. Visibility, feature configuration, record state, and the selected fields can affect which values are present. Treat nullable and optional fields defensively. Additive response fields may also appear over time.
What does a successful response look like?
Responses use a consistent envelope containing success, data, and, where applicable, meta. See Responses and Errors and the response example on the endpoint page.
Can I use an ObjectId or a Requidex reference in an {id} parameter?
Identifier support is endpoint-specific. Some detail endpoints accept an ObjectId or internal nanoid, while others require a particular identifier. Follow the URL parameter description on the relevant endpoint page.
Errors, limits, and reliability
What is the difference between 401 and 403?
401 UNAUTHORIZED normally means the credential is missing, invalid, revoked, or expired. 403 FORBIDDEN means the request was authenticated but is not permitted, for example because a scope, tenant assignment, IP allowlist, HTTPS requirement, or caller type does not allow it.
Why am I receiving 404 for a record that exists in Requidex?
Check the identifier and the key's tenant access. A record outside the companies or agencies assigned to the key is not available through that key. Also confirm that the endpoint supports the identifier type you supplied.
How should I handle rate limits?
Rate limits apply per API key. New keys default to 60 requests per minute and 5000 requests per day, although configured limits may differ. On 429 RATE_LIMITED, pause and retry with exponential backoff and jitter rather than immediately repeating the request. See Rate Limits.
Should I retry failed requests?
Retry 429 and transient 5xx responses with a bounded exponential-backoff policy. Do not automatically retry authentication, authorization, validation, or not-found failures without first correcting the request. Set an explicit timeout and log the status and error code without logging the API key or sensitive response data.
Are Open API requests idempotent?
GET requests are safe to repeat. Do not assume a write operation is idempotent unless its Endpoint Reference explicitly says so. Prevent duplicate submissions in your own integration and verify the result before retrying an uncertain write request.
Key security and lifecycle
How should I store an API key?
Use a server-side secret manager or equivalent protected credential store. Restrict who and what can read it, avoid copying it between environments, and never expose it to client-side code.
Can I restrict where a key is used from?
Yes. A key can have an IP allowlist, an expiry date, per-minute and per-day limits, tenant assignments, and scopes. Combine these controls rather than relying on the key value alone.
Do API keys expire automatically when unused?
Yes. Requidex automatically revokes a key that has not been used for 30 days. For a key that has never been used, the 30-day period starts when it is created. A configured expiry date may revoke access sooner.
What should I do if a key may have been exposed?
Revoke it immediately, issue a replacement with the minimum required access, update the consuming system, and review the API audit logs for unexpected use. Do not wait for the inactivity or expiry controls to take effect.
Can Requidex audit API activity?
Yes. API use and failed authentication attempts are logged for operational and forensic review. Avoid placing unnecessary personal data or secrets in free-text query values that may be captured by operational logging.
Webhooks
Should I poll the API or use webhooks?
Use webhooks for supported lifecycle events when you need near real-time notification, then fetch the latest record through the Open API if required. Use polling for reconciliation or for data that does not have a corresponding event. Avoid aggressive polling.
How do I know a webhook came from Requidex?
Verify X-Requidex-Signature against the raw request body and webhook signing secret, and reject stale timestamps. Keep the signing secret separate from API keys. See Webhooks for the signing procedure.
Can the same webhook be delivered more than once?
Yes. Delivery is at-least-once, so duplicate and out-of-order events are possible. Store and deduplicate by X-Requidex-Event-Id, and make the receiving handler idempotent.
What should my webhook endpoint return?
Return a 2xx response promptly after safely accepting the event. Non-2xx responses and timeouts are retried. If processing takes longer, acknowledge first and move the work to a durable queue.
MCP and AI services
What is the Requidex MCP server?
The MCP server presents supported Open API operations as tools that compatible assistants and clients can call. Endpoint pages identify the corresponding tool name and inputs where an MCP tool exists. MCP does not bypass Open API authentication, scopes, tenant boundaries, or endpoint restrictions.
Are all Open API endpoints available as MCP tools?
Supported GET operations and explicitly enabled write operations are registered as tools. An Endpoint Reference page includes an MCP Tool section when a corresponding tool exists. The API-key information endpoint is not exposed as an MCP tool.
Does MCP return every matching record automatically?
No. Paginated MCP tools use a default limit of 50, a maximum page size of 200, and a maximum of 10,000 reachable records across pages. Use filters or server-side summary tools for larger analysis rather than trying to retrieve an unlimited dataset.
Can I connect Requidex to Claude or another AI service?
Technically, an approved Open API or MCP integration can provide a third-party service with data that the configured key is allowed to access. Requidex secures and controls access at the API boundary. Once your organisation chooses to send data to another service, your organisation must confirm that the service, subscription, configuration, data-processing terms, subprocessors, retention, training controls, and transfer arrangements meet its legal, contractual, and information-security requirements.
Does Requidex guarantee that an AI provider keeps data in the UK or EEA?
No. Requidex cannot warrant the processing location or data-handling behavior of an independent third-party service. Availability of UK- or EEA-restricted processing may depend on the provider, product, account type, region, and configuration and may change over time. This applies to Claude and other AI services. Verify the provider's current contractual and technical commitments before enabling access.
For example, consult Anthropic's current commercial data-location guidance for the specific Claude product being considered. For UK data-transfer responsibilities, consult the ICO's guide to international transfers and your own advisers.
Can I use an AI service with worker documents or other personal data?
Only after your organisation has established an appropriate lawful, contractual, and security basis for doing so. Worker and right-to-work documents may contain sensitive personal data. If your contracts or policies require all processing to remain in the UK or EEA, do not send those documents to an AI service unless the selected service and configuration have been verified to meet that requirement.
Is automated AI access different from manually downloading and uploading a document?
Automation changes the transfer mechanism, not the underlying data-protection decision. A person could manually export an authorised document from Requidex and upload it to a third-party AI service; an API or MCP integration can automate a similar flow at greater speed and scale. In both cases, your organisation is responsible for approving the destination, purpose, data set, retention, and safeguards. Automation should therefore receive at least the same review as a manual process, with additional attention to scale and repeatability.
How can I reduce the data exposed to an AI integration?
Create a dedicated least-privilege key. Limit it to the required companies or agencies and read scopes, omit write scopes unless essential, request only required fields, use narrow filters, configure an IP allowlist and expiry, and revoke the key when it is no longer needed. Where residency is a strict requirement, consider a region-restricted service or architecture and verify its contractual coverage before use.
Is AI output authoritative?
No. AI-generated extraction, classification, or advice can be incomplete or incorrect. Do not use it as the sole basis for right-to-work, employment, payment, compliance, or other consequential decisions. Keep appropriate human review, source-document checks, auditability, and escalation controls.
This FAQ describes Requidex product behavior and recommended integration controls. It is not legal advice. Your organisation should obtain its own privacy, employment, and information-security advice where required.
Specifications, versions, and support
Where can I download the OpenAPI specification?
Download the current v1 JSON from OpenAPI Spec. That page also provides a Swagger 2.0 generator for tooling that does not accept OpenAPI 3.
How is the API versioned?
The current namespace is /api/open/v1. Breaking contract changes will use a new major API version. Compatible additions, such as new optional fields, may be introduced within v1. See Versioning.
How do I track API changes?
Review the ChangeLog before releasing or updating an integration. Build clients defensively so that additive fields do not cause failures.
What information should I provide when requesting support?
Provide the endpoint and HTTP method, approximate UTC time, response status and error code, non-sensitive request parameters, and the key name or prefix. Never send the full API key, webhook signing secret, personal documents, or an unredacted response unless an approved secure support process specifically requires it.