Making a request
The request body, idempotency keys, consent and the response envelope.
The request
Every API is POST /v1/{group}/{name} with a JSON body of two parts: input, the details to check, and options, settings for the call. Each API’s page lists its own input fields. Document APIs take a file instead; see Document APIs.
| Header | Required | What it is |
|---|---|---|
X-Api-Key | Required | Your API key. |
Idempotency-Key | Required | A key you generate for each attempt; see below. |
Content-Type | Required | application/json |
Idempotency keys
Every call needs an Idempotency-Key: 8 to 255 characters matching ^[A-Za-z0-9._:-]+$. A fresh UUID per attempt is the simplest way to meet it.
- The same key with the same request returns the first answer again, with
meta.idempotentReplay: true, and the check is not run twice. - The same key with a different body, or for a different API, is refused
409 IDEMPOTENCY_KEY_REUSED. Send a new key. - While the first attempt is still running, the same key answers
409 REQUEST_IN_PROGRESS. 502 OUTCOME_UNCERTAINmeans the outcome is not known yet: retry with the same key, not a new one.
A key belongs to your organisation, the environment and the API version.
Consent
APIs that check a personal identifier require the person’s consent, sent as options.consent with obtained, at and purpose. Each API’s page says whether it requires consent. A call without it where it is required is refused 422 CONSENT_REQUIRED. You can also send options.reference, your own reference for the call, which comes back as meta.reference.
The response
A definitive answer is 200, including when the source holds no record: that is data.found: false, with every other field null and every list empty.
| Field | Type | What it is |
|---|---|---|
success | boolean | Always true on a 200. |
data | object | The API's own fields, listed on its page. |
requestId | string | This call's id, also sent in the X-Request-Id header. |
latencyMs | number | How long the call took, in milliseconds. |
meta.productSlug | string | The API that answered, as its path: vehicle/rc. |
meta.environment | string | sandbox or production. |
meta.apiVersion | string | The API version that served the call. |
meta.idempotentReplay | boolean | Whether this is a replay of an earlier answer. |
meta.billing | object | What the call was charged, when it is included. Amounts are decimal strings in paise. |
meta.reference | string | Your options.reference, when you sent one. |
GET /v1/requests/{requestId} returns the answer an earlier call produced, at the status it was first answered with.
Written from FinSour platform API contract (finsour development at 80e8b83bf), last changed . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.