1. ADVANCE.AI
  2. FAQ
  3. Document Verification

Generate URL API

Avatar
Cheeny Aban
 
Request Example: 


curl -X POST \
  https://ph-api.advance.ai/intl/openapi/identity-risk/
idvs-h5/ekyc/v1/generate-document-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"
}'


Request Url


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

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

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

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

https://sg-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-document-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 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 Verification processing in frontend.
Refer to Frontend Integration(H5)
callbackUrl string [Optional] The target URL to notify the caller after the 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 Verification processing, such as order id.
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 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 The document type that requires the user to provide.
[Required]
Refer to Supported Regions & DocTypes
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.

 
 
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 verification 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
  Solution code is wrong
  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"
}
" class="rm-Markdown markdown-body rm-Markdown markdown-body ng-non-bindable" data-testid="RDMD" style="--font-size: 90%; color: var(--markdown-text); font-family: var(--markdown-font); line-height: var(--markdown-line-height); position: relative; text-size-adjust: 100%; overflow-wrap: break-word; font-size: var(--markdown-font-size, 14px); margin-left: 31px;"

Call this API to generate an Document Verification H5 Frontend link.

Request Example:

 
curl -X POST \ https://ph-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-document-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" }'
 
 
Request Url
 
https://my-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-document-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 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 Verification processing in frontend.
Refer to Frontend Integration(H5)
callbackUrl string [Optional] The target URL to notify the caller after the 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 Verification processing, such as order id.
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 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 The document type that requires the user to provide.
[Required]
Refer to Supported Regions & DocTypes
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.

 
 
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 verification 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
  Solution code is wrong
  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" }

Articles in this section

Was this article helpful?
37 out of 39 found this helpful

Comments

0 comments

Please sign in to leave a comment.