Service API · eKYC Platform
Common objects & errors
Every Service API endpoint except Log in is authenticated the same way and fails the same way at the transport layer — all of it defined once, here, and referred to by name from each endpoint page.
Authorization
| Header key | Header Value | Description |
|---|---|---|
Authorization | Bearer <JWT> | Include the JWT access token to support request authentication |
Request objects
metadata
The metadata object taken by Index faces and eKYC full checks.
| Name | Type | Required | Description |
|---|---|---|---|
client_uid | string | Required | ID of a user or application or any unique token |
national_id | string | Optional | ID number of the user's ID card |
unique_token | string | Optional | The application_unique_token token from Application detail |
The application result
Application detail and Full verification both return the TS-native application result. These are the mappings for its verdict, file_ids and form_data fields.
verdict
| verdict | Description |
|---|---|
| pending | The user has not completed the flow |
| approve | Our recommendation to approve this application |
| review | Our recommendation to review this application |
| reject | Our recommendation to reject this application |
| abandoned | The user abandoned the flow |
The verdict stays pending until the application reaches a final state. From there it defaults to approve when the application succeeded and reject when it failed, and the post-check, AML and government-check rules enabled for your account can change it — for example from approve down to review, or to reject. An application still pending after its expiry time is reported as abandoned. If your code validates verdict against a list of allowed values, include abandoned.
These five values are the recommendation inside a successful application result. On an error response, the top-level verdict carries an error code instead. Codes shared by every endpoint, such as expired_token and invalid_parameters, are listed under Shared transport errors. A code specific to one endpoint, such as record_not_found, is listed under Failure codes on that endpoint's page, for example Application detail. The status fields inside each check object (process_status, compare_status, …) are listed under Check status fields.
file_ids
| key | Description | Present in |
|---|---|---|
| id_front_img_uuid | The image id of front side | ID Only, Full Flow |
| id_back_img_uuid | The image id of back side | ID Only, Full Flow |
| qr1_img_uuid | The image id of QR code | ID Only, Full Flow |
| selfie_image_uuid | The image id of selfie that use to compare faces | Selfie Only, Full Flow |
| gesture_images | List images during user do liveness | Selfie Only, Full Flow |
| sequence_frames | List frames video during user do liveness | Selfie Only, Full Flow |
| liveness_transformed_video_id | The video id merge from sequence frames | Selfie Only, Full Flow |
form_data
{
"contactInfo": {
"familyAddress": "CABAROAN SAN ESTEBAN ILOCOS SUR PHL 2706"
},
"personalInfo": {
"birthday": "1990/01/01",
"fullName": "JOSE CRUZ SANTOS",
"gender": "",
"idCard": "0123456789"
}
}
Check status fields
| Field | In | Documented values |
|---|---|---|
process_status | ekyc_ocr, ekyc_face | pending, partial_success (ekyc_ocr only), success, failure |
sanity_check_status | ekyc_ocr, ekyc_face | success, failure, disabled |
liveness_status | ekyc_face | success, failure |
compare_status | ekyc_face | matched, unmatched |
search_face_status | ekyc_ocr, ekyc_face | found, not_found, disabled |
verdict (of id_tampering) | id_tampering | good, alert, not_in_same_card, unknown |
process_statusis the processing state, not a business outcome:pendinguntil the check has finished,partial_success(ekyc_ocronly) when one side of the ID card has been processed and the other has not,successonce it has finished,failurewhen processing failed.sanity_check_statusisdisabledwhen the sanity check is turned off for your account.compare_statusisunmatchedwhenever the faces were not confirmed as the same person, including when the engine was unsure.id_tampering.verdictisgoodwhen no sign of tampering was found, andalertwhen at least one was.not_in_same_cardis returned only when your account is configured to return it as the final verdict; otherwise the result isalert.unknownmeans the tampering check returned no result.
The scores next to them (sanity_check_score, liveness_score, compare_score, id_tampering.score) are decimals between 0 and 1 inclusive.
When
search_face_statusisdisabled,search_face_resultisnull. Onekyc_face,search_face_statuscan also be an empty string when face search is turned off.
Finding the reason for a failure
The webhook and Application detail do not carry a reason for a failed check:
process_status: "failure"is all you get for a check that failed. It does not say whether the cause was liveness, image quality or a system error. Where a check ran, its result fields —compare_statusand theverdictofid_tampering— are the most specific information the payload carries.- A check that did not run is absent from the payload: its key is missing, not
null. Make your parser tolerate missing keys. reviewhas no reason field. Arejectcan have one: when enabled for your account, Application detail also returnsrejected_codeandrejected_reasonfor a rejected application. The webhook never carries them. When post-check is enabled,rejected_reasoncan bepostcheck_rejectedinstead of the underlying cause.
When to expect a webhook at all, including for abandoned and for system errors, is described under When the webhook is sent.
Shared transport errors
The parameter, auth, method, rate-limit and server errors documented for the JWT-authenticated endpoints. A code an endpoint adds beyond this set is documented under Failure codes on that endpoint's own page.
| Name | Description | Status code | Response Body |
|---|---|---|---|
| Bad Request | Invalid parameters | 400 | {"data":{},"message":"","verdict":"invalid_parameters"} |
| Unauthorized | Invalid authentication token | 401 | {"data":{},"message":"authorization header is missing","time":"2024-10-31T07:50:22Z","verdict":"missing_authorization"} |
| Token Expired | Token expired. Client should login again | 401 | {"data":{},"message":"Provided token is expired","time":"2024-10-31T07:50:22Z","verdict":"expired_token"} |
| Invalid Method | Invalid URL or method | 405 | {"data":{},"message":"method is not correct for the requested route","time":"2024-11-06T03:23:26Z","verdict":"invalid_method"} |
| Too many requests | Too many failed login attempts | 429 | {"data":{},"message":"too many failed login attempts","time":"2024-11-06T03:33:43Z","verdict":"limit_exceeded"} |
| Internal Server Error | Internal Server Error | 500 | {"data":{},"message":"Unexpected error. Error ID: ff4d5572d9df4560bb6dabc2eadd5a1e","time":"2024-11-06T03:32:09Z","verdict":"failure"} |
Log in and Full verification document their own error sets on their own pages.