Call this API to get the liveness detection result.

Request Example:

curl -X POST \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: application/json" \
-d '{"livenessId": "ddsd-9e6-dcc9-4ca1-bdfe-9f001c05f1b1","resultType": "IMAGE_URL"}' \
"https://api.advance.ai/openapi/liveness/v3/detection-result"

Request Url

https://api.advance.ai/openapi/liveness/v3/detection-result
POST (application/json)

https://sg-api.advance.ai/intl/openapi/face-identity/v1/liveness-detection
POST (application/json)

https://my-api.advance.ai/my/openapi/face-identity/v1/liveness-detection
POST (application/json)

https://th-api.advance.ai/th/openapi/face-identity/v1/liveness-detection
POST (application/json)

https://ph-api.advance.ai/ph/openapi/face-identity/v1/liveness-detection
POST (application/json)

https://mex-api.advance.ai/mex/openapi/face-identity/v1/liveness-detection
POST (application/json)

https://col-api.advance.ai/col/openapi/face-identity/v1/liveness-detection
POST (application/json)

https://nga-api.advance.ai/nga/openapi/face-identity/v1/liveness-detection
POST (application/json)

** The endpoint URI may vary by country.**

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` [Optional] signatureId from Get SignatureId API We strongly suggest using signatureId instead of livenessId
livenessId	`string` [Optional] an identifier for your user’s face photo from the SDK
resultType	`string` [Optional] Refer to resultType
region	`string` [Required in Singapore]The region of the service support, format please refer to ISO ALPHA-2/ISO ALPHA-3 Country Code

Notes

livenessId and signatureId can not be empty at the same time.

resultType

the preferred format for the liveness image, IMAGE_URL or IMAGE_BASE64. The default will be IMAGE_URL.

Supported Values	explained
IMAGE_URL	Returns a URL where the customer’s face image can be downloaded, the url will remain valid for only 24 hours.The availability of images in the format of image_url should be impacted and expected slow response when the public network’s situation is not in a good condition.
IMAGE_BASE64	Returns the base64 string of the image

Response Description

Parameter	Description
code	Status Code
transactionId	The request id, the max length is 64
pricingStrategy	always `FREE`
message	Status Code Explanation
data	`detectionResult`: `string` The image URL or the image base64
	`livenessScore` :`double` The score for anti-spoofing, ranging from [0,100], less than 50 means it might be an attack. Please refer to the Note below of given suggestions based on different liveness scores.
	`auditImageUrl`:`string`, The audit image link
	`imageFarUrl`: `string`, Photo taken by user in far stage
	`imageNearUrl`: `string`, Photo taken by user in near stage
	`farImageTime` : `long`, Timestamp of the imageFar
	`nearImageTime` : `long`, Timestamp of the imageNear
	`attackType`: `string`, Refer to attackType
	`attackSubType`: `string`, For future use, currently null
	`livenessType`:`string`, The livenessType that is used in liveness. Refer to Liveness Type List
	`livenessFlowCategory`:`string`, the category of the capture flow that is used in liveness. the capture flow is under the livenessType. Refer to livenessFlowCategory
	`sdkVersion` : `string`, Version of SDK
	`platform` : `string`, Platform of SDK. `Android` or `iOS`
extra	Extra response info (Exception Message)

Note

livenessScore
If the user’s liveness score is more than 50, that is regarded as normal behavior, and the suggestion is pass.
If the user’s liveness score is less than 50, that is regarded as abnormal behavior, and the suggestion is manual check.
imageFarUrl: Returns a URL where the customer’s face far view image can be downloaded, the url will remain valid for only 24 hours.The availability of images in the format of image_url should be impacted and expected slow response when the public network’s situation is not in a good condition.
imageNearUrl: Returns a URL where the customer’s face near near image can be downloaded, the url will remain valid for only 24 hours.The availability of images in the format of image_url should be impacted and expected slow response when the public network’s situation is not in a good condition.
auditImageUrl: Will return audit image in a link, format is zip, need to be configured in SDK first, otherwise it will be null the url will remain valid for only 24 hours.The availability of images in the format of auditImageUrl should be impacted and expected slow response when the public network’s situation is not in a good condition.

attackType

Supported Values	explained
null	when livenessScore >= 50
1	Presentation Attack ( only possible when when livenessScore < 50)
2	Injection Attack ( only possible when when livenessScore < 50)
3	Unsure Attack ( only possible when when livenessScore < 50)

Response Code

Status Code	Message
SUCCESS	OK
LIVENESS_ID_NOT_EXISTED	Liveness Id does not exist
RESULT_NOT_FOUND	The requested resource was not found or has been deleted
PARAMETER_ERROR	Parameter error, please check your request whether has illegal parameters
ERROR	Server error

Response Examples

livenessScore >= 50

{
    "code":"SUCCESS",
    "transactionId": "196eb0c777789e58",
    "pricingStrategy": "PAY",
    "message":"OK",
    "data": {
        "detectionResult":"https://XXXX/standard-images/random_20180929195400851_1478837456",
        "livenessScore": 100.0,
        "auditImageUrl": null,
        "imageFarUrl": "https:/XXXX/standard-images/random_20180929195400851_1478837457",
        "farImageTime": 1713247589908,
        "imageNearUrl": "https:/XXXX/standard-images/random_20180929195400851_1478837458",
        "nearImageTime": 1713247589908,
        "attackType": null,
        "attackSubType": null,
        "livenessType": "DISTANT_NEAR",
        "livenessFlowCategory": "DISTANT_CLOSE",
        "sdkVersion": "3.1.0",
        "platform": "Android"


    },
    "extra":null
}

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "detectionResult": "https:/XXXX/standard-images/random_20180929195400851_1478837456",
        "livenessScore": 0.0,
        "auditImageUrl": null,
        "imageFarUrl": "https:/XXXX/standard-images/random_20180929195400851_1478837457",
        "imageNearUrl": "https:/XXXX/standard-images/random_20180929195400851_1478837458",
        "nearImageTime": null,
        "farImageTime": null,
        "attackType": 3,
        "attackSubType": null,
        "livenessType": "DISTANT_NEAR",
        "livenessFlowCategory": "DISTANT_CLOSE",
        "sdkVersion": "3.1.0",
        "platform": "Android"
    },
    "extra": null,
    "transactionId": "16733ebf2ca75a0b",
    "pricingStrategy": "PAY"
}

LIVENESS_ID_NOT_EXISTED

{
  "message": "Liveness id does not exist",
  "data": null,
  "extra": null,
  "code": "LIVENESS_ID_NOT_EXISTED",
  "transactionId": "196eb0c777789e58",
  "pricingStrategy": "FREE"
}

RESULT_NOT_FOUND

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

ERROR

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