OCR

Overview

OCR lets you verify a person's identity with a mobile, browser-based flow. Users capture their government ID and a selfie, and our service performs OCR, document authenticity checks, and face matching/liveness.

What it does

  • Document capture & OCR — reads key fields (name, ID number, DOB, sex, issue/expiry dates, etc.).

  • Security checks — evaluates document security features where applicable.

  • Face verification — selfie liveness + match against the ID portrait (when available).

  • Decisioning — returns a clear outcome: Success, Failure, or Void\\\\* (canceled/aborted).

Request

post

Initialize a verification session by passing your callback URLs and the document type.

Browser Flow:

Returns a launch URL (open on a mobile browser) and a JWT token that you must keep for polling status. After the user completes or cancels the H5 flow, the browser is redirected to your provided callback URL.

Mobile App Flow:

Use the returned url to open an in-app web view or the system browser on the phone. Use the returned token later with /ocr/poll to check the final decision.

Note: The redirect is UX-only; you still need to call /ocr/poll with the returned token to obtain the authoritative decision.

Authorizations
x-client-idstringRequired

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

Body
completeCallbackUrlstring · uriRequired

Where to redirect the user after success. Must be publicly reachable over https.

Example: https://example.com/ocr/completePattern: ^https://
interruptCallbackUrlstring · uriRequired

Where to redirect the user if they cancel/exit. Must be publicly reachable over https.

Example: https://example.com/ocr/interruptPattern: ^https://
docTypestring · enumRequired

The identity document type to verify. 00000001003 (Passport), 08520000002 (HKID New), 08520000001 (HKID Old). Use the exact code for your target document.

Example: 08520000002Possible values:
Responses
post
/ocr/request
POST /ocr/request 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: 141

{
  "completeCallbackUrl": "https://example.com/ocr/complete",
  "interruptCallbackUrl": "https://example.com/ocr/interrupt",
  "docType": "08520000002"
}
200

Successfully initialized verification session

{
  "token": "eyJhbGciOiJIUzI1NisInR5cCI6IkpXVCJ9.eyJiaXpJZCI6Im9jci0xNzU0OTgzNTAwNjI3LUVjWE1xMyIsInRyYW5zYWN0aW9uSWQiOiJHMDAwMDAwMDA0RlJMMjAyNTA4MTIwMDAwMDAxMTg2MTAwNTc5NDIiLCJkb2NUeXBlIjoiMDg1MjAwMDAwMDIiLCJjcmVhdGVUaW1lIjoxNzU0OTgzNTAwODY0LCJqdGkiOiJZMjhCS2tRSXZwODRYSGFrIiwiaWF0IjxNzU0OTgzNTAwfQ.9ox1rEeT9NtxhWYLk8i0NgsDNhW30cfQShx1ui9ssyM",
  "url": "https://sg-production-cdn.zoloz.com/page/zoloz-realid-fe/index.html?clientcfg=eyJzaWduIjoiTHIzMzhpcmZTR1Z2dXVHOEd5MUd0Q0xzdTNXK3h5RVBxcnlmRGNYaVB1VnFEUVlRMTh1ckVLNmhDTVVIaTNMdHlWdHE5aEFCeGFpVnMvYm9iVmtxOENSUUwva2lvdEVFTjFZTHQ5YkExUUc0NlZQQlI4cWdBb0QzenBPVkhRZHN4Sm1RMko3QjFKS1hkNHQrK2dmTUxtS2xhSkRHTHhUQkc4dXFxMDVuOGZyMmVYWUo4S0dKS2x4SGtFU1JoUGN0ZUNsTFJDYUhSWUUyZFlVdUVrekdaRUdGYXUzTDFBUUdTZkM5VldMYkhRemViajZyMk54OWdGN2JIb3ErUlE2NFVDNzFrZGF1dXZTeEQ2b1VTQTBxaGhCYm9TQ0lHL2NZZWtIb2w1NEJHWlhwS3pOeG9YOEhDYmlyRURya0pGZ0ZzQkpMeEgxNkljZFdqSDBvNXhtMEt3PT0iLCJjb250ZW50Ijoie1wiR0FURVdBWV9VUkxcIjpcImh0dHBzOi8vc2ctc2FuZGJveC1hcGkuem9sb3ouY29tL3ptZ3MvdjIvc2VjXCIsXCJBUFBfSURcIjpcIlwiLFwia2V5TWV0YVwiOlwie1xcXCJyZXNvdXJjZUNvZGVcXFwiOlxcXCIwMDAwMDAwMFxcXCIsXFxcIm1pZFxcXCI6XFxcIjI1OTdcXFwiLFxcXCJrZXlWZXJcXFwiOlxcXCJ2MVxcXCJ9XCIsXCJ2ZXJzaW9uVG9rZW5cIjpcIjIwMjUwODEyMDcyNDU2MTE0MTc4NzM4NFwiLFwiaDVEZWdyYWRhYmxlXCI6XCJOXCIsXCJpbnRlcnJ1cHRDYWxsYmFja1VybFwiOlwiaHR0cHM6Ly95b3VyYXBwLmNvbS9vY3IvaW50ZXJydXB0XCIsXCJmYWNlR3VpZGVVcmxcIjpcImh0dHBzOi8vc2ctcHJvZHVjdGlvbi1jZG4uem9sb3ouY29tL3BhZ2UvZmFjZS1ndWlkZS1mZS9pbmRleC5odG1sXCIsXCJXT1JLU1BBQ0VfSURcIjpcIlwiLFwidXNlVG95Z2VyVHlwZVwiOlwibmNublwiLFwiZW5hYmxlVXBsb2FkXCI6XCJOXCIsXCJzdGF0ZVwiOlwiRzAwMDAwMDAwNEZSTDIwMjUwODEyMDAwMDAwMTE4NjEwMDU3OTQyXCIsXCJjb21wbGV0ZUNhbGxiYWNrVXJsXCI6XCJodHRwczovL3lvdXJhcHAuY29tL29jci9jb21wbGV0ZVwiLFwiYXV0aFR5cGVcIjpcIlJFQUxJRFwiLFwiZmxvd0lkXCI6XCJGMjAyNTA4MTIwMDAwMDAxMTg2MTAwNzA2MDhcIixcIkMyU19QVUJfS0VZXCI6XCJNSUlCSWpBTkJna3Foa2lHOXcwQkFRRUZBQU9DQVE4QU1JSUJDZ0tDQVFFQWxRZXJKQWVNSTMwSjBKUnRVVnhqYjgwY2RCNndJRWRWU0hrNXB1THRtV3lqeHFCMTVXTnBVaktRakU1V3kzQ3FvSlBNMVN0a1Ayc2gvd0h6OWJwbUh2dHMyclBwYkVXYjNaOTVSVU9yK01IWEFBWVo2OURvYXE1VktjdFdoNWo3eEd4dXVZcFUrR2E0d3ZTZHVCNVd6YlNUSXgvM2ZVczdRRjNUVWxoTGwvODBzamRERXQzazh3a0g2L0dsOFJoVXdQcS82M0prMVBCVlpKWHRmb2pMdlkwdmtlNnN6T0crdmtoMTJsSmlQY2d0eTk4Z01wUzYyb2NGR2JYVE9pa0NNTU1QWk9Xc3BVNUxpaWNXbzdmbDUxOEkxSk1pUGpxd0lESTN2dEh6QXhicjdHU2NKK0JDdE1HZjNIZkdmN2tndmFHc2VLN3JERCtmT3AzZm5HN0xjd0J9"
}

Poll

post

Check the status of a verification using the token returned by /ocr/request.

  • Returns 202 Accepted while the verification is in progress.

  • Returns 200 OK when the verification is completed (Success / Failure / Void*).

  • Always responds with a concise summary (no raw payloads needed).

Send only the token. It already encapsulates the session identifiers.

Terminal states: Success, Failure, or Void\*.

Authorizations
x-client-idstringRequired

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

Body
tokenstringRequired

The token returned by POST /ocr/request that encodes the session identifiers

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
Responses
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: 343

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJiaXpJZCI6Im9jci0xNzU0OTg0ODQwOTc3LThzVG5OciIsInRyYW5zYWN0aW9uSWQiOiJHMDAwMDAwMDA0RlJMMjAyNTA4MTIwMDAwMDAxMTg2MTEzNTA0MzgiLCJkb2NUeXBlIjoiMDg1MjAwMDAwMDIiLCJjcmVhdGVUaW1lIjoxNzU0OTg0ODQxMjYzLCJqdGkiOiJkVndVOEM1N2F4UmNvU2VBIiwiaWF0IjoxNzU0OTg0ODQxfQ.y8_cFDqO69YpRMQnbKGmgk3sPujrZaqumv5NFmGTkPo"
}
{
  "message": "Verification completed",
  "summary": {
    "ekycResult": "Success",
    "isTerminal": true,
    "document": {
      "type": "08520000002",
      "number": "F*********",
      "holderName": "John, Smith",
      "dob": "2000/01/01",
      "sex": "M",
      "dateOfIssue": "2021/11/11",
      "dateOfExpiry": "2031/11/11",
      "decision": "Success"
    },
    "face": {
      "liveness": "Success",
      "livenessScore": 25,
      "matchScore": 94
    },
    "risk": {
      "decision": "Success"
    }
  }
}
PreviousSino ConnectNextCompany Registry Report

Last updated