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": "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",
"docType": "PH-ID-SSS",
"prefersColorScheme":"light",
"ignoreFailWhenJump": false,
"bizCode":"WhiteCard",
"productLevel": "STANDARD"
}'

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)

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 user completes the H5 Identity Verification 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 Identity Verification processing in frontend. Refer to Frontend Integration(H5)
callbackUrl	`string` [Optional] The target URL to notify the caller after the H5 Identity Verification 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 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]The languages currently supported by the frontend are: en - English fil - Filipino ms - Malay id - Indonesian th - Thai bn - Bengali Refer to HTTP Accept-Language NOTE: When the user-specified language is not matched, it will fall back sequentially: language by Generate URL API > language by User browser > 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	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` the productLevel that satisfy the client's business needs. Refer to ProductLevel

ProductLevel

the productLevel determine the product form of the Identity Verification , please choose the product form that suits your needs.

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