Call this API to generate an Identity Verification Solution link.

Request Example:

curl -X POST \
  https://sg-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-ekyc-verification-url \
  -H 'Content-Type: application/json' \
  -H 'X-ACCESS-TOKEN:{Your Access Token}' \
  -d '{
    "returnUrl": "myapp://verification/success",
    "failReturnUrl":"myapp://verification/fail",
    "callbackUrl": "https://www.example.com/callback",
    "bizId": "7ac66c0f148de9519b8bd264312c4d64", 
    "userId":"8e44f0089b076e18a718eb9ca3d94674",
    "region":"PHL",
    "language": "en-US",
    "docType": "PH-ID-SSS",
    "prefersColorScheme":"light",
    "ignoreFailWhenJump": false,
    "bizCode":"WhiteCard",
    "productLevel": "ADVANCED"
}'

Request Url

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

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

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

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

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

https://vn-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-ekyc-verification-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 H5 Identity 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 Integration(H5).
failReturnUrl	`string` The target URL that the frontend jumps to after the user fails to complete the H5 Identity 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 Integration(H5).
callbackUrl	`Deprecated`, please use Webhook instead. `string`[Optional] The target URL to notify the caller after the H5 Identity Verification result is all completed (include Id forgery result). 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.
bizId	`string` The unique business id to identify the business transaction that triggered this Identity Verification processing, such as order id.
userId	`string` The unique userId to identify the user who is performing the Identity Verification.
region	`string` The region of the service support. 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 API Language from user's browser settings Default language (`en`)
prefersColorScheme	`string` [Optional] default "light". Refer to prefersColorScheme.
docType	`string` [Optional] Suggests the document type that expected the user to provide.
ignoreFailWhenJump	`bool` [Optional] default to false. Refer to Frontend Integration(H5)
bizCode	`string` [Optional] The business type of the user. max size of the length is 32. only support characters a-zA-z0-9
iframeEnabled	`bool` [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 example 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` Required. The productLevel that satisfies 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
oldSignatureId	`string` [Optional] Used when upgrading from the DV (Document Verification) product to the IDV (Identity Verification) product. The system retrieves and reuses the information previously submitted in the DV process based on the provided oldSignatureId, ensuring continuity and a smoother user experience during the IDV flow. If this field is not provided, the IDV process will proceed independently.

URL Requirements

returnUrl and failReturnUrl use the same validation rules. You can pass a standard web address such as https://example.com/callback or a custom scheme such as myapp://callback/success or alipays://platformapi/startapp?id=1.

Use a URL that:

is not empty
does not contain control characters such as line breaks, carriage returns, tabs, or null bytes
can be parsed as a valid URI
uses a scheme that starts with a letter and then contains only letters, numbers, +, ., or -
does not use blocked schemes such as javascript, data, file, about, blob, or intent
includes a host in the format scheme://host/...

The following values are rejected:

javascript:alert(1)
myapp:
myapp://
https://host/\npath

If you use a custom scheme, register it in your app before starting the verification flow so the redirect can return to your app successfully.

Support Global Passport

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	Description
STANDARD	Basic compliance / High coverage rate / Acceptable accuracy
ADVANCED	Medium compliance / High pass rate / High accuracy
PRO	Strong compliance / Enhanced 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	H5 Document Verification 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 H5 IDV result
	`url` Get H5 URL that for user to go through the process. Will expire in 3600 seconds. Refer to Frontend Integration(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
	Face image is empty
	Prefers color scheme is wrong
	Face image base64 decode error
	Region is wrong
	Face quality is too low of the uploaded picture.
	No Face detected from the uploaded picture.
	Product level is wrong
	oldSignatureId does not exist
	oldSignatureId does not belong to document verification
	The associated DV verification failed
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"
}