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 15 credits (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",
  "reference_code": "3J7Q9WD2M4XT",
  "status": "PENDING",
  "country": "pk",
  "doc_type": "NATIONAL_ID",
  "end_user_ref": "user_8842",
  "cost_credits": 15,
  "mode": "LIVE",
  "risk_score": null,
  "hosted_url": "https://okias.io/verify/cms80k9ix001moea2jxy64fgu",
  "liveness_challenge": null,
  "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.

FULL_KYC includes both the document check and sanctions screening. When you request ID_DOCUMENT and AML_SCREENING as separate checks instead, each is priced as its own item, at the credits listed for it by GET /v1/pricing, and cost_credits is the sum of the checks you requested. In live mode that total is the size of the hold, and it is still charged only if the verification resolves APPROVED.

Holds by product#

The same hold-then-charge-on-approval rule applies to every KYC product:

Every KYC product — AI KYC, Manual KYC (decided by OKIAS or by you) and BYOK — is charged only when the final result is APPROVED. Declined, expired and errored verifications are never charged, and reviews or action-required requests cost nothing until they end approved. Credits are reserved (held) while a verification is open and released automatically if it does not end approved.

Pricing API#

The public price list (no authentication) is the source of every price on this site and of the cost_credits a verification is created with. A verification keeps the price it was created with. The response (api_version: 2) includes:

• products[] — each product on sale with key, credit_cost, usd, billing_trigger (ON_APPROVAL for every KYC product) and includes[].
• credit — the value of one credit in USD (fixed).
• trial — the free trial credits granted after e-mail verification, or null.
• topup — minimum and maximum top-up, volume bonus tiers and payment_methods[].
• when_charged[] — the charging rule per outcome (approved, declined, review, expired, error, sandbox).
• subscription and partner — white-label plans and partner payout terms.

The response carries an ETag; send it back in If-None-Match to receive 304 Not Modified when nothing changed. POST /v1/pricing/quote and GET /v1/pricing/convert are retired and answer 410 ENDPOINT_RETIRED: use GET /v1/pricing for list prices and POST /v1/me/billing/quote (signed-in console session) for the prices that apply to your own account.

Liveness on a verification#

Liveness reason codes appear in the verification's reason_codes; they are listed under Errors and reason codes.

• liveness_challenge is deprecated and is always null. No liveness instructions are published in a response before the capture.
• Pure-API submissions (assets inline in the create call, or POST /v1/verifications/:id/submit) have no interactive capture; their liveness frames are assessed like a passive capture, and 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, plus verification.expired when a session is not completed within the session lifetime (24 hours by default). 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",
  "reference_code": "3J7Q9WD2M4XT",
  "status": "APPROVED",
  "country": "pk",
  "doc_type": "NATIONAL_ID",
  "end_user_ref": "user_8842",
  "cost_credits": 15,
  "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": [] }
}

Reference code#

Every verification also carries a reference_code: twelve uppercase characters (digits and letters, never I, L, O or U, so nothing is ambiguous when it is read aloud or retyped). Print it on receipts, put it in confirmation e-mails, quote it in support. It is randomly generated server-side and contains no personal data, no timestamp and no account identifier, so it is safe to log and to show to your own users.

• Permanent and unique. A code is assigned once, never changes, and is never reused — even if the verification is deleted.
• Forgiving on input. Case, spaces and hyphens are ignored, and because I, L and O never appear in a code, typing one is read as 1, 1 and 0. So 3j7q-9wd2-m4xt and 3J7Q 9WD2 M4XT both resolve.
• An identifier, not a secret. This endpoint still requires your API key and only ever returns your own verifications. An unknown code, a malformed code and another merchant's code all return the same 404 NOT_FOUND.
• Verifications created before this field existed omit it. Keep storing the id as your join key.

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#