Skip to content

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.

HeaderRequiredWhat it is
X-Api-KeyRequiredYour API key.
Idempotency-KeyRequiredA key you generate for each attempt; see below.
Content-TypeRequiredapplication/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_UNCERTAIN means 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.

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.

FieldTypeWhat it is
successbooleanAlways true on a 200.
dataobjectThe API's own fields, listed on its page.
requestIdstringThis call's id, also sent in the X-Request-Id header.
latencyMsnumberHow long the call took, in milliseconds.
meta.productSlugstringThe API that answered, as its path: vehicle/rc.
meta.environmentstringsandbox or production.
meta.apiVersionstringThe API version that served the call.
meta.idempotentReplaybooleanWhether this is a replay of an earlier answer.
meta.billingobjectWhat the call was charged, when it is included. Amounts are decimal strings in paise.
meta.referencestringYour 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.