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 keyHeader ValueDescription
AuthorizationBearer <JWT>Include the JWT access token to support request authentication

Request objects

metadata

The metadata object taken by Index faces and eKYC full checks.

NameTypeRequiredDescription
client_uidstringRequiredID of a user or application or any unique token
national_idstringOptionalID number of the user's ID card
unique_tokenstringOptionalThe 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

verdictDescription
pendingThe user has not completed the flow
approveOur recommendation to approve this application
reviewOur recommendation to review this application
rejectOur recommendation to reject this application
abandonedThe 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

keyDescriptionPresent in
id_front_img_uuidThe image id of front sideID Only, Full Flow
id_back_img_uuidThe image id of back sideID Only, Full Flow
qr1_img_uuidThe image id of QR codeID Only, Full Flow
selfie_image_uuidThe image id of selfie that use to compare facesSelfie Only, Full Flow
gesture_imagesList images during user do livenessSelfie Only, Full Flow
sequence_framesList frames video during user do livenessSelfie Only, Full Flow
liveness_transformed_video_idThe video id merge from sequence framesSelfie Only, Full Flow

form_data

JSON
{
  "contactInfo": {
    "familyAddress": "CABAROAN SAN ESTEBAN ILOCOS SUR PHL 2706"
  },
  "personalInfo": {
    "birthday": "1990/01/01",
    "fullName": "JOSE CRUZ SANTOS",
    "gender": "",
    "idCard": "0123456789"
  }
}

Check status fields

FieldInDocumented values
process_statusekyc_ocr, ekyc_facepending, partial_success (ekyc_ocr only), success, failure
sanity_check_statusekyc_ocr, ekyc_facesuccess, failure, disabled
liveness_statusekyc_facesuccess, failure
compare_statusekyc_facematched, unmatched
search_face_statusekyc_ocr, ekyc_facefound, not_found, disabled
verdict (of id_tampering)id_tamperinggood, alert, not_in_same_card, unknown
  • process_status is the processing state, not a business outcome: pending until the check has finished, partial_success (ekyc_ocr only) when one side of the ID card has been processed and the other has not, success once it has finished, failure when processing failed.
  • sanity_check_status is disabled when the sanity check is turned off for your account.
  • compare_status is unmatched whenever the faces were not confirmed as the same person, including when the engine was unsure.
  • id_tampering.verdict is good when no sign of tampering was found, and alert when at least one was. not_in_same_card is returned only when your account is configured to return it as the final verdict; otherwise the result is alert. unknown means 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_status is disabled, search_face_result is null. On ekyc_face, search_face_status can 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_status and the verdict of id_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.
  • review has no reason field. A reject can have one: when enabled for your account, Application detail also returns rejected_code and rejected_reason for a rejected application. The webhook never carries them. When post-check is enabled, rejected_reason can be postcheck_rejected instead 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.

NameDescriptionStatus codeResponse Body
Bad RequestInvalid parameters400{"data":{},"message":"","verdict":"invalid_parameters"}
UnauthorizedInvalid authentication token401{"data":{},"message":"authorization header is missing","time":"2024-10-31T07:50:22Z","verdict":"missing_authorization"}
Token ExpiredToken expired. Client should login again401{"data":{},"message":"Provided token is expired","time":"2024-10-31T07:50:22Z","verdict":"expired_token"}
Invalid MethodInvalid URL or method405{"data":{},"message":"method is not correct for the requested route","time":"2024-11-06T03:23:26Z","verdict":"invalid_method"}
Too many requestsToo many failed login attempts429{"data":{},"message":"too many failed login attempts","time":"2024-11-06T03:33:43Z","verdict":"limit_exceeded"}
Internal Server ErrorInternal Server Error500{"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.