Call this API to generate an H5 Frontend link.

Request Example:

curl -X POST \
  https://sg-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-face-authentication-url \
  -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":"NGA",
"language": "en-US",
"prefersColorScheme":"light",
"ignoreFailWhenJump": false,
"bizCode":"WhiteCard",
"productLevel": "PRO"
}'

Request Url

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

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

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

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

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

https://vn-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-face-authentication-url
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 that the frontend jumps to after the user completes the verification flow. Supports standard web URLs such as `https://...` and custom schemes such as `myapp://...`. Max Length 2048 characters. Refer to Redirect URL Requirements and Frontend(H5)
failReturnUrl	`string` The target URL that the frontend jumps to after the user fails to complete the verification flow. Supports standard web URLs such as `https://...` and custom schemes such as `myapp://...`. Max Length 2048 characters. Refer to Redirect URL Requirements and Frontend(H5)
callbackUrl	`string` [Optional] The target URL to notify the caller after the Verification result is all completed. Max Length 2048 characters. `callbackUrl` only supports `http://` and `https://` URLs. Custom schemes such as `myapp://...` are not supported. Refer to Redirect URL Requirements and Callback Notification
userId	`string` The unique userId to identify the user who is performing the Verification.
region	`string` The region of the service support. Refer to ISO ALPHA-3 Country Code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
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 API Language from user's browser settings Default language (`en`)
prefersColorScheme	`string` [Optional] default "light". Refer to prefersColorScheme.
ignoreFailWhenJump	`bool` [Optional] default to false. Refer to Frontend(H5)
bizId	`string` The unique business id to identify the business transaction that triggered this Verification processing, such as order id. (only for caller's internal tracking purposes, We don't use it for business logic.)
bizCode	`string` [Optional] The business type of the user. max size of the length is 32. only support characters a-zA-z0-9. (only for caller's internal tracking purposes, We don't use it for business logic.)
iframeEnabled	The iframeEnabled parameter is used to activate iframe integration mode. When this parameter is set to true, the generated URL will allow the workflow to be embedded into your web application via an iframe. This provides a seamless experience by eliminating the need for users to leave your application interface.
productLevel	`string` Required. The productLevel that satisfies the client's business needs. Refer to ProductLevel.
livenessType	[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 Identity Verification(..DV, LD, FA) 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	Product Name	Description
STANDARD	Advanguard Face Authentication Standard	Basic compliance / High coverage rate / Acceptable accuracy
PRO	Advanguard Face Authentication 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.

Response Description

Parameter	Description
code	Response Code of this Face Authentication Transaction.
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 verification result
	`url` Get H5 URL that for user to go through the process. Will expire in 3600 seconds. Refer to Frontend(H5)
	`expiredTime` Expiration timestamp
extra	Extra response info (Exception Message)

Response Code

Status Code	Message
SUCCESS	OK
PARAMETER_ERROR	Parameter error, please check you input.
	Parameter should not be empty
	Invalid returnUrl, please check your returnUrl
	Prefers color scheme is wrong
	Region is wrong
ERROR	Server error

Response Examples

SUCCESS

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

REGION_WRONG

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

PARAMETER_ERROR

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

ERROR Response

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