Platform API · API Docs · eKYC Platform
Onboard
Bundles initialization, ID verification and selfie verification into one synchronous request, and returns the full application result once every configured check has finished.
Request
Unlike Verify ID and Verify selfie, this endpoint does not require a prior Initialize or a Bearer access_token — it authenticates with the encrypted_token in the body (the same token as Initialize). The response still returns an access_token you can use to re-pull Application detail later.
The call imports a complete dossier, runs the configured ID and selfie checks in sequence (waiting for each), drives the application to a terminal state so the configured Post-check / AML / Government checks run, and returns the full TS-native result — the same shape as Application detail — in the response.
Use this when you already hold a user's ID/selfie assets (e.g. captured on another channel or by another vendor) and want to re-check them through the TrustVision pipeline in one call, without driving Initialize / Verify ID / Verify selfie separately.
| Name | Type | Required | Description |
|---|---|---|---|
encrypted_token | string | Required | The ENCODED_VALUE from the Authentication mechanism (same as Initialize). Identifies the user; the user reference inside it is the idempotency key. |
flow_id | string | Optional | Specific flow to use. |
card_types | string | Optional | Comma-separated allowed card types (e.g. vn.national_id,vn.passport). |
lang | string | Optional | Language code (e.g. vi, en). |
card_type | string | Required for ID | Card type to verify (e.g. vn.national_id). Must be within card_types when that is provided. |
image1 | object | Required for ID | ID front: { "base64": "<base64>", "metadata": "<string>", "qr_code": [{"result": "...", "from_image_type": "..."}] }. |
image2 | object | Optional | ID back: same structure as image1. |
qrs | array | Optional | Standalone QR images: [{ "base64": "<base64>", "metadata": "<string>" }]. |
selfies | array | Required for selfie | Frontal selfie image(s): [{ "base64" \| "id", "metadata" }]. The last element is the primary selfie used for face compare. An element with id references a pre-uploaded image. |
selfie_type | string | Optional | Selfie / liveness type (e.g. passive, passive_v2, flash). |
videos | array | Optional | Liveness video frames: [{ "id"?, "metadata"?, "frames": [{ "base64", "label", "index", "metadata"? }] }] (≤ 10). Required for passive/flash liveness to pass — a still-only selfie gives the engine nothing to score. |
client_metadata | object | Optional | Optional prepared metadata (e.g. applicant identity PII: applicant_name, id_number, dob, gender, phone_number, email), already encrypted by you. JSON ≤ 8 KB. Stored raw and echoed back raw only — never decrypted, and never fed into any check or the verdict. |
At least one of image1 (ID) or selfies (selfie) must be present — supply only one group for an ID-only or selfie-only re-check. Put liveness frames in videos, not in selfies.
Response
The endpoint blocks until all checks complete, then returns the full result — the same TS-native shape as Application detail (overall verdict plus each module's status). Conditional blocks (ekyc_ocr / ekyc_face / id_tampering / file_ids / form_data / client_metadata) appear only when the corresponding data exists.
| Field | Description |
|---|---|
data.verdict | Overall application verdict: approve, review, reject, or pending. |
ekyc_ocr / ekyc_face / id_tampering | Per-module results + status (same as Application detail). Present only when run. |
client_metadata | The prepared metadata you supplied, echoed back raw (omitted if none). |
access_token | JWT to re-pull Application detail for this application later. |
An approved application, with OCR, face and ID-tampering modules all run:
{
"data": {
"verdict": "approve",
"application_id": 10,
"application_unique_token": "ad083945-...",
"application_user_id": "0123456789",
"ekyc_ocr": {
"card_info": {},
"process_status": "success",
"sanity_check_status": "success"
},
"ekyc_face": {
"compare_status": "matched",
"compare_score": 0.98,
"liveness_status": "live",
"search_face_status": "not_found"
},
"id_tampering": { "score": 0.01, "verdict": "genuine" },
"client_metadata": {
"applicant_name": "Jane Doe",
"gender": "female"
},
"access_token": "<JWT>"
},
"message": "onboard completed",
"time": "2026-01-01T00:00:00Z",
"verdict": "success"
}
See Application detail for the full field reference (the verdict, file_ids, and form_data mappings).
When enabled for the lender (client_custom_settings.onboard_dedupe_only), the endpoint runs only face index/search, leaves data.verdict as pending, and returns the match result on data.ekyc_face.search_face_result / search_face_status (the Post-check / AML / verdict pipeline is skipped).
Failure codes
The top-level verdict names the outcome, alongside the HTTP status code:
verdict | Status code | Description |
|---|---|---|
success | 200 | Processing completed — read data.verdict for the outcome. |
missing_parameters | 400 | encrypted_token is missing. |
invalid_parameters | 400 | Token undecodable, no ID/selfie assets, bad card_type, or invalid base64. |
record_not_found | 404 | Encryption key or lender not found / inactive. |
limit_exceeded | 429 | Another submission for the same user is in progress, or rate limit reached. |
failure | 500 | Internal server error. |