Call this API to generate an Identity Verification Solution link.

Request Example:

curl -X POST \
  https://ph-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-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",
"ttlSeconds": 7200,
"docType": "PH-ID-SSS",
"solutionCode": "01",
"prefersColorScheme":"light",
"ignoreFailWhenJump": false,
"bizCode":"WhiteCard"
}'

Request Url

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

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

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

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

https://sg-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-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	`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. Required when solutionCode is 06
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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3))
language	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).
solutionCode	`string` [Optional ] default 01. Refer to solutionCode.
ttlSeconds	`integer` [Optional] Validity period of the generated H5 URL. Defaults to 3600 seconds, minimum 10 seconds, maximum 604800 seconds. Unit is seconds.
prefersColorScheme	`string` [Optional ] default "light". Refer to prefersColorScheme.
docType	`string` The document type that requires the user to provide. [Required] when solutionCode in ["01","02","03"]. Refer to Supported Regions & DocTypes
docImageWithFaceBase64	`string` Used for Face Comparison (with the face image collected in liveness detection) later. Only used for solutionCode in ["04"]. Provide either docImageWithFaceBase64 or docImageWithFaceUrl. Refer to Image Requirements.
docImageWithFaceUrl	`string` Used for Face Comparison (with the face image collected in liveness detection) later.. The url should be valid for at least 1 hour. Only used when solutionCode in ["04"]. Provide either of docImageWithFaceBase64 or docImageWithFaceUrl. Refer to Image Requirements .
frontImageBase64	`string` The front image of the document. Only used when solutionCode in ["10"]. Please provide either frontImageBase64 or frontImageUrl. Refer to Image Requirements.
frontImageUrl	`string` The front image of the document. Should be valid for at least 1 hour. Only used when solutionCode in ["10"]. Please provide either frontImageBase64 or frontImageUrl. Refer to Image Requirements .
backImageBase64	`string` The back image of the document. [Required] when the docType is two-sides. Only used when solutionCode in ["10"]. Please provide either backImageBase64 or backImageUrl. Refer to Image Requirements .
backImageUrl	`string` The back image of the document. Should be valid for at least 1 hour. Only used when solutionCode in ["10"]. Please provide either backImageBase64 or backImageUrl. Refer to Image Requirements .
ignoreFailWhenJump	`bool` [Optional] default to false.Refer to Frontend Integration(H5) Error Handling
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.

Support Global Passport

solutionCode

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

Supported Values	Product Form
01	DOCUMENT(H5) + FACE(H5)
02	DOCUMENT(H5)
03	DOCUMENT Lite(H5)
04	FACE(H5)
06	DOCUMENT(H5) + FACE(H5)+FACE_SEARCH(BACK_GROUND)+MANUAL_AUDIT(BACK_GROUND)
10	DOCUMENT(API) + FACE(H5)

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 Identity 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 the H5 URL for the user to go through the process. Will expire in `ttlSeconds` seconds. If `ttlSeconds` is not provided, the URL will expire in 3600 seconds. Refer to Frontend Integration(H5)
	`expiredTime` Expiration timestamp of the H5 URL, in milliseconds. After the URL expires, generate a new URL to restart the verification.
extra	Extra response info (Exception Message)

Response Code

Status Code	Message
SUCCESS	OK
PARAMETER_ERROR	Parameter error, please check your input.
	Parameter should not be empty
	Invalid returnUrl, please check your returnUrl
	Solution code is wrong
	Face image is empty
	Prefers color scheme is wrong
	Face image base64 decode error
	Region is wrong
	Invalid image format, image format should be one of jpeg/jpg/png, and request content type should be image/jpeg or image/png
	Invalid image size, max image size should be less than 2M, and image dimension should be between 256 256 and 4096 4096
	The image download has exceeded 3 seconds. Please check the network and operate again.
	Face quality is too low of the uploaded picture.
	No Face detected from the uploaded picture. (only possible when solutionCode in["10"].)
	The image download has exceeded 3 seconds. Please check the network and operate again. (only possible when solutionCode in["10"].)
	No image found. (only possible when solutionCode in["10"].)
NO_FACE_DETECTED	No face detected on the front image of the document. (only possible when solutionCode in["10"].)
CARD_INFO_MISMATCH	The front part and the back part of the two-side document do not match with each other. (only possible when solutionCode in["10"].)
NO_SUPPORTED_CARD	The card type detected from the document image is not supported. (only possible when solutionCode in["10"].)
CARD_TYPE_MISMATCH	The card type detected from the document image doesn't match with the docType from the Generate URL API. (only possible when solutionCode in["10"].)
TOO_MANY_CARDS	More than one cards were detected. (only possible when solutionCode in["10"].)
OCR_NO_RESULT	Can't extract ocr result from the docImages. (only possible when solutionCode in["10"].)
OCR_REQUIRED_FIELDS_MISSING	One or more required fields are missing from the OCR result. (only possible when solutionCode in["10"].)
	ttlSeconds is below the minimum of 10 seconds
	ttlSeconds exceeds the maximum of 604800 seconds
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 your 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"
}