Document APIs
Uploading a file, polling the job, and reading the extracted fields.
Upload the document
A document API reads a file. Send it as multipart/form-data: a file part, and an optional payload part holding the call’s options as a JSON string (required where the API needs consent). Sending the document as a JSON object reference is refused 422 VALIDATION_FAILED; send the file itself.
Send FinSour-Version: 2026-11-01 on the upload and on every poll. The job described here, and the fields each document API’s page lists, are that version’s. A call without the header is served under the default, 2026-09-01, whose job has a different shape.
cURL
curl -X POST https://gateway.staging.finsour.io/v1/documents/pan-card \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "FinSour-Version: 2026-11-01" \
-F "file=@<path-to-document>" \
-F 'payload={"options":{"consent":{"obtained":true,"at":"2026-09-01T10:00:00Z","purpose":"kyc"}}}'Node.js
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("file", await openAsBlob("<path-to-document>"));
form.append("payload", JSON.stringify({
"options": {
"consent": {
"obtained": true,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc"
}
}
}));
const response = await fetch("https://gateway.staging.finsour.io/v1/documents/pan-card", {
method: "POST",
headers: {
"X-Api-Key": process.env.FINSOUR_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"FinSour-Version": "2026-11-01",
},
body: form,
});
console.log(response.status, await response.json());Python
import os
import uuid
import json
import requests
response = requests.post(
"https://gateway.staging.finsour.io/v1/documents/pan-card",
headers={
"X-Api-Key": os.environ["FINSOUR_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
"FinSour-Version": "2026-11-01",
},
files={"file": open("<path-to-document>", "rb")},
data={"payload": json.dumps({
"options": {
"consent": {
"obtained": True,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc",
},
},
})},
timeout=30,
)
print(response.status_code, response.json())Replace each value in angle brackets with your own. The key is read from the FINSOUR_API_KEY environment variable.
The job
The call answers 202 with a job: data.jobId and data.status, which is queued. Reading a document is always asynchronous; there is no synchronous answer.
Poll for the result
Poll GET /v1/jobs/{jobId}, with the same FinSour-Version header, until the job leaves queued and processing. The poll itself is always 200; the job’s outcome is in the body, and the result is data itself. data.fields always carries every field the API declares, with null (or an empty list) for one that was not read, so it can be read without checking the status first.
| data.status | What to do |
|---|---|
queued | Keep polling. |
processing | Keep polling. |
completed | Every field was read with high confidence. data.fields holds them, as listed on the API's page. |
needs_review | data.fields holds what was read, and a person should confirm the fields named in data.fieldsToReview. This is charged. |
unreadable | The document could not be read. data.failureReason says why, and nothing is charged. |
failed | The job failed. data.failureReason says why, and nothing is charged. |
expired | The job ran out of time. Nothing was read; upload the document again. |
cancelled | The job was cancelled. Nothing was read; upload the document again. |
cURL
curl https://gateway.staging.finsour.io/v1/jobs/<jobId> \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "FinSour-Version: 2026-11-01"Results are read by polling. The gateway does not deliver a result to a webhook address sent with the request; such a field is refused.
Document errors
| Code | Status | Meaning | Retrying |
|---|---|---|---|
OCR_JOB_NOT_FOUND | 404 | No such job. | Do not retry automatically |
OCR_RESULT_EXPIRED | 410 | That result is no longer retained. | Do not retry automatically |
OCR_FILE_TOO_LARGE | 413 | The document is too large. | Do not retry automatically |
OCR_UNSUPPORTED_MEDIA_TYPE | 415 | That document format is not accepted. | Do not retry automatically |
OCR_DOCUMENT_TYPE_MISMATCH | 422 | The document is not the type this product reads. | Do not retry automatically |
OCR_INPUT_CORRUPT | 422 | The document could not be decoded. | Do not retry automatically |
OCR_LOW_CONFIDENCE | 422 | The document could not be read with enough confidence. Retry with a clearer image. | Safe to retry |
OCR_PAGE_LIMIT_EXCEEDED | 422 | The document has more pages than this product accepts. | Do not retry automatically |
OCR_UNREADABLE | 422 | No text could be found in the document. Retry with a clearer image. | Safe to retry |
OCR_QUEUE_SATURATED | 429 | The document queue is full. Retry shortly. | Safe to retry |
OCR_UNAVAILABLE | 503 | Document reading is unavailable right now. Retry later. | Safe to retry |
OCR_TIMEOUT | 504 | The document took too long to process. Retry shortly. | Safe to retry |
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.