Liveness Check Proxy API

Liveness Check Proxy provides a RESTful API which is used for interacting with the service. The RESTful API consists of following API resource groups:

• The Liveness Check Service offer services for the liveness verification.
• The Audit Logs Reading Service offer services for the audit logs reading.

Possible Error Codes

The API may return one of the following error codes:

Liveness Check Service

The liveness check verification flow consists of two steps, which vary slightly depending on the selected verification provider.

For the iProov verification provider, the initiation step generates a verification token, which must be passed to the iProov SDK. The iProov SDK is responsible for capturing face image of a user and transmitting it to the backend services. Once the iProov SDK completes its operations, you can proceed to the verification step to obtain the final liveness verification result.

For the Innovatrics verification provider, the initiation step is not required. The verification step requires a serialized face image captured by Innovatrics SDK to evaluate liveness and obtain the verification result.

{
  "userId": "user1"
}

{
  "initiationType": "TOKEN",
  "reference": "46a0c1fba98b9a1cae88353ae8279503"
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "INITIATION_ERROR",
    "message": "Could not initiate liveness check for the user."
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REMOTE",
    "message": "REST API call failed when fetching User Details."
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_GENERIC",
    "message": "Unknown error occurred while processing request."
  }
}

{
  "userId": "user1",
  "livenessRecord": {
    "image": "c2VsZmllSW1hZ2U=",
    "reference": "46a0c1fba98b9a1cae88353ae8279503"
  }
}

{
  "result": "ACCEPTED",
  "selfie": null
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "VERIFICATION_ERROR",
    "message": "Could not verify liveness of the user."
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REMOTE",
    "message": "REST API call failed when fetching User Details."
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_GENERIC",
    "message": "Unknown error occurred while processing request."
  }
}

Audit Logs Reading Service

The Liveness Check Proxy logs occurrences of important events, such as liveness verification initiation, upload of the probe or reference face image, or result of the liveness verification. For the convenience of reading those events, an audit log retrieval service is available through the following REST API endpoints.

This service is only available to privileged users authorized as ADMIN.

{
  "records": [
    {
      "id": "394a898b-26b4-4641-9f47-b4ea3488295e",
      "timestamp": 1724336046394,
      "message": "Received request to verify liveness from userId=user-123."
    }
  ]
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REQUEST",
    "message": "Invalid method arguments."
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_GENERIC",
    "message": "Unknown error occurred while processing request."
  }
}

{
  "id": "f400fe20-7114-4316-9264-1d505a9ef93a",
  "timestamp": 1718276453230,
  "message": "User with userId=user-123 recorded probe image.",
  "params": {
    "userId": "user-123",
    "probeImage": "<base64 encoded image>"
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REQUEST",
    "message": "Audit log was not found."
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_GENERIC",
    "message": "Unknown error occurred while processing request."
  }
}