H5 Liveness Detection

Change Log

V10.9.0 (2025.12)

Added support silent, action, 3D+action liveness detection methods.

V6.3.2 (2025.11) To access the documentation for previous API versions, please see here

Added support for displaying the AAI logo on the liveness detection collection page.
Resolved the issue where video recording remained in a persistent “pending” state on some iOS devices.

V6.3.1 (2025.7)

Added support for delayed camera activation in user-defined guide page scenarios.

V6.3.0 (2025.6)

Added some anti-injection capabilities to improve security.
Fixed some bugs.

Integration Guideline

Preparation

There are 5 steps to integrate the H5 Liveness Detection Service.

Step1: Request Generate URL API to get a signatureId and a url.

Step2: Integrate the Web SDK.

Step3: (Optionally) Receive the COMPLETED callback notification.

Step4: Request Get Result API to get the liveness score and its corresponding image with signatureId returned from step 1 as request parameter.

Step5: If there are compliance requirements, call PII Data Retention to clean up PII (Personally identifiable information) data when you need

Generate URL API

Call this API to generate a H5 Liveness Detection link.

Request Example:

curl -X POST \
-H 'Content-Type: application/json' \
-H 'X-ACCESS-TOKEN:{Your Access Token}' \
-D '{
        "returnUrl": "https://www.example.com",
        "failReturnUrl":"https://www.example.com/fail",
        "callbackUrl": "https://www.example.com/callback",
        "bizId": "7ac66c0f148de9519b8bd264312c4d64", 
        "userId":"8e44f0089b076e18a718eb9ca3d94674",
        "region":"PHL",
        "language": "en-US",
        "prefersColorScheme":"light",
        "bizCode":"WhiteCard",
        "productLevel": "STANDARD",
        "livenessType": "DISTANT_NEAR"
    }'\
"https://api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-liveness-detection-url"

Request Url

https://api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-liveness-detection-url
POST (application/json)

Request Header Parameters

Parameter	Description
X-ACCESS-TOKEN	`string` Please Click here to get your access token

Request Parameters

Parameter	Description
returnUrl	`string` The target URL of the web page jump after user completes the H5 Liveness Detection processing in frontend.Refer to Frontend Integration(H5)
failReturnUrl	`string` The target URL of the web page jump after user fails to complete the H5 Liveness Detection processing in frontend. Refer to Frontend Integration(H5)
callbackUrl	`string` `optional` The target URL to notify the caller after the H5 Liveness Detection result is all completed (include Id forgery result).Refer to Callback Notification
bizId	`string` The unique business id to identify the business transaction that triggered this H5 Liveness Detection processing, such as order id.
userId	`string` The unique userId to identify the user who is performing the H5 Liveness Detection.
region	`string` The service region for Liveness Detection，typically aligned with the user’s residence. Refer to ISO ALPHA-3 Country Code
language	`string` `optional` Specifies the display language for the frontend interface using ISO 639-1 language codes (e.g., `en`, `zh`, `fil`, `id`, `th`, `bn`, `ms`).For the complete list of supported languages, refer to Supported Languages.Fallback Logic: When the specified language is not supported, the system will fall back sequentially:Language specified in Generate URL APILanguage from user’s browser settingsDefault language (`en`)
prefersColorScheme	`string` `optional` Default “light”. Refer to prefersColorScheme.
bizCode	`string` `optional` The business type of the user. max size of the length is 32. only support characters a-zA-z0-9
iframeEnabled	`boolean` `optional` The iframeEnabled parameter controls the integration mode for the workflow. When set to true, the generated URL enables iframe embedding, allowing the workflow to be seamlessly integrated into your web application without requiring users to leave your interface. In this mode, please refer to Iframe-integration for implementation details.When set to false, the system will redirect users using either the returnUrl (for successful completion) or failReturnUrl (for failed attempts) instead of iframe embedding.
productLevel	`string` `optional` The productLevel that satisfy the client’s business needs. Refer to ProductLevel.
livenessType	`string` `optional` Default to `DISTANT_NEAR`. Determine how the user go through the liveness capture. Refer to Liveness Type List

ProductLevel

The productLevel defines the tier of the H5 Liveness Detection service. Please consult with our sales representative to determine the tier that best aligns with your business requirements and use the granted product level for your API request submission.

Supported Values	Description
STANDARD	Basic compliance / High coverage rate / Acceptable accuracy
PRO	Medium compliance / High pass rate / High accuracy

prefersColorScheme

indicate the theme that AAI’s Frontend should use.

Supported Values	explained
light	light theme.
dark	dark theme.

Example of SUCCESS Response:

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "signatureId": "ed8b21c0c87ad617",
        "url": "https://h5.advance.ai/idvs/?token=eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJoNV9saXZlbmVzcyIsInN1YiI6IntcImN1c3RvbWVySWRcIjozMTUwMjk4LFwiYWNjb3VudElkXCI6MzE1MDI5OSxcIl90aW1lc3RhbXBcIjoxNzA4NTA5ODk5OTI4LFwiX3V1aWRcIjpcIjFmYzEzOWExMTY1YjRjMTBiY2U4MDFkM2RkMjRhYzI4XCJ9IiwiYXVkIjoiV0VCIiwiaWF0IjoxNzA4NTA5ODk5LCJleHAiOjE3MDg1MTM0OTl9.VKpPl8fDtdhD2y6Y2VwUYOdlnJKusRrDtmfw4FY6lq2kbStk0J45VdchdEHl4oa9SZq9_b9hYBJ1KzCSegAglA&signatureId=ed8b21c0c87ad617",
        "expiredTime":1642580192430
    },
    "extra": null,
    "transactionId": "ed8b21c0c87ad617",
    "pricingStrategy": "FREE"
}

Example of REGION_WRONG Response:

{
    "code":"REGION_WRONG",
    "message":"Region is wrong",
    "data":null,
    "extra":null,
    "transactionId":"0f74aeb4dd3f1d48",
    "pricingStrategy":"FREE"
}

Example of PARAMETER_ERROR Response:

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter error,please check you input.",
    "data":null,
    "extra":null,
    "transactionId":"ba134d6112c57a4c",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter should not be empty",
    "data":null,
    "extra":null,
    "transactionId":"dfcdc346a81f404f",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Invalid returnUrl,please check your returnUrl",
    "data":null,
    "extra":null,
    "transactionId":"876cf2a354f73725",
    "pricingStrategy":"FREE"
}

Example of ERROR Response:

{
    "code":"ERROR",
    "message":"Server error",
    "data":null,
    "extra":null,
    "transactionId":"1deae5a13ef2bd5e",
    "pricingStrategy":"FREE"
}

Response Description

Parameter	Description
code	H5 Liveness Status Code
transactionId	The request id, the max length is 64
pricingStrategy	`Deprecated`, Always return FREE
message	Status Code Explanation
data	`signatureId`: signatureId which can use it to get the result
	`url` Get H5 URL that for user to go through the process.Will expire in 3600 seconds.Refer to Frontend Integration(H5)
extra	Extra response info (Exception Message)

Response Code

Status Code	Message
SUCCESS	`free` OK
REGION_WRONG	`free` Region is wrong
PARAMETER_ERROR	`free` Parameter error,please check you input.
	`free` Parameter should not be empty
	`free` Invalid returnUrl, please check your returnUrl
	`free` Product level is wrong
	`free` Invalid failedReturnUrl, please check your failedReturnUrl
ERROR	`free` Server error

Get Result API

After the verification process is done on the user side, you can request the result by calling the Get Result API.

Request Example:

curl -X POST  \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: application/json" \
-d '{"signatureId": "f302f5d2454a85c2"}' \
"https://api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/get-result"

Request Url

https://api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/get-result
POST (application/json)

Request Header Parameters

Parameter	Description
X-ACCESS-TOKEN	`string` Please use Token Authentication API to get your access token

Request Parameters

Parameter	Description
signatureId	`string` SignatureId which can use it to get the H5 Liveness Detection result
returnImageType	`string` `Optional` `URL` or `BASE64` default to `URL`. Refer to ReturnImageType

ReturnImageType

Supported Values	Description
URL	the value of the image fields in the response will be image urls , so the caller can download images.
BASE64	the value of image fields in the repsone will be base64 encoded string of image bytes.

Example of SUCCESS Response:

{
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "signatureId": "f302f5d2454a85c2",
    "overallResult": "PASS",
    "idvResult": "PASS",
    "errorCode": "SUCCESS",
    "faceDetail": {
      "faceResult": "PASS",
      "faceImageFar": "https://abc.com/faceImageFar.jpg",
      "faceImageNear": "https://abc.com/faceImageNear.jpg",
      "auditImageUrl": "https://abc.com/auditImage.zip",
      "faceLivenessScore": 99,
      "eventDetails": [
        {
          "event": "FE_DOCUMENT_SCAN",
          "result": "PASS",
          "createTimestmap": 1665993522952
        }
      ]
    },
    "countryCodeIso3": "PHL",
    "inputParameters": {
      "returnUrl": "https://www.example.com",
      "failReturnUrl": "https://www.example.com/fail",
      "callbackUrl": "https://www.example.com/callback",
      "bizId": "7ac66c0f148de9519b8bd264312c4d64",
      "userId": "8e44f0089b076e18a718eb9ca3d94674",
      "region": "NGA",
      "language": "en-US",
      "prefersColorScheme": "light",
      "ignoreFailWhenJump": false,
      "bizCode": "WhiteCard",
      "productLevel": "STANDARD"
    }
  },
  "extra": null,
  "transactionId": "d3fde1547eeaf226",
  "pricingStrategy": "FREE"
}

Example of SIGNATURE_NOT_EXIST Response:

{
    "code":"SIGNATURE_NOT_EXIST",
    "message":"This signatureId is not exist",
    "data":null,
    "extra":null,
    "transactionId":"b6d722f7e9f553ae",
    "pricingStrategy":"FREE"
}

Response Description

Parameter	Description
code	Status Code
transactionId	The request id, the max length is 64
pricingStrategy	`Deprecated`, Always return `FREE`
message	Status Code Explanation
data	`object` : the business result of H5 Liveness Detection
extra	Extra response info (Exception Message)

Response Code

Status Code	Message
SUCCESS	OK
SIGNATURE_NOT_EXIST	This signatureId is not exist.
ERROR	Server error.

Response Data

Field	Description
signatureId	`string` The signatureId of this verification transaction.
overallResult	`string` The result code of this verification transaction.
idvResult	`string` The result code of this verification transaction. (will be deprecated, use `overallResult` instead)
errorCode	`string` The fail reason when overallResult is `FAIL` or `INCOMPLETE`
faceDetail	`object` The face verification result details. Refer toFaceDetail
countryCodeIso3	`string` The `region` in theGenerate URL API’s input.
inputParameters	`object` The request parameters that fromGenerate URL API. Refer toInputParameters

overallResult

overallResult is the result code of the H5 Liveness Detection

Value	Description
PASS	the user passed the check.
FAIL	the user failed the check.
INCOMPLETE	the user gave up in the middle of the check, or the user timeouts.

errorCode

Response Data OverallResult	Value	Description
PASS	SUCCESS	The user passed the H5 Liveness Detection.
FAIL	LIVENESS_ATTACK	True if faceDetail.faceLivenessScore < 50.0, else False.
	STRATEGY_HIT	Security policy hit. （Deprecated)
	RISK_STRATEGY_HIT	The transaction has triggered risk prevention strategies that are used to reject attacks.
INCOMPLETE	PARAMETER_ERROR	the data submitted by our frontend is not valid. this may indicates a frontend bug.
	USER_TIMEOUT	User did not complete the operation within the specified time（1 hour）
	ERROR	Error during processing in our backend. this may indicates a backend bug.

PII Data Retention

Code Sample

curl -X POST \
-H "X-ACCESS-TOKEN: {Your Access Token}" \

"https://api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/clear-data?signatureId=ac66706068e737b5"

Request URL

https://api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/clear-data
POST

Request Header Parameters

Parameter	Description
X-ACCESS-TOKEN	`string` Please use Token Authentication API to get your access token

Request Parameters:

Parameter	Description
signatureId	`string` The signatureId which you want to clean up

Example of SUCCESS Response:

{
  "code": "SUCCESS",
  "message": "OK",
  "data": null,
  "extra": null,
  "transactionId": "d3fde1547eeaf226",
  "pricingStrategy": "FREE"
}

Example of PARAMETER_ERROR Response:

{
    "code":"PARAMETER_ERROR",
    "message":"SignatureId is empty",
    "data":null,
    "extra":null,
    "transactionId":"b6d722f7e9f553ae",
    "pricingStrategy":"FREE"
}

Example of ERROR Response:

{
    "code":"ERROR",
    "message":"Server error",
    "data":null,
    "extra":null,
    "transactionId":"1deae5a13ef2bd5e",
    "pricingStrategy":"FREE"
}

Response Description:

Parameter	Description
code	Liveness Detection Status Code
transactionId	The request id, the max length is 64
pricingStrategy	Whether the request will be charged, enum type: `FREE`, `PAY`
message	Status Code Explanation
data	null
extra	Extra response info (Exception Message)

Response Code

Status Code	Message
SUCCESS	OK
PARAMETER_ERROR	SignatureId is empty
	SignatureId is not exist
	Transaction is not finished
REQUEST_IN_PROCESSING	Your request is currently being processed. Please do not submit it repeatedly
ERROR	Server error.

Token Authentication

Request Parameters:

Parameter	Description
accessKey	`string` the accessKey
timestamp	`string` 13-digit-long timestamp, suggested 300 seconds before or after the current time when requesting the token
signature	`string` Combined accessKey, secretKey and timestamp, encrypted by SHA256. eg. accessKey: sampleaccesskey secretKey: samplesecretkey timestamp: 1665993522952 Combined: sampleaccesskeysamplesecretkey1665993522952 Encrypted based on the combined: 02209bbeaf0d0a3dd587f6a1ba22f84c98d142e3b545e77db7e4906ca56349f5
periodSecond	`string` `optional` Validity period defaults to 3600 seconds, minimum 60 seconds, maximum 86400 seconds. Unit is seconds

Note:

You can find accessKey, secretKey on the Websaas Platform -> Account -> Account Management
The timestamp in the “signature” must be consistent with parameter timestamp
Please remember to re-obtain a new valid token to do the authentication for the open APIs when the previous one is expired

Code Sample

curl -X POST \
-H "Content-Type: application/json" \
-d '{"accessKey":"22********70b","signature":"f786441e7b3d95f*****************853a5a244f9522","timestamp":1648785145789,"periodSecond":120}' \ 
"https://api.advance.ai/openapi/auth/ticket/v1/generate-token"

Request Url

https://api.advance.ai/openapi/auth/ticket/v1/generate-token
POST (application/json)

Example of Success Response:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
    "token":"eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJoNV9saXZlbmVzcyIsInN1YiI6IntcImN1c3RvbWVySWRcIjo1NTAwMDI4MixcImFjY291bnRJZFwiOjU1MDAwMjg0LFwicmVhbElwXCI6XCI0NS4yNTEuMTA3LjExMVwifSIsImF1ZCI6IldFQiIsImlhdCI6MTY0MjU4MDA3MiwiZXhwIjoxNjQyNTgwMTkyfQ.HmIDcuSW67A59x7bnumjGp0Wdcz-FmoDrnHF1YGui6wVPfulLn4Izonay5LQnySgph1dbyC1E0LtifS-BJo8VA",
    "expiredTime":1642580192430
    },
    "extra":null,
    "transactionId":"6c2c50a3049ce67e",
    "pricingStrategy":"FREE"
}

Example of PARAMETER_ERROR Response:

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter should not be empty",
    "data":null,
    "extra":null,
    "transactionId":"040e769e38f87e3e",
    "pricingStrategy":"FREE"
 }

{
    "code":"PARAMETER_ERROR",
    "message":"Timestamp error",
    "data":null,
    "extra":null,
    "transactionId":"a9c2a6c199ad5db5",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Signature error",
    "data":null,
    "extra":null,
    "transactionId":"00b05cb9cf6f0fed",
    "pricingStrategy":"FREE"
}

Example of ACCOUNT_DISABLED Response:

{
    "code":"ACCOUNT_DISABLED",
    "message":"Account Disabled",
    "data":null,
    "extra":null,
    "transactionId":"5e00fded1272490e",
    "pricingStrategy":"FREE"
}

Example of CLIENT_ERROR Response:

{
    "code":"CLIENT_ERROR",
    "message":"HTTP 400 - Bad Request",
    "data":null,
    "extra":null,
    "transactionId":"bd5d5653c45d4c6e",
    "pricingStrategy":"FREE"
 }

Response Description:

Parameter	Description
`code`	Response Status Code
`message`	Message returned from server
`data`	`token` AccessToken
	`expiredTime` Expiration timestamp
`extra`	Extra response info such as exception message
`transactionId`	the request id, the max length is 64
`pricingStrategy`	whether the request will be charged, enum type: `FREE`, `PAY`

Response Code

Status Code	Message
`SUCCESS`	`free` OK
`PARAMETER_ERROR`	`free` Parameter should not be empty
	`free` Timestamp error
	`free` Signature error
`ACCOUNT_DISABLED`	`free` Account Disabled
`CLIENT_ERROR`	`free` HTTP 400 - Bad Request

Glossary

Welcome to the Glossary!

Please read the following to understand how ADVANCE API system, for a smooth integration. We will explain all the basics you need to know about our API.

Status Code

Our API responses will contain a Status Code indicating the result of the API call, whether it was successful, or an error occurred during the process
Each API will also have its own unique Status Codes that can only be found in the responses of the API
Your API usage will be charged based on the response Status Code, each Status Code listed in our API document will have either a free or pay tag with it
free means you will not be charged and paymeans that you will be charged
pay means you will be charged if the API response contains the said status code
Below are the commonly used Status Codes, these status codes could appear in all our API responses, so please remember to add a handler for these Status Codes

Notes:

Please use ‘Status Code’ in your strategy instead of ‘Message’, as 'Message’ is a detailed explanation for developer’s reference and may update without ADVANCE Notice.

Status Code	Message
`SUCCESS`	`pay` OK
`ERROR`	`free` Server error
`EMPTY_PARAMETER_ERROR`	`free` Parameter should not be empty
`INSUFFICIENT_BALANCE`	`free` Insufficient balance, please top up or contact your sales manager for help
`SERVICE_BUSY`	`free` Messages may look like: Rate limit is exceeded, please retry after the suggested time in HTTP Header. Retry-After :10s p.s. Please also note that this code may migrate to HTTP 429 Too Many Requests in the future. Quota exceeded: You have exceeded the daily quota for free queries, please contact out tech support for help
`IAM_FAILED`	`free` Access denied. Messages may look like: You are not authorized by the Identity and Access Management system Access Key not found Token not found or expired Access Key not found or expired Account not authorized for this country Account not authorized for this domain Account is expired. Please contact your sales manager for help Account is disabled. Please contact your sales manager for help Access denied: Token not found or expired
`PARAMETER_ERROR`	`free` The message is detailed error description, may includes: Parameter should not be empty Invalid phone number, please check your phone number format etc. p.s. Mobile number format should be country code + phone number(without leading 0 or dash or space e.g. +xx12345678); fixed-line number should be country code + area code + number(without leading 0)
`OVER_QUERY_LIMIT`	`free` Messages may look like: Quota exceeded. you have exceeded free query quota, please contact your sales manager for help Quota exceeded: You have exceeded free query quota for test account, please contact your sales manager for help
`CLIENT_ERROR`	`free` HTTP client error. Messages may look like: HTTP 400 - Bad Request HTTP 404 - Not Found HTTP 405 - Method Not Allowed etc. If you get this error, please check the API document or contact our tech support for help.
`RETRY_LATER`	`free` Query failed, please retry after the suggested time in HTTP Header. Retry-After :10s

Notes:

If the Status Code is SUCCESS, it may not be charged. Please check the code returned by each interface

Request URL & Parameters

Request URL can be found at each API document along with the request method (POST or GET or other request method) and Content Type (application/json or other content type)
Some parameters will have optional tag on them, this means the parameter is not mandatory for the request and they can be empty, however adding them might produce more accurate result, for example : Company check, zip code is an optional parameter but adding zip code parameter will return all the companies around that said zip code instead of all around Indonesia.
If a parameter does not have an optional tag, it means the parameter is mandatory and making request without them will return EMPTY_PARAMETER_ERROR response
Every parameter has a data type such as string, integer and file, please double check the parameter data type before making any request
Here’s an example of parameter explanation that can be found on each API document

Parameter	Description
requestString	`string` String value for API request
requestFile	`file` Request file for API request
requestInteger	`optional` `integer` Number value for API request

Response

ADVANCE API responds in JSON format
ADVANCE API response consists of 4 fields:
- code the Status Code;
- message detailed explanation of the Status Code;
- extra an exception message (should be empty most of the time);
- data the response content from ADVANCE;
Each service has its own data format, outlined in the API document
If the response format is very complicated (multiple different JSON object, nested JSON object), please refer to the Breakdown section of the Response Explanation
transactionId: It is strongly recommended to save the transactionId.
The following is an example of Response Explanation found in each API document:

Parameter	Description
code	API Status Code
message	Status Code Explanation
data	`field1`: explanation of the first information that will be returned from ADVANCE
	`field2`: explanation of the second information that will be returned from ADVANCE
extra	Extra response info (Exception Message)

Image Quality Requirements

The services check and extract the necessary information from the uploaded images, hence please ensure the uploaded images satisfy the following criteria:
- Is in one of the following image formats: PNG / JPG / JPEG
- Below 2 MB file size
- Minimum resolution of 256 x 256
- Maximum resolution of 4096 x 4096
For OCR services please also ensure that the uploaded images satisfy the following criteria:
- ID Card’s ratio in the uploaded photo is not so small that the words in the ID Card are unreadable
- ID Card’s orientation is in Vertical or Horizontal position and NOT heavily tilted (around 45 degree)
- Nothing is covering up the words in the ID Card (ex: Light Spot, Dirt, Ink, Shadow, etc)
- Have a clean background (No words or other picture in the background)