Passport OCR API
New
Read an uploaded passport image and get the biographic page back as structured fields, including the machine-readable zone where the document carries one.
Overview
Passport OCR reads an uploaded passport image and returns the details printed on the biographic page as structured fields. That includes the machine-readable zone where the document carries one. It removes the step where a person opens a photograph of a booklet and retypes what it says. Onboarding, travel, forex and staffing teams collect passports as phone photographs, and every retyped number can introduce an error that shows up much later. Which fields are available in any response varies with image quality, the document layout and the underlying data source. A passport is sensitive personal data. Collect it with the holder's consent and a stated purpose, and use the reading only for that purpose. Reading the document is a capture step, and it does not confirm that the passport is genuine.
- Category
- Document OCR APIs
- Coverage
- Passport booklets presented in India; readable output depends on the image and the document layout
- Input
- A passport image or scan uploaded by the holder, or captured inside your own onboarding flow
- Output
- Structured identity and document fields read from the biographic page, including the machine-readable zone where present
- Typical users
- Banks and NBFCs, forex and remittance desks, travel and hospitality platforms, overseas staffing agencies, insurers
- Coverage note
- Available fields vary by image quality, document layout and data source. A reading captures the document; it does not verify identity.
The overview and the sections after the reference are the FinSour API catalog’s own record for this service, rendered unaltered.
Endpoint URL and method
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Authentication
Send your API key in this header on every call, from your own server: a key sent from a browser is refused. A key starting fs_test_ calls the sandbox and one starting fs_live_ calls production, at the same address. Create keys in the FinSour console.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Request parameters
Headers
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
Idempotency-Key | string | Required | A key you generate for each attempt. Sending the same key again returns the first answer instead of running the check twice; the same key with a different body is refused. | 8 to 255 characters. Matches ^[A-Za-z0-9._:-]+$ |
FinSour-Version | string | Required | Send 2026-11-01 on this call and on every poll to get the receipt and the result described on this page. A call without it is served under 2026-09-01, whose job has a different shape. | — |
Body
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
file | file | Required | The document to read. | — |
payload | string (JSON) | Required | A JSON string carrying the call's options. | — |
payload. | object | Required | Settings for this call. This API requires consent. | — |
payload. | string | Optional | Your own reference for this call. It comes back unchanged as meta.reference. | 1 to 128 characters |
payload. | object | Required | The person's consent to this check. | — |
payload. | boolean | Required | Send true once the person has agreed to the check. | Always true |
payload. | string (date-time) | Required | When the person gave consent. | — |
payload. | string | Required | What the check is for, for example kyc. | 1 to 64 characters |
Request samples
cURL
curl -X POST https://gateway.staging.finsour.io/v1/documents/passport \
-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":"<obtained>","at":"<at>","purpose":"<purpose>"}}}'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": "<obtained>",
"at": "<at>",
"purpose": "<purpose>"
}
}
}));
const response = await fetch("https://gateway.staging.finsour.io/v1/documents/passport", {
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/passport",
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": "<obtained>",
"at": "<at>",
"purpose": "<purpose>",
},
},
})},
timeout=30,
)
print(response.status_code, response.json())Generated from the fields above. Replace each value in angle brackets with your own; the key is read from FINSOUR_API_KEY.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Response schema
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
data | object | Always | The job that will read the document. | — |
data. | string | Always | The job's id. Poll GET /v1/jobs/{jobId} with it. | Matches ^[0-9A-HJKMNP-TV-Z]{26}$ |
data. | string | Always | Always queued: the job is accepted and has not started. | Always "queued" |
The result
Poll GET /v1/jobs/{jobId}. Once the job has finished, data holds these fields:
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
jobId | string | Always | — | — |
status | string | Always | — | One of queued, processing, completed, needs_review, unreadable, failed, expired, cancelled |
documentType | string or null | Always | The kind of document found, once it has been read; null before that. | — |
confidence | number or null | Always | The document's confidence, 0 to 1, to two places; null until it has been read. | Minimum 0. Maximum 1 |
fields | object | Always | What was read. Every key is always present: null means the document does not carry it, or it could not be read with enough confidence. | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | ISO date, YYYY-MM-DD; a year or month alone is YYYY or YYYY-MM. | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | ISO date, YYYY-MM-DD; a year or month alone is YYYY or YYYY-MM. | — |
fields. | string or null | Always | ISO date, YYYY-MM-DD; a year or month alone is YYYY or YYYY-MM. | — |
fields. | boolean or null | Always | — | — |
fieldsToReview | array of strings | Always | When status is needs_review, the fields a person should confirm; empty otherwise. | — |
failureReason | string | Sometimes | Present only when status is unreadable or failed. | One of UNREADABLE_IMAGE, LOW_CONFIDENCE, DOCUMENT_TYPE_MISMATCH, UNSUPPORTED_MEDIA_TYPE, FILE_TOO_LARGE, INPUT_CORRUPT, PAGE_LIMIT_EXCEEDED, TIMEOUT, PROCESSING_ERROR |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Error codes
| Code | Status | Meaning | Retrying |
|---|---|---|---|
API_VERSION_UNSUPPORTED | 400 | That API version is no longer supported. | Do not retry automatically |
IDEMPOTENCY_KEY_INVALID | 400 | That Idempotency-Key does not meet the required format. | Do not retry automatically |
IDEMPOTENCY_KEY_REQUIRED | 400 | An Idempotency-Key header is required for this request. | Do not retry automatically |
REQUEST_MALFORMED | 400 | The request could not be parsed. | Do not retry automatically |
AUTH_KEY_EXPIRED | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_INVALID | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_MISSING | 401 | No API key was presented. | Do not retry automatically |
AUTH_KEY_REVOKED | 401 | The API key is not valid. | Do not retry automatically |
INSUFFICIENT_BALANCE | 402 | The available balance is not enough for this request. | Do not retry automatically |
AUTH_IP_NOT_ALLOWED | 403 | This API key may not be used from this address. | Do not retry automatically |
ENTITLEMENT_MISSING | 403 | This organization is not entitled to that product in this environment. | Do not retry automatically |
ORGANIZATION_SUSPENDED | 403 | This organization is not active. | Do not retry automatically |
PRODUCT_NOT_AVAILABLE | 403 | That product is not available. | Do not retry automatically |
PRODUCT_RETIRED | 403 | That product has been withdrawn. | Do not retry automatically |
SCOPE_INSUFFICIENT | 403 | This API key does not carry the scope this product requires. | Do not retry automatically |
PRODUCT_NOT_FOUND | 404 | No such product. | Do not retry automatically |
IDEMPOTENCY_KEY_REUSED | 409 | That idempotency key was already used for a different request. | Do not retry automatically |
PRICE_UNAVAILABLE | 409 | No active price covers this product right now. | Safe to retry |
REQUEST_IN_PROGRESS | 409 | An earlier attempt with this key is still running. | Safe to retry |
SETTLEMENT_PENDING | 409 | This request is awaiting reconciliation by an operator. | Do not retry automatically |
API_VERSION_SUNSET | 410 | That API version passed its announced sunset date. | Do not retry automatically |
REQUEST_TOO_LARGE | 413 | The request body is too large. | Do not retry automatically |
OCR_UNSUPPORTED_MEDIA_TYPE | 415 | That document format is not accepted. | Do not retry automatically |
UNSUPPORTED_MEDIA_TYPE | 415 | That content type is not accepted on this route. | Do not retry automatically |
CONSENT_REQUIRED | 422 | This product requires an explicit consent flag. | Do not retry automatically |
SANDBOX_FIXTURE_MISSING | 422 | No sandbox fixture exists for this input. Use a different test value. | Do not retry automatically |
UPSTREAM_REJECTED | 422 | The upstream source rejected the input. | Do not retry automatically |
VALIDATION_FAILED | 422 | The request payload is invalid. | Do not retry automatically |
CONCURRENCY_LIMIT | 429 | Too many simultaneous requests. | Safe to retry |
OCR_QUEUE_SATURATED | 429 | The document queue is full. Retry shortly. | Safe to retry |
QUOTA_EXCEEDED | 429 | The allowance for this window is spent. | Do not retry automatically |
RATE_LIMITED | 429 | Too many requests. | Safe to retry |
INTERNAL_ERROR | 500 | An unexpected error occurred. | Safe to retry |
OUTCOME_UNCERTAIN | 502 | The outcome of this request is not yet known. Retry with the same Idempotency-Key. | Do not retry automatically |
UPSTREAM_UNAVAILABLE | 502 | The upstream source is unavailable. Retry shortly. | Safe to retry |
MAINTENANCE_MODE | 503 | The service is in a maintenance window. | Safe to retry |
NO_PROVIDER_AVAILABLE | 503 | No provider can serve this product right now. | Safe to retry |
OCR_UNAVAILABLE | 503 | Document reading is unavailable right now. Retry later. | Safe to retry |
SERVICE_OVERLOADED | 503 | The service is shedding load. Retry shortly. | Safe to retry |
UPSTREAM_TIMEOUT | 504 | The upstream source did not respond in time. | Safe to retry |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Rate limits
| Scope | Limit | Window | At the limit |
|---|---|---|---|
| Your API key, within your organisation's limit | The figure in X-RateLimit-Limit | Per minute | 429 RATE_LIMITED, with Retry-After in seconds. Every answer past authentication carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Use cases
- Banking: capture passport fields when a passport is the identity document offered at onboarding
- Forex and remittance: read traveler passport details during currency purchase and intake
- Travel platforms: capture passport details for international booking and check-in
- Hospitality: read foreign-guest passport details when a property must file a guest record
- Staffing and overseas recruitment: capture candidate passport details for deployment paperwork
- Insurance: read passport fields on travel and expatriate policy proposals
What this service does
Reads the MRZ where the booklet has one
The MRZ is printed in a fixed international layout with check digits, which makes it the steadiest part of the page to read. Where a booklet is older, worn or cropped out of frame, the reading falls back on the printed text above it. The fields available vary by document and data source.
Biographic page fields instead of retyping
Name, passport number, dates of birth, issue and expiry, nationality and other available attributes come back as data your form can fill. An operations team no longer reads a photograph and types what it sees.
Built for the images people actually send
Passports arrive as phone photographs taken at a desk, in a car or under a ceiling light. The workflow is built around retries and correction. It never assumes a clean flatbed scan.
A capture step you can audit
Keeping the submitted image alongside the structured reading gives a later reviewer both the source and the result. That is what a file needs when a decision made on it is questioned.
How a check runs
Ask the holder for the biographic page
The holder photographs or scans the full biographic page, with the machine-readable zone inside the frame, and uploads it through your application.
Send the passport image to the API
Your application submits the uploaded file in a single request, as part of the onboarding, booking or intake journey.
Read back what the service could recover
The response returns the identity and document fields that could be read. Available fields vary by image quality, document layout and data source.
Let the holder fix what the image hid
Show the values that were read and let the holder correct anything the image obscured, before you commit the record.
Carry the confirmed data forward
The confirmed fields fill your onboarding file, booking record or case, and you can keep the image alongside them for review.
Questions
- What is a Passport OCR API?
- An interface that accepts a passport image and returns the details printed on the biographic page as structured fields. Your application captures them directly. That removes the manual read-and-retype step.
- What is the machine-readable zone on a passport?
- The MRZ is the block of uppercase characters and chevrons printed along the foot of the biographic page in a fixed international layout. The positions are known and the zone carries check digits, which usually makes it the steadiest part of the page to read. Not every document has a usable one.
- Which passport fields can the response contain?
- Depending on the document and the image, the response may carry the name, passport number, date and place of birth and nationality. It can also carry sex, the dates of issue and expiry, the place of issue and the machine-readable zone. The exact fields available vary by data source, document layout and image quality.
- Does reading a passport confirm that it is genuine?
- No. OCR reads what the document shows. Confirming that a document is valid, or that the person presenting it is its holder, calls for separate verification and liveness checks. Those can sit alongside the reading in the same workflow.
- What happens when the passport photo is poor?
- Glare, a cropped page, a heavy angle or a worn booklet can leave parts of the page unreadable, and those fields simply do not come back. The practical answer is a confirmation screen and a clear retry prompt that tells the person what to fix.
- What consent do I need before collecting a passport image?
- A passport is personal data. Collect it only for a stated, lawful purpose, and tell the person what you are collecting and why. Take their consent before the image leaves their device, use the reading only for that purpose, and keep it no longer than your policy and applicable law require.
Catalog entry last updated .