Skip to content

Liveness Check

This API allows you to perform a liveness check to verify that a person is real and present during the verification process.

Generate Liveness Check Session

Endpoint: POST {baseurl}/v1/api/liveness/generate-liveness-url

This endpoint generates a liveness check session and provides a URL that can be used to perform the liveness check through a web SDK.

Request Body

Parameter Type Required Description
callbackUrl string No The URL to receive liveness check results.
identity string No A unique identifier for the user.

Development Tip

If a callback URL was provided in the generate request, the system will send the liveness check results to this URL once the process is complete.

Sample Request

curl -X 'POST' \
  'https://{baseurl}/v1/api/liveness/generate-liveness-url' \
  -H 'accept: application/json' \
  -H 'x-api-key: {API-KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "identity": "6791457be570f7f292f1fe23",
  "organization": "6791457be570f7f292f1fe23",
  "country": "NGA",
  "reference": "1234567890",
  "verificationLevel": "basic",
  "callbackUrl": "https://example.com/my-liveness-result"
}'

Sample Response

{
  "responseCode": "00",
  "isValid": true,
  "data": {
    "sessionId": "0a3c8be0-29d7-4d0d-90e6-42ed4f50bf8d",
    "frontendUrl": "https://liveness.{baseurl}/0a3c8be0-29d7-4d0d-90e6-42ed4f50bf8d",
    "metaData": {
      "requestId": "16d02b32-6c9d-4c98-82e8-f67e74c86b86",
      "attempts": 1,
      "totalRetryDelay": null
    }
  },
  "referenceId": "0a3c8be0-29d7-4d0d-90e6-42ed4f50bf8d",
  "timeStamp": "Fri May 16 2025 10:53:27 GMT+0000 (Coordinated Universal Time)",
  "statusCode": "200"
}

Check Liveness Session Result

Endpoint: POST {baseurl}/v1/api/liveness/liveness-result

This endpoint allows you to check the result of a liveness check session.

Request Body

Parameter Type Required Description
reference string Yes The session ID obtained from the generate endpoint.

Sample Request

curl -X 'POST' \
  '{baseurl}/v1/api/liveness/liveness-result' \
  -H 'accept: application/json' \
  -H 'x-api-key: {API-KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "reference": "ad717c90-79fe-4586-94b9-56de75d957fd"
}'

Sample Response

{
  "responseCode": "00",
  "isValid": true,
  "data": {
    "sessionId": "ad717c90-79fe-4586-94b9-56de75d957fd",
    "status": "SUCCEEDED",
    "confidence": 77.32842254638672,
    "referenceImageUrl": "https://amplify-sidfaceliveness-prod-b44ca-deployment.s3.us-east-1.amazonaws.com/studio-backend-rd/ad717c90-79fe-4586-94b9-56de75d957fd/reference.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAYS2NRJUV4IFDHU55%2F20250516%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250516T105152Z&X-Amz-Expires=3600&X-Amz-Signature=2e92c107badecec1d7f8d9133a72fee97e827d5fd00a3f4359334605741b6595&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject",
    "metaData": {
      "requestId": "b899b230-679a-4f36-acd7-eb285f47bc24",
      "attempts": 1,
      "totalRetryDelay": null
    }
  },
  "referenceId": "ad717c90-79fe-4586-94b9-56de75d957fd",
  "timeStamp": "Fri May 16 2025 10:51:51 GMT+0000 (Coordinated Universal Time)",
  "statusCode": "200"
}

Integration Flow

Generate a Liveness Check Session

  1. Call the /v1/api/liveness/generate-liveness-url endpoint to obtain a session ID and frontend URL.
  2. Direct the user to the provided frontend URL to complete the liveness check process.

Check Liveness Results

  1. Call the /v1/api/liveness/liveness-result endpoint with the session ID to get the results of the liveness check.
  2. Process the result based on the status and confidence value.

Possible Status Values

Status Description
SUCCEEDED The liveness check was successful.
FAILED The liveness check failed.
IN_PROGRESS The liveness check is in progress.
EXPIRED The liveness check session has expired.