API documentation

Keys and environments

You create keys in the console. The key decides the environment, and the address stays the same.

fin_test_… is a sandbox key. It returns fixed test scenarios, never reaches a real source and costs nothing.
fin_live_… is a production key. It calls the real source and charges your wallet. It needs your organisation to be approved for production.

Making a call

Send a POST with a JSON body and your key as a bearer token.

curl -X POST https://api.finovel.in/v1/aadhaar-validation \
  -H "Authorization: Bearer fin_test_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: application-48213-check" \
  -d '{"id_number":"234567890124"}'

Every API answers in the same shape.

{
  "request_id": "req_...",
  "success": true,
  "status": "success",
  "environment": "sandbox",
  "message": "...",
  "data": { },
  "error": null,
  "charged_paise": 0
}

Status codes

HTTP	`status`	Meaning
200	success	The call worked. Read data.
400	rejected	The request could not be accepted, such as a badly formed Idempotency-Key.
401	rejected	The API key is missing or invalid.
402	rejected	Your wallet balance is too low. Recharge and retry.
403	rejected	Your organisation or this API is not enabled for this environment.
404	rejected	There is no API at this address.
409	rejected	This Idempotency-Key was used with a different body, or that request is still running.
422	rejected or failed	The fields are wrong (rejected), or the source gave a definite negative answer (failed).
429	none	Too many requests. Each key can send up to 600 a minute. Wait and retry.
502	error	The source could not complete the request. You are not charged. Retry.

Retrying safely

Send an Idempotency-Key header of 8 to 128 letters, digits or - _ . : that names the piece of work.

The same key and body return the stored response, with an Idempotent-Replayed: true header. Nothing runs or is charged again. Stored responses last 24 hours.
The same key with a different body returns 409.
After an error or a low balance, the key is released, so a retry runs again.

Async APIs

Some APIs, such as document reading, take longer. They answer 202 with data.job_id. Fetch the result from GET /v1/jobs/{id}, or have a webhook tell you when it is ready.

Getting documents signed

Send a PDF to be signed by one or more people with eSign.

Charges

The charged_paise field says what this call cost. Errors are never charged, and each API's reference says exactly when it charges. You can see every request and charge in the console.

Your own reference

Send X-Client-Reference with your own id, up to 120 characters, to find a request later in the console. Every response has an X-Request-Id header; quote it when you contact support.