Verify an identity document

Extract ID documents and act on what comes back.

Goal. Extract the fields from a passport, driver's licence or other identity document, and use the result — together with its integrity signals — to support a KYC check.

Before you start

• An API key, exported as $DOCAI_API_KEY.

• An identity document image or PDF.

Identity documents are personal data of the most sensitive kind. Everything here happens inside your regulated pipeline: log field values only where your retention policy allows, never write them to application logs by default, and delete source images on the schedule your policy sets. Nothing in this recipe should be pasted into a shared notebook or a support ticket.

Step 1 — Find the right document type

Identity documents form their own category in the registry:

curl -s "https://api-docai-uat.uptiq.ai/listSupportedDocuments" \
  | jq -r '.documents[] | select(.category == "Identity Document") | "\(.type)\t\(.name)"'

AadhaarCard     Aadhaar Card
Passport        Passport
…

See Document Types for the full categorised list.

Step 2 — Check the accepted formats first

ID documents are usually photographed rather than scanned, and the accepted formats differ from financial documents — spreadsheets are accepted for a bank statement and meaningless here.

curl -s "https://api-docai-uat.uptiq.ai/document/supported-file-types" \
  -H "X-Api-Key: $DOCAI_API_KEY" | jq '.data.AadhaarCard'

["pdf", "jpg", "jpeg", "png"]

Validating the extension before you submit saves a wasted call and a wasted credit.

Step 3 — Extract

If you know which document you were given, name it:

{ "documentType": "Passport", "content": "…" }

If the customer simply uploaded "ID", classify first — a passport and a driver's licence carry different fields, and extracting one as the other returns very little:

curl -X POST "https://api-docai-uat.uptiq.ai/classify/sync" \
  -H "X-Api-Key: $DOCAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @classify.json

Classification runs in around 13 seconds, so this is affordable in an interactive flow in a way that extraction is not. See Classify, then extract.

subtype is worth reading on the result. The webhook contract shows "type": "Driver's License" with "subType": "CA" — the issuing jurisdiction, which usually determines which validation rules apply.

Step 4 — Judge the capture quality

Photographed IDs fail differently from scanned documents — glare, angle, a thumb over the corner. documentQuality tells you whether a thin result is the image's fault:

jq '.extraction.result.documentQuality' record.json

{ "level": "high", "sharpness": 833.29, "stage": "extraction", "reasons": [] }

Low level, or a populated reasons array, means ask for a better photograph rather than retrying the same one or escalating to a human. That single decision removes most of the avoidable review load in an onboarding flow.

Step 5 — Check the integrity signals

For identity documents this is not optional — a forged ID is the threat the whole check exists for.

jq '.extraction.fraudResults.preflight.results[]
    | select(.status == "FAIL")
    | {ruleId, category, explanation: .details.explanation}' record.json

visual_forensic is the category that matters most here: it looks for tampering evidence such as inconsistent fonts, edited regions and missing print artifacts.

Two traps, both covered in Reading fraud and control checks:

Fraud analysis finishes after extraction does. An extraction at Processed may still have fraudStatus: "processing". For KYC, fail closed — hold the case rather than clearing it on an incomplete signal.

Gate on failed, not on score. A category score can be low simply because rules were skipped for lack of evaluable evidence. "Could not assess" is a review decision, not a pass and not a rejection.

Step 6 — Decide

Signals	Decision
Fields complete, quality high, no failed rules, fraud analysis terminal	Pass to your matching step
Quality low	Request a better image — do not escalate to a human yet
Fields missing but quality high	Human review; possibly the wrong document type
Any visual_forensic failure	Hold for the fraud team. Do not auto-reject on a machine signal alone
Fraud analysis not terminal	Wait, then decide. Never clear on a partial result

Extraction supports the check; it does not make the decision. Whether the extracted name matches your applicant, whether the document has expired, and whether the jurisdiction is acceptable are all your system's calls.

What is not here

The API extracts and reports integrity signals. It does not do biometric matching, liveness detection, or sanctions and PEP screening — those come from your KYC provider. Nor can fraud rules be configured through the API; that is Fraud Detection in the portal.

Related pages

• Reading fraud and control checks — the integrity signals in detail.

• Classify, then extract — when you do not know which ID you were given.

• Document Types — the Identity Document category.

• Fraud Detection — configuring the rules behind the checks.