Verifications

The lifecycle is simple: create → submit assets (or use the hosted flow) → OKIAS scores the signals → you read a final status.

Create a verification#

Creating a verification places a hold on one credit (in live mode) and returns a hosted_url you can redirect the user to. Always send an Idempotency-Key header.

curl https://api.okias.io/v1/verifications \
  -H "Authorization: Bearer $OKIAS_API_KEY" \
  -H "Idempotency-Key: 9f2c4a1b-1e33-4c07-9c1e-2b7f0d5a1a10" \
  -H "Content-Type: application/json" \
  -d '{
    "level": ["FULL_KYC"],
    "country": "pk",
    "doc_type": "NATIONAL_ID",
    "end_user_ref": "user_8842",
    "applicant": {
      "expected_first_name": "Ayesha",
      "expected_last_name": "Khan",
      "expected_dob": "1994-03-22"
    }
  }'

Request body#

The response is 201 Created with the verification as a flat JSON object — there is no data envelope. status starts at PENDING:

{
  "id": "cms80k9ix001moea2jxy64fgu",
  "status": "PENDING",
  "country": "pk",
  "doc_type": "NATIONAL_ID",
  "end_user_ref": "user_8842",
  "cost_credits": 1,
  "mode": "LIVE",
  "risk_score": null,
  "hosted_url": "https://okias.io/verify/cms80k9ix001moea2jxy64fgu",
  "liveness_challenge": { "actions": ["LOOK_DOWN", "TURN_RIGHT", "LOOK_UP", "TURN_LEFT"] },
  "reason_codes": [],
  "created_at": "2026-07-30T10:00:00.054Z",
  "completed_at": null
}

Levels & checks#

level is an array of check identifiers. The purchasable catalog is exactly three checks — anything else returns 400 VALIDATION_ERROR with UNKNOWN_CHECK:<value>. Your API key's scope determines which of them it may request; see key scopes.

Requesting several checks in one call sums their credits — ["ID_DOCUMENT", "AML_SCREENING"] returns cost_credits: 2. In live mode that total is the size of the hold, and it is still charged only if the verification resolves APPROVED.

The liveness challenge#

When you create a verification without inline assets (the hosted / deferred-capture flow), the response includes a liveness_challenge object:

"liveness_challenge": { "actions": ["LOOK_DOWN", "TURN_RIGHT", "LOOK_UP", "TURN_LEFT"] }

• Server-generated and random. Each challenge is a random ordering of the four head-turn actions (TURN_LEFT, TURN_RIGHT, LOOK_UP, LOOK_DOWN), generated server-side per verification. The random order is the anti-replay signal — a pre-recorded video cannot match it.
• The actions must be captured in order. The client performs the actions live, in exactly the sequence given, while liveness frames are captured. The hosted flow does all of this for you.
• Single-use, time-limited. The challenge is consumed when the pipeline scores the capture (it cannot be replayed) and expires 30 minutes after issuance. liveness_challenge reads as null once consumed or expired.
• Pure-API creates skip it. If you include assets inline in the create call there is no interactive capture, so no challenge is issued and liveness is evaluated passively only (which caps how strong the liveness signal can be — borderline cases lean to REVIEW).

Submit assets#

If you run your own capture UI, submit the document and selfie as base64 (no data: prefix). Each asset has a kind, an optional mime_type and the data.

curl https://api.okias.io/v1/verifications/cms80k9ix001moea2jxy64fgu/submit \
  -H "Authorization: Bearer $OKIAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      { "kind": "DOCUMENT_FRONT", "mime_type": "image/jpeg", "data": "<base64>" },
      { "kind": "DOCUMENT_BACK",  "mime_type": "image/jpeg", "data": "<base64>" },
      { "kind": "SELFIE",         "mime_type": "image/jpeg", "data": "<base64>" }
    ]
  }'

Asset kinds#

Statuses#

A verification's status moves from pending to one of four terminal outcomes:

In lowercase, webhook events map to these outcomes: verification.approved, verification.review, verification.declined and verification.error. See Webhooks.

Risk score & reason codes#

Every resolved verification carries a risk_score and a reason_codes array explaining the decision.

• risk_score is 0–100, and higher is worse. 0 means no risk detected; 100 is maximum risk. It is the weighted risk across the stages that ran, rounded to an integer.
• UI band guidance: treat < 20 as low risk, 20–59 as elevated, and ≥ 60 as high risk.
• APPROVED results carry a low score and an empty reason_codes array — approved verifications never carry reason codes. A declined one carries the specific signals that failed alongside a high score.

{
  "id": "cms81hq0p0031oea2vv17b1om",
  "status": "DECLINED",
  "risk_score": 71,
  "reason_codes": ["FACE_MISMATCH"],
  "completed_at": "2026-07-30T10:04:11.900Z"
}

Common reason codes#

Retrieve a verification#

Fetch the current state and decision at any time. On top of the fields returned by create, GET includes four owner-only detail fields. All four are null until processing completes (and stay null where no data was captured):

{
  "id": "cms80k9ix001moea2jxy64fgu",
  "status": "APPROVED",
  "country": "pk",
  "doc_type": "NATIONAL_ID",
  "end_user_ref": "user_8842",
  "cost_credits": 1,
  "mode": "LIVE",
  "risk_score": 8,
  "hosted_url": "https://okias.io/verify/cms80k9ix001moea2jxy64fgu",
  "liveness_challenge": null,
  "reason_codes": [],
  "created_at": "2026-07-30T10:00:00.054Z",
  "completed_at": "2026-07-30T10:03:41.120Z",
  "extracted": { "fullName": "OKIAS SAMPLE USER", "documentNumber": "AB1234567", "dateOfBirth": "1990-01-01", "dateOfExpiry": "2030-01-01" },
  "images": { "front": "data:image/jpeg;base64,...", "back": null, "selfie": "data:image/jpeg;base64,..." },
  "declared": { "firstName": "Okias", "lastName": "Sample User", "dateOfBirth": "1990-01-01" },
  "match": { "status": "MATCH", "fields": { "name": "MATCH", "dateOfBirth": "MATCH", "dateOfExpiry": "SKIP", "sex": "SKIP" }, "reasons": [] }
}

Idempotency#

Send a unique Idempotency-Key header on every create (supported on POST /v1/verifications and the partner variant POST /v1/p/:code/verifications). If a network hiccup makes you retry, OKIAS returns the original verification instead of creating a second one — so retries never double-charge or duplicate.

• The header is optional — but omitting it makes every call chargeable. Without an Idempotency-Key, each request creates a brand-new verification (and, in live mode, a new credit hold).
• 24-hour replay window. Repeating the same key within 24 hours returns the same verification object — never a second charge.
• Concurrent duplicates can return 409. If two requests race on the same key and the first has not finished, the duplicate may fail with 409 IDEMPOTENCY_IN_PROGRESS — retry it and you will get the original verification.
• Use a UUID or any unique string per logical operation (e.g. per user signup attempt).
• Reuse the same key when retrying the same request; use a new key for a genuinely new verification.

Next steps#