Facial & ID Scan

Identity verification that bundles ID document verification, face match, and passive liveness into a single hosted flow. The user completes capture on a Fill Easy-hosted page; you receive the decision via webhook or polling.

Flow

Call POST /ocr/auth with a redirect URL → receive a token and a hosted sessionUrl
Redirect the user to sessionUrl to complete ID capture, liveness, and face match
Receive the result via webhook or poll /ocr/poll

Result Delivery

Webhook (recommended) — Pass a callbackUrl in the /ocr/auth body. When verification completes, a POST is sent to that URL with the decision wrapped in a WebhookPayload envelope. Polling remains available as a fallback.

Polling — Call /ocr/poll with the returned token until a 200 response is returned.

Direct API (no redirect)

Prefer to run capture inside your own app? Call POST /ocr/verify with base64 images to get the same OcrResult decision synchronously — no hosted page, webhook, or polling. The checks that run are driven by what you send: frontImage for ID Verification, selfie for Passive Liveness, and both together add Face Match.

Start session

post

Creates an OCR verification session bundling ID Verification, Face Match, and Passive Liveness. Returns a hosted sessionUrl to redirect the user to, plus a JWT token used later with /ocr/poll to retrieve the decision.

Webhook Delivery: Provide callbackUrl to receive a POST when verification completes. The webhook body is a WebhookPayload envelope whose data is an OcrResult — the same shape returned by /ocr/poll on 200. The request also carries an X-Webhook-Event: ocr.verification.completed header plus any custom headers supplied via callbackHeaders. Polling remains available regardless of whether a callbackUrl is provided.

Authorizations

x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body

redirectstringRequired

Redirect URI after user authorization.

Browser: HTTPS URL to your website.

iOS: HTTPS Universal link

Android: Package name (com.filleasy.app)

Example: https://www.yourwebsite.com/callback

vendorDatastringOptional

Optional identifier of your own (e.g. user id) stored with the session and returned in the webhook payload.

callbackUrlstring · uriOptional

HTTPS URL to receive a webhook POST when verification completes. When provided, the webhook data is the same payload as a 200 response from /ocr/poll. Polling remains available as a fallback.

Pattern: ^https://.+

Responses

200

Session created

application/json

tokenstringRequired

JWT to pass to /ocr/poll

sessionUrlstring · uriRequired

Hosted OCR verification URL to redirect the user to

400

Bad Request - Invalid input parameters

application/json

500

Internal Server Error

application/json

503

Upstream verification provider unavailable - retry later

post/ocr/auth

POST /ocr/auth HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "redirect": "https://yourapp.com/kyc/done",
  "vendorData": "user-123"
}

{
  "token": "text",
  "sessionUrl": "https://example.com"
}

Poll result

post

Poll with the token returned from /ocr/auth to get the verification decision. Returns 202 while still pending, 200 once the upstream webhook has delivered the result. The status field doubles as the pending flag and the terminal verdict.

Authorizations

x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body

tokenstringRequired

JWT token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$

Responses

200

Verification complete - decision returned

application/json

Verification decision returned by /ocr/poll (200) and as the data field of the ocr.verification.completed webhook. status carries the terminal verdict. identity, faceMatch, and liveness are present only when the upstream check produced data — for example, a Declined outcome with no captured document may return only status.

statusstring · enumRequired

Terminal verdict from the verification provider.

Possible values:

202

Pending - user has not completed verification yet

application/json

400

Bad Request - Invalid input parameters

application/json

401

Unauthorized - Token is missing, invalid, or expired

application/json

410

Token is valid but the session result has expired (TTL) or is unknown

post/ocr/poll

POST /ocr/poll HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

{
  "status": "Approved",
  "identity": {
    "firstName": "Chan Tai",
    "lastName": "Man",
    "fullName": "Chan Tai Man",
    "dateOfBirth": "1990-01-15",
    "documentNumber": "A1234567",
    "documentType": "Identity Card",
    "issuingCountry": "HKG",
    "gender": "M",
    "dateOfIssue": "2018-06-01",
    "expirationDate": "2028-06-01"
  },
  "faceMatch": {
    "score": 97.5
  },
  "liveness": {
    "score": 100,
    "method": "PASSIVE"
  }
}

Verify (direct)

post

Synchronous, no-redirect alternative to /ocr/auth. Submit the images you have as base64 strings and receive the decision directly in the response — the same OcrResult shape /ocr/poll returns.

You choose which checks run by what you send (send at least one of frontImage or selfie):

Inputs sent

Checks run

frontImage (+ optional backImage)

ID Verification

selfie

Passive Liveness

frontImage + selfie

ID Verification + Face Match + Passive Liveness

No hosted page, webhook, or polling is involved: your application captures the images and this call returns the verdict in one round-trip. status is Approved only when every check that ran passed; identity, faceMatch, and liveness are present only for the checks that ran.

Images are base64-encoded — a raw base64 string or a data: URL. Keep the combined request body under ~6 MB; compress phone captures before sending.

Authorizations

x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body

Send at least one of frontImage or selfie.

frontImagestringOptional

Base64-encoded image of the ID document front. Triggers ID Verification.

backImagestringOptional

Base64-encoded image of the ID document back, when the document has one.

selfiestringOptional

Base64-encoded selfie. Triggers Passive Liveness, and Face Match when frontImage is also sent.

Responses

200

Verification complete - decision returned

application/json

statusstring · enumRequired

Terminal verdict from the verification provider.

Possible values:

400

Bad Request - Invalid input parameters

application/json

500

Internal Server Error

application/json

503

Upstream verification provider unavailable - retry later

post/ocr/verify

POST /ocr/verify HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 164

{
  "frontImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "backImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "selfie": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}

{
  "status": "Approved",
  "identity": {
    "firstName": "Chan Tai",
    "lastName": "Man",
    "fullName": "Chan Tai Man",
    "dateOfBirth": "1990-01-15",
    "documentNumber": "A1234567",
    "documentType": "Identity Card",
    "issuingCountry": "HKG",
    "gender": "M",
    "dateOfIssue": "2018-06-01",
    "expirationDate": "2028-06-01"
  },
  "faceMatch": {
    "score": 97.5
  },
  "liveness": {
    "score": 100,
    "method": "PASSIVE"
  }
}

Last updated 10 hours ago