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.
`customer`	`string`	No	ID of the customer (optional).
`verificationGroup`	`string`	No	ID of the verification group (optional).

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

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 '{
  "organization": "6791457be570f7f292f1fe23",
  "country": "NGA",
  "reference": "1234567890",
  "verificationLevel": "basic",
  "callbackUrl": "https://example.com/my-liveness-result",
  "customer": "6791457be570f7f292f1fe23",
  "verificationGroup": "6791457be570f7f292f1fe23"
}'

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.
`customer`	`string`	No	ID of the customer (optional).
`verificationGroup`	`string`	No	ID of the verification group (optional).

Sample Request

curl

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",
  "customer": "6791457be570f7f292f1fe23",
  "verificationGroup": "6791457be570f7f292f1fe23"
}'

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"
}

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.

SID Liveness Web SDK - Customization Guide

Overview

The SID Liveness Web SDK supports customization through URL query parameters, allowing you to modify the appearance and behavior of the liveness check interface.

Supported Query Parameters

`hideBranding`

Type: boolean
Default: false
Description: Hide the "Powered by SourceID" footer branding
Usage: ?hideBranding=true

`customTitle`

Type: string
Default: "Liveness Check"
Description: Replace the default title with your custom text
Usage: ?customTitle=Face%20Verification

`theme`

Type: 'light' | 'dark'
Default: 'light'
Description: Set the color theme for the interface
Usage: ?theme=dark

`primaryColor`

Type: string (hex color)
Default: "#2B2347"
Description: Set the primary color for buttons and accents
Usage: ?primaryColor=%23FF5733

Usage Examples

Basic Usage

https://liveness.sourceid.tech/session-123

Hide Branding

https://liveness.sourceid.tech/session-123?hideBranding=true

Custom Title

https://liveness.sourceid.tech/session-123?customTitle=Identity%20Verification

Dark Theme

https://liveness.sourceid.tech/session-123?theme=dark

Multiple Parameters

https://liveness.sourceid.tech/session-123?hideBranding=true&customTitle=Face%20Scan&theme=dark&primaryColor=%23007BFF

URL Encoding

Remember to URL-encode special characters in query parameter values: - Spaces: %20 or + - Hash (#): %23 - Ampersand (&): %26 - Equals (=): %3D

Implementation Details

The SDK uses Next.js useSearchParams to extract query parameters and applies them through a centralized configuration system. All parameters are optional and fall back to sensible defaults.

Future Customizations

The architecture supports easy addition of new customization options such as: - Custom logos - Layout variations - Content customization - Language localization - Color theming beyond primary color