NAV Navbar
Logo

H5 Liveness Detection

Change Log

V6.3.0 (2025.6)

V6.2.6 (2024.8)

V6.2.5 (2024.6)

V6.2.4 (2024.4)

V6.2.1 (2024.2)

V6.1.4 (2024.1)

V6.1.0 (2023.6)

Integration Guideline

Preparation

There are 3 steps before integrating H5 Liveness Detection:

Step1: Choose an integration method.

Step2: Give permission. Please refer to Frontend Permission.

Step3: Customise UI (optional). Please call ConfigureUI API to customise the H5 Liveness UI.

Choose integration methods

There are 2 integration methods available:

Methods feature
Open Liveness Detection Pro URL directly - Easier integration
- Resource isolation from your page
Load Liveness Detection Pro URL in iframe - The user doesn’t have to leave the current page.
- Liveness detection requires the user to go full screen

Integration of Liveness Detection

Note : Please first check the Glossary for basic information about ADVANCE AI API.

API Authentication

Generate accessToken by passing the accessKey through the Token Authentication API. The accessToken will be used in the subsequent API calls.

Liveness Detection process

Step1: Request Get Token API to set returnUrl and obtain signatureId and url.

Step2: Users go through the Liveness Detection process

Step3: Request Liveness Detection API to get the liveness score and its corresponding image with “signatureId”.

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

Users go through the Liveness Detection process

  1. Open the H5 Liveness Detection page so the user can start the Liveness Detection process.
  2. The user goes through the Liveness Detection process as guided, the result score will be shown to the user after completion. If the user faces a camera issue, the user can go to the cross device process.
  3. After completion, the Liveness Detection page will be redirected to returnUrl.

Cross device process

If a user cannot complete the Liveness Detection due to camera issues, the user can continue the verification process through the cross device process. You need to contact us to activate the fallback option in order to enable the cross device process.

The cross device process is as follows:

  1. The user copies the cross device process link.
  2. The user opens the copied link in another browser to go through the Liveness Detection process.
    1. If the camera function is normal, liveness detection is successfully completed.
    2. If the camera function is normal, liveness detection fails and the user can try in another browser as long as the page on initial device is still available.
  3. The initial device liveness detection will poll for the results of the cross device process, the liveness detection process ends once results are obtained.

Frontend Permission

H5 Iframe integration

Step1 In the Get Token API, you need to add isLivenessIframe=true after the returnUrl and failedReturnUrl links.

curl --location --request POST 'https://api.advance.ai/openapi/liveness/v2/h5/token' --header 'X-ACCESS-TOKEN: xxx' --header 'Content-Type: application/json' --header 'Cookie: JSESSIONID=26D72B9074019D342F05138D11566211; JSESSIONID=431C60369BA92B23E877E277256F49C9' --data-raw '{
    "returnUrl":"https://www.example-success.com/?id=123&isLivenessIframe=true",
    "tryCount":1000,
    "region":"IDN",
    "failedReturnUrl":"https://www.example-fail.com/?id=123&isLivenessIframe=true"
}'

Step2 To allow iframe to visit camera , you need to add allow attribute with “autoplay; camera;” value.

 <iframe src="liveness-url-here" allow="autoplay; camera;"></iframe>

Step3 When the Liveness Detect is completed, successNext or failedNext will be sent to the parent iframe via postmessage. In the outer layer, you can register the message to receive the time.

window.addEventListener('message', function (event) {
  if (event.origin === 'https://liveness.advance.ai') {
    const data = JSON.parse(event.data);
    if (data.info === 'successNext') {
      // the liveness detect success
    } else if (data.info === 'failedNext') {
      // the liveness detect failed
    }
  }
});

Please note that,

  1. The integration only works with HTTPs. Besides, to ensure the best security was held, please make sure only trusted websites were allowed here.
  2. The srcattribute should be URL encoded. In Javascript, you can use encodeURIComponent method to achieve that.

Following is an example:

const url = "liveness-url-here";<br>
const encodedUrl = encodeURIComponent(url);
<iframe src=encodedUrl allow="autoplay; camera;"></iframe>

Android App

You need to configures the Webview:

webView.settings.javaScriptEnabled = true
webView.webChromeClient = mWebChromeClient

To allow Android Webview to visit camera, you need to override the following methods in your app:

private var mWebChromeClient: WebChromeClient = object : WebChromeClient() {

    override fun onPermissionRequest(request: PermissionRequest?) {

        //  IMPORTANT: Check host and adapt filter to allow camera access
        // e.g. if (request?.origin?.host == "xxx") {...}

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
            if (context is BaseActivity) {
                if (ContextCompat.checkSelfPermission(
                        context,
                        Manifest.permission.CAMERA
                    ) == PackageManager.PERMISSION_GRANTED
                ) {
                    request?.grant(request.resources)
                } else {
                    context.requestPermission(Manifest.permission.CAMERA) { granted ->
                        if (granted) {
                            request?.grant(request.resources)
                        } else {
                            request?.deny()
                        }
                    }
                }
            }
        }
    }

}

iOS App

To allow iOS Webview to visit camera, you need the following adjustment:

<key>NSCameraUsageDescription</key> 
<string>$(PRODUCT_NAME) need to use your front camera</string>  

let configuration = WKWebViewConfiguration()
configuration.allowsInlineMediaPlayback = true
configuration.mediaTypesRequiringUserActionForPlayback = []
configuration.preferences.javaScriptEnabled = true
configuration.preferences.javaScriptCanOpenWindowsAutomatically = true
self.webView = WKWebView(frame: self.view.bounds, configuration: configuration)

// 请求相机权限(swift 样例代码)
// Request camera permission (in Swift)
func checkAVAuthorizationStatus(with block: @escaping((_ authed: Bool) -> Void)) {
    let authStatus = AVCaptureDevice.authorizationStatus(for: .video)
    if authStatus == .authorized {
        block(true)
    } else if authStatus == .denied || authStatus == .restricted {
        block(false)
    } else {
        AVCaptureDevice.requestAccess(for: .video) { (result) in
            DispatchQueue.main.async {
                block(result)
            }
        }
    }
}

// Usage
// Check auth status before entering H5 liveness webpage.
self.checkAVAuthorizationStatus { authed in
  if authed {
    // Enter H5 webpage directly
  } else {
    // Logic to handle camera unauthorised.
  }
}

// Make sure your ViewController inherits WKUIDelegate.
class ViewController: UIViewController, WKUIDelegate {
    ...

    // Only verified for iOS 15+
    @available(iOS 15.0, *)
    func webView(_ webView: WKWebView, requestMediaCapturePermissionFor origin: WKSecurityOrigin, initiatedByFrame frame: WKFrameInfo, type: WKMediaCaptureType, decisionHandler: @escaping (WKPermissionDecision) -> Void) {
        // NOTE: please add necessary security check like domain filter if needed.
        decisionHandler(.grant)
    }

}

self.webView.uiDelegate = self

Token Authentication API

This is the API for getting the Access Token.

Request Url

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

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 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:

Example of Success Response:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
    "token":"eyJhbG****nySgph1dbyC1E0LtifS-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 error,please check you input.
free Parameter should not be empty
free Invalid returnUrl, please check your returnUrl
free try count must > 0
ACCOUNT_DISABLED free Account Disabled
CLIENT_ERROR free HTTP 400 - Bad Request

ConfigureUI API

Below are the instructions of how to integrate with the API to enable customizing UI through configurations

Request URL

https://api.advance.ai/openapi/liveness/v1/h5/configureUI
POST (application/json)

Request Header Parameters

Parameter Description
X-ACCESS-TOKEN string Your access token

Request Parameters


  {
    "titleText": "Liveness Detection",
    "locale": "en",
    "mobileCameraPage": {
        "tipsTextColor": null,
        "backgroundColor": null,
        "backgroundLink": null,
        "faceNotCenterTipText": "Please move your face to the center of the face frame",
        "faceNotCenterTipTextColor": null,
        "faceNotFrontalTipText": "Please turn your face straight to the camera",
        "faceNotFrontalTipTextColor": null,
        "faceTooFarTipText": "Move closer",
        "faceTooFarTipTextColor": null,
        "faceTooNearTipText": "Move away",
        "faceTooNearTipTextColor": null,
        "keepStillTipText": "Please stay still and start testing",
        "keepStillTipTextColor": null,
        "moveLeftTipText": "Please move your face to the left",
        "moveLeftTipTextColor": null,
        "moveRightTipText": "Please move your face to the right",
        "moveRightTipTextColor": null,
        "moveTopTipText": "Please move your face down",
        "moveTopTipTextColor": null,
        "moveBottomTipText": "Please move your face up",
        "moveBottomTipTextColor": null,
        "multipleFacesTipText": "Multiple faces detected from the image, please only keep one face in the image",
        "multipleFacesTipTextColor": null,
        "faceMissingTipText": "Please move your face to the center of the face frame",
        "faceMissingTipTextColor": null,
        "faceOcclusionTipText": "Please don't cover your face",
        "faceOcclusionTipTextColor": null,
        "pageName": "mobile camera page"
    },
    "mobileLoadingPage": {
        "progressColor": null,
        "loadingText": "Loading...",
        "loadingTextColor": "#ffffff"
    },
    "mobileResultPage": {
        "successIconLink": null,
        "failedIconLink": null,
        "successDesc": "Liveness Detection succeed",
        "failedDesc": "Liveness Detection failed",
        "showScore": false,
        "nextStepButtonText": "Next Step",
        "nextStepButtonBackgroundColor": null,
        "tryAgainButtonText": "Please try again",
        "tryAgainButtonBackgroundColor": null,
        "nextStepButtonInvisibleBeforeTryCountUseUp": null,
        "livenessResultTextColor": null,
        "nextStepButtonTextColor": null,
        "tryAgainButtonTextColor": null,
        "nextStepButtonBackgroundLink": null,
        "tryAgainButtonBackgroundLink": null,
        "backgroundColor": null,
        "backgroundLink": null,
        "isShow": true,
        "faceShow": null,
        "countdownText": "Go to next process after {second} seconds.",
        "countdownTextColor": null,
        "closeCountdownLogic": null
    },
    "mobileMultiDeviceProcessPage": {
        "refreshPageTopIconLink": null,
        "refreshPageBoldText": "Camera permission denied",
        "refreshPageBoldTextColor": null,
        "refreshPageTipText": "Please grant camera permission\nRefresh this page to start the liveness detection process",
        "refreshPageTipTextColor": null,
        "refreshPageBtnText": "Refresh",
        "refreshPageBtnTextColor": null,
        "refreshPageBtnBackgroundLink": null,
        "refreshPageBtnBackgroundColor": null,
        "qrCodePageTopIconLink": null,
        "qrCodePagePermissionDeniedBoldText": "Camera permission denied",
        "qrCodePagePermissionDeniedBoldTextColor": null,
        "qrCodePagePermissionDeniedTipText": "Please copy the link or scan the QR code to verify on another browser or device",
        "qrCodePagePermissionDeniedTipTextColor": null,
        "qrCodePageCameraIssueBoldText": null,
        "qrCodePageCameraIssueBoldTextColor": null,
        "qrCodePageCameraIssueTipText": "Please copy the link or scan the QR code to verify on another device",
        "qrCodePageCameraIssueTipTextColor": null,
        "qrCodePageLivenessLinkBackgroundLink": null,
        "qrCodePageLivenessLinkBackgroundColor": null,
        "qrCodePageLivenessLinkTextColor": null,
        "qrCodePageLivenessLinkBorderColor": null,
        "qrCodePageCopyLinkBtnText": "Copy",
        "qrCodePageCopyLinkBtnTextColor": null,
        "qrCodePageCopyLinkBtnBackgroundLink": null,
        "qrCodePageCopyLinkBtnBackgroundColor": null,
        "verifyFinishedPageTopIconLink": null,
        "verifyFinishedPageBoldText": "Verification completed",
        "verifyFinishedPageBoldTextColor": null,
        "verifyFinishedPageTipText": "Please return to the original browser to continue",
        "verifyFinishedPageTipTextColor": null,
        "videoUploadingText": "Please wait for the video uploading",
        "videoUploadingTextColor": null
    },
    "mobileTimeoutPage": {
        "boldText": "Time out",
        "boldTextColor": null,
        "tipText": "Please follow the instructions",
        "tipTextColor": null,
        "iconLink": null,
        "tryAgainButtonText": "Please try again",
        "tryAgainButtonTextColor": null,
        "tryAgainButtonBackgroundLink": null,
        "tryAgainButtonBackgroundColor": null,
        "backgroundColor": null,
        "backgroundLink": null
    }
}


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


  //On the page of tips in the mobile side
  M_TITLE_TOO_LONG_TIPS_PAGE("The title is too long of tips page."),
  M_TITLE_DESC_TOO_LONG_TIPS_PAGE("The title description is too long of tips page."),
  M_BACKGROUND_NOT_COLOR_TIPS_PAGE("Wrong format of the tips page background color."),
  M_TIPS_COUNT_OVERSTEP_TIPS_PAGE("The number of prompts exceeds the limit, supporting up to four."),
  M_TIP_ICON_LINK_NOT_URL_TIPS_PAGE("Wrong format of the icon link at tips page."),
  M_TIPS_TOO_LONG_TIPS_PAGE("The tips is too long of tips page."),
  M_BUTTON_TEXT_TOO_LONG_TIPS_PAGE("The button text is too long of tips page."),
  M_BUTTON_BACKGROUND_NOT_COLOR_TIPS_PAGE("Wrong format of the start button background color of tips page."),
  //On the page of loading in the mobile side
  M_LOADING_TEXT_TOO_LONG_LOADING_PAGE("The loading text is too long of loading page."),
  M_PROGRESS_COLOR_WRONG_LOADING_PAGE("Wrong format of the loading page progress color."),

  //On the page of failure in the mobile side
  M_DESC_TEXT_TOO_LONG_FAILED_DIALOG("The description text is too long of failed dialog."),
  M_ICON_LINK_NOT_URL_FAILED_DIALOG("Wrong format of the icon link at detection failed dialog."),
  M_BUTTON_TEXT_TOO_LONG_FAILED_DIALOG("The button text is too long of failed dialog."),
  M_BUTTON_TEXT_BACKGROUND_NOT_COLOR_FAILED_DIALOG("Wrong format of the confirm button background color of detection failed dialog."),

  //On the page of result in the mobile side
  M_SUCCESS_ICON_LINK_NOT_URL_RESULT_PAGE("Wrong format of the success icon link at result page."),
  M_FAILED_ICON_LINK_NOT_URL_RESULT_PAGE("Wrong format of the failed icon link at result page."),
  M_SUCCESS_DESC_TEXT_TOO_LONG_RESULT_PAGE("The success description text is too long of result page."),
  M_FAILED_DESC_TEXT_TOO_LONG_RESULT_PAGE("The failed description text is too long of result page."),
  M_NEXT_STEP_BUTTON_TEXT_TOO_LONG_RESULT_PAGE("The next step button text is too long of result page."),
  M_TRY_AGAIN_BUTTON_TEXT_TOO_LONG_RESULT_PAGE("The try again button text is too long of result page."),
  M_NEXT_STEP_BUTTON_BACKGROUND_COLOR_WRONG_RESULT_PAGE("Wrong format of the result page next step button background color"),
  M_TRY_AGAIN_BUTTON_BACKGROUND_COLOR_WRONG_RESULT_PAGE("Wrong format of the result page try again button background color"),

  //Prompt page on PC
  M_TITLE_TOO_LONG_TIPS_PAGE_PC("The title is too long of PC tips page."),
  M_TITLE_DESC_TOO_LONG_TIPS_PAGE_PC("The title description is too long of PC tips page."),
  M_TIPS_COUNT_OVERSTEP_TIPS_PAGE_PC("The number of PC tips exceeds the limit, supporting up to four."),
  M_TIP_ICON_LINK_NOT_URL_TIPS_PAGE_PC("Wrong format of the icon link at PC tips page."),
  M_TIPS_TOO_LONG_TIPS_PAGE_PC("The tips is too long of PC tips page."),
  M_BUTTON_TEXT_TOO_LONG_TIPS_PAGE_PC("The button text is too long of PC tips page."),
  M_BUTTON_BACKGROUND_NOT_COLOR_TIPS_PAGE_PC("Wrong format of the start button background color of PC tips page."),

  //Failure page on PC
  M_DESC_TEXT_TOO_LONG_PC_FAILED_DIALOG("The description text is too long of PC failed dialog."),
  M_ICON_LINK_NOT_URL_PC_FAILED_DIALOG("Wrong format of the icon link at detection PC failed dialog."),
  M_BUTTON_TEXT_TOO_LONG_PC_FAILED_DIALOG("The button text is too long of PC failed dialog."),
  M_BUTTON_TEXT_BACKGROUND_NOT_COLOR_PC_FAILED_DIALOG("Wrong format of the confirm button background color of detection PC failed dialog."),

  //Camera page on PC
  M_TITLE_TOO_LONG_CAMERA_PAGE_PC("The title is too long of PC camera page."),
  M_TITLE_DESC_TOO_LONG_CAMERA_PAGE_PC("The title description is too long of PC camera page."),
  M_TAKE_PHOTO_ICON_LINK_NOT_URL_CAMERA_PAGE_PC("Wrong format of the icon link of take photo button at PC camera page."),

  //Result page on PC
  M_SUCCESS_ICON_LINK_NOT_URL_RESULT_PAGE_PC("Wrong format of the success icon link at PC result page."),
  M_FAILED_ICON_LINK_NOT_URL_RESULT_PAGE_PC("Wrong format of the failed icon link at PC result page."),
  M_SUCCESS_DESC_TEXT_TOO_LONG_RESULT_PAGE_PC("The success description text is too long of PC result page."),
  M_FAILED_DESC_TEXT_TOO_LONG_RESULT_PAGE_PC("The failed description text is too long of PC result page."),
  M_NEXT_STEP_BUTTON_TEXT_TOO_LONG_RESULT_PAGE_PC("The next step button text is too long of PC result page."),
  M_TRY_AGAIN_BUTTON_TEXT_TOO_LONG_RESULT_PAGE_PC("The try again button text is too long of PC result page."),
  M_NEXT_STEP_BUTTON_BACKGROUND_COLOR_WRONG_RESULT_PAGE_PC("Wrong format of the PC result page next step button background color"),
  M_TRY_AGAIN_BUTTON_BACKGROUND_COLOR_WRONG_RESULT_PAGE_PC("Wrong format of the PC result page try again button background color"),

Get Token API

Request Example:

curl -X POST  \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: application/json" \
-d '{"returnUrl": "https://www.example.com","region":"IDN"}' \
"https://api.advance.ai/openapi/liveness/v2/h5/token"

Request Url

https://api.advance.ai/openapi/liveness/v2/h5/token
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
returnUrl string The target URL of the web page jump after completing the H5 Liveness Detection
userId string optional The user ID
failedReturnUrl string optional The target URL of the web page jump after failed the H5 Liveness Detection
region string The region of the service support, format please refer to ISO ALPHA-3 Country Code
tryCount string optional The maximum number of failures that the user can do the H5 Live Detection. If none, the number of times is once. This retry mechanism is only effective for backend liveness detection failures. deprecated since v6.0.0
productLevel string optional Enum parameter STANDARD or PRO

Example of SUCCESS Response:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
        "signatureId":"f302f5d2454a85c2",
        "url":"https://token=eyJhbGciOiJIUzUxCwiZ1Htmc77hMxFGTnYmyVBVSpXv1kX5o6OvSY8-prfBBVJxnhWR4cBfZ_s6AHtjNefIPi5fqg"
    },
    "extra":null,
    "transactionId":"f302f5d2454a85c2",
    "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"
}

{
    "code":"PARAMETER_ERROR",
    "message":"try count must > 0",
    "data":null,
    "extra":null,
    "transactionId":"c84f79e15fddf753",
    "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 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 signatureId signatureId which can use it to get the liveness result
url Get liveness URL(this URL is valid in 3600 seconds.)
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 try count must > 0
free Invalid failedReturnUrl, please check your failedReturnUrl
ERROR free Server error

Get Result API

After the Liveness Detection process is done on the user side, you can request the Liveness Detection 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/openapi/liveness/v4/h5/get-result"

Request Url

https://api.advance.ai/openapi/liveness/v4/h5/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 liveness result

Example of SUCCESS Response:

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "image": "/9j/4AAXXXXXXXXXX",
        "imageFar": "/9j/4AAXXXXXXXXXX",
        "imageNear": "/9j/4AAXXXXXXXXXX",
        "farImageTime": 1713247589908,
        "nearImageTime": 1713247593101,
        "auditImageUrl": null,
        "score": 100,
        "cameraType": "WEB_CAMERA",
        "video": "GkXfo6NChoEBQveBA4EEQoWBAhhTgGcB",
        "attackType": null
    },
    "extra": null,
    "transactionId": "0749ac5e17200576",
    "pricingStrategy": "FREE"
}

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "image": "/9j/4AAXXXXXXXXXX",
        "imageFar": "/9j/4AAXXXXXXXXXX",
        "imageNear": "/9j/4AAXXXXXXXXXX",
        "farImageTime": 1713247589908,
        "nearImageTime": 1713247593101,
        "auditImageUrl": null,
        "score": 0,
        "cameraType": "WEB_CAMERA",
        "video": "GkXfo6NChoEBQveBA4EEQoWBAhhTgGcB",
        "attackType": 2
    },
    "extra": null,
    "transactionId": "0749ac5e17200576",
    "pricingStrategy": "FREE"
}

Example of TOO_MANY_FACES_DETECTED Response:

{
    "code":"TOO_MANY_FACES_DETECTED",
    "message":"Multiple faces detected from the image,please only keep one face in the image.",
    "data":{
        "image":"/9j/4AAQSkZJRgABAQAAAQABAAD.../",
        "imageFar": "/9j/4AAXXXXXXXXXX",
        "farImageTime": 1713247589908,
        "nearImageTime": null,    
        "imageNear":null,
        "auditImageUrl": null,
        "score":null,
        "cameraType": "WEB_CAMERA",
        "video": null,
        "attackType": null
    },
    "extra":null,
    "transactionId":"652a2cf01a12e254",
    "pricingStrategy":"FREE"
}

Example of NO_FACE_DETECTED Response:

{
    "code":"NO_FACE_DETECTED",
    "message":"No face detected from the image.",
    "data":{
        "image":"/9j/4AAQSkZJRgABAQAASABIAAD.../",
        "imageFar": "/9j/4AAXXXXXXXXXX",        
        "farImageTime": 1713247589908,
        "nearImageTime": null,
        "imageNear":null,
        "auditImageUrl": null,
        "score":null,
        "cameraType": "WEB_CAMERA",
        "video": null,
        "multiDevice": false,
        "useSlaveUrl": false,
        "attackType": null
    },
    "extra":null,
    "transactionId":"05f1cab930ff355f",
    "pricingStrategy":"FREE"
}

Example of INVALID_FACE_DETECTED Response:

{
    "code":"INVALID_FACE_DETECTED",
    "message":"The face is too big,small,incomplete,please show your front-view face.",
    "data":{
        "image":"/9j/4AAQSkZJRgABAQAASABIAAD.../",
        "imageFar": "/9j/4AAXXXXXXXXXX",
        "farImageTime": 1713247589908,
        "nearImageTime": null,
        "imageNear":null,
        "auditImageUrl": null,
        "score":null,
        "cameraType": "WEB_CAMERA",
        "video": null,
        "multiDevice": false,
        "useSlaveUrl": false,
        "attackType": null
    },
    "extra":null,
    "transactionId":"238dc76503ecd659",
    "pricingStrategy":"FREE"
}

Example of FACE_OCCLUDED Response:

{
    "code":"FACE_OCCLUDED",
    "message":"Face should not be occluded,please try again.",
    "data":{
        "image":"/9j/4AAQSkZJRgABAQAASABIAAD.../",
        "imageFar": "/9j/4AAXXXXXXXXXX",
        "farImageTime": 1713247589908,
        "nearImageTime": null,
        "imageNear":null,
        "auditImageUrl": null,
        "score":null,
        "cameraType": "WEB_CAMERA",
        "video": null,
        "multiDevice": false,
        "useSlaveUrl": false,
        "attackType": null
    },
    "extra":null,
    "transactionId":"a31ace36ba5400a6",
    "pricingStrategy":"FREE"
}

Example of FACE_QUALITY_TOO_POOR Response:

{
    "code":"FACE_QUALITY_TOO_POOR",
    "message":"Face quality is too low,please try again.",
    "data":{
        "image":"/9j/4AAQSkZJRgABAQAASABIAAD.../",
        "imageFar": "/9j/4AAXXXXXXXXXX",
        "farImageTime": 1713247589908,
        "nearImageTime": null,
        "imageNear":null,
        "auditImageUrl": null,
        "score":null,
        "cameraType": "WEB_CAMERA",
        "video": null,
        "multiDevice": false,
        "useSlaveUrl": false,
        "attackType": null
    },
    "extra":null,
    "transactionId":"4e16efac9780ea71",
    "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"
}

Example of RESULT_NOT_FOUND Response:

{
    "code":"RESULT_NOT_FOUND",
    "message":"The requested resource was not found or has been deleted",
    "data":null,
    "extra":null,
    "transactionId":"d5bec4f642549caf",
    "pricingStrategy":"FREE"
}

Example of LIVENESS_NO_RESULT Response:

{
    "code":"LIVENESS_NO_RESULT",
    "message":"This token has no detection result",
    "data":null,
    "extra":null,
    "transactionId":"530ca52958c9cd0e",
    "pricingStrategy":"FREE"
}

Example of PARAMETER_ERROR Response:

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter should not be empty",
    "data":null,
    "extra":null,
    "transactionId":"a8537603443aaabf",
    "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 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 score : The score is for anti-spoofing, ranging from [0,100], less than 50 means it might be an attack.
image : Photo taken by user (is generally the same as the imageFar)，format is BASE64
imageFar : Photo taken by user in far stage，format is BASE64
imageNear : Photo taken by user in near stage，format is BASE64.
cameraType : The type of camera queried when the user used the service. Awlays return WEB_CAMERA since 6.1.0
WEB_CAMERA : The browser camera.
SYSTEM_CAMERA ： The device camera, if the user rejects camera permission, then it will query the system camera.
video : Video taken by the user, format is webm or mp4 , needs to be enabled by configuration.
auditImageUrl : The audit image link.
multiDevice : bool value.Indicate whether the user used multiple devices, needs to be enabled by configuration.
useSlaveUrl : bool value. Indicate whether the user has go through the cross device flow, needs to be enabled by configuration.
farImageTime : Timestamp of the imageFar
nearImageTime : Timestamp of the imageNear
attackType : Return attacktype when livenessScore=0
1 Presentation Attack
2 Injection Attack
3 Unsure Attack
extra Extra response info (Exception Message)

Response Code

Status Code Message
SUCCESS free OK
RESULT_NOT_FOUND free The requested resource was not found or has been deleted
TOO_MANY_FACES_DETECTED free Multiple faces detected from the image,please only keep one face in the image. Deprecated since 6.0.0
NO_FACE_DETECTED free No face detected from the image. Deprecated since 6.0.0
INVALID_FACE_DETECTED free The face is too big,small,incomplete,please show your front-view face. Deprecated since 6.0.0
FACE_OCCLUDED free Face should not be occluded,please try again. Deprecated since 6.0.0
FACE_QUALITY_TOO_POOR free Face quality is too low,please try again. Deprecated since 6.0.0
SIGNATURE_NOT_EXIST free This signatureId is not exist.
LIVENESS_NO_RESULT free This token has no detection result.
PARAMETER_ERROR free Parameter should not be empty.
ERROR free Server error.

Note: There will be image (BASE64) and score (value is null) and video (value is null) returned in the data of JSON response body for response code TOO_MANY_FACES_DETECTED 、NO_FACE_DETECTED 、INVALID_FACE_DETECTED 、FACE_OCCLUDED and FACE_QUALITY_TOO_POOR

Note: Please remember to add a handler for the Status Codes in the Glossary as well

PII Data Retention

Note : Please first check the Glossary for basic information about ADVANCE API.

Code Sample

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

"https://api.advance.ai/liveness/h5/ext/v1/clear-data?signatureId=ac66706068e737b5"

Request URL

https://api.advance.ai/liveness/h5/ext/v1/clear-data
GET

Request Header Parameters:

Parameter Description
X-ACCESS-TOKEN string 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":"ac66706068e737b5",
    "pricingStrategy":"FREE"
}

Example of PARAMETER_ERROR Response:

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter error, please check your request whether has illegal parameters",
    "data":null,
    "extra":null,
    "transactionId":"a2190c8682344303",
    "pricingStrategy":"FREE"
}

Example of ERROR Response:

{
    "code":"ERROR",
    "message":"server error",
    "data":null,
    "extra":null,
    "transactionId":"90bd3e1bd2acea48",
    "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

Note: Please remember to add a handler for the Status Codes in the Glossary as well

Glossary

Welcome to the Glossary!

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

Status Code

Notes:

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:

Request URL & Parameters

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

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

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:

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

Notes:

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:

Request URL & Parameters

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

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