Use this API to create a Non-Document Verification session and obtain a link for the user. For Thailand ThaID, the link opens the authorization flow for the ThaID app.

Request Example:

curl -X POST \
  https://sg-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-non-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",
    "bizId": "7ac66c0f148de9519b8bd264312c4d64", 
    "userId":"8e44f0089b076e18a718eb9ca3d94674",
    "region":"IDN",
    "numberType": "NIK",
    "language": "en-US",
    "ttlSeconds": 7200,
    "prefersColorScheme":"light",
    "ignoreFailWhenJump": false,
    "bizCode":"WhiteCard",
    "numberValue":"22841958472"
}'

Request Url

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

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

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

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

https://my-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/generate-non-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 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 Integration(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 Integration(H5)
callbackUrl	`Deprecated`, please use Webhook instead. `string` [Optional] The target URL to notify the caller after the 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 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
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). These parameters control the ADVANCE.AI H5 experience and do not configure the ThaID authorization flow.
ttlSeconds	`integer` [Optional] Validity period of the generated H5 URL. Defaults to 3600 seconds, minimum 10 seconds, maximum 604800 seconds. Unit is seconds. For `THAIEID`, omit this parameter. It does not change the authorization link's validity. If supplied, it is still validated: a value outside 10–604800 returns `PARAMETER_ERROR`.
prefersColorScheme	`string` [Optional ] default "light". Refer to prefersColorScheme. These parameters control the ADVANCE.AI H5 experience and do not configure the ThaID authorization flow.
numberType	`string`. The verification type for the selected `region`. See Supported Regions & NumberTypes.
scope	`string[]`, optional for `THAIEID`. Selects which identity attributes to request. If omitted or `null`, defaults to `["idNumber", "firstName", "lastName", "birthday"]`. See Thailand ThaID authorization.
bizCode	`string` [Optional ] The business type of the user. max size of the length is 32. only support characters a-zA-z0-9
ignoreFailWhenJump	`bool` [Optional] default to false.Refer to Frontend Integration(H5) These parameters control the ADVANCE.AI H5 experience and do not configure the ThaID authorization flow.
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. The ADVANCE.AI H5 iframe integration does not apply to `THAIEID`.
livenessType	`string` [Optional ] default to `DISTANT_NEAR`. Determine how the user goes through the liveness capture. Refer to Liveness Type List. Ignored when `numberType` = 'PCN' — see Philippines PCN prefill. Ignored for `THAIEID`. This flow does not use ADVANCE.AI liveness capture.
numberValue	`string` [Optional ] Only valid when numberType is not empty. The number you want to check . eg 22841958472. Whether it is required depends on `numberType` — see Input fields by numberType. Not applicable to `THAIEID`. Omit this field.
fullName	`string` [Optional ] Only valid when both numberType and numberValue are not empty. Required when numberType = 'NIK'. See Input fields by numberType.
gender	`string` [Optional ] User gender. Values: `FEMALE` / `MALE` / `OTHER`. For numberType = 'DNI', required when `numberValue` is provided. See Input fields by numberType.
firstName	`string` [Optional ] Personal-information prefill, only valid for `numberType` = 'PCN'. Required together with `lastName` and `birthday` when you prefill personal information instead of `numberValue`. See Philippines PCN prefill.
middleName	`string` [Optional ] Personal-information prefill, only valid for `numberType` = 'PCN'. Optional; used when prefilling personal information instead of `numberValue`. See Philippines PCN prefill.
lastName	`string` [Optional ] Personal-information prefill, only valid for `numberType` = 'PCN'. Required together with `firstName` and `birthday` when you prefill personal information instead of `numberValue`. See Philippines PCN prefill.
suffix	`string` [Optional ] Personal-information prefill, only valid for `numberType` = 'PCN'. Optional name suffix; allowed values are `JR`, `SR`, `I`–`XV` (Roman numerals), case-insensitive. See Philippines PCN prefill.
birthday	`string` [Optional ] Personal-information prefill, only valid for `numberType` = 'PCN'. Required together with `firstName` and `lastName` when you prefill personal information instead of `numberValue`. Format `yyyy/MM/dd`; must be strictly before today. See Philippines PCN prefill.

prefersColorScheme

indicate the theme that AAI's Frontend should use.

Supported Values	explained
light	light theme.
dark	dark theme.

Philippines PCN prefill

For region = PHL and numberType = PCN, you can prefill either the PCN or the holder's personal information. If neither is prefilled, the user enters the PCN or the personal information on the H5 frontend.

Mode	Required at Generate URL	Optional
PCN	`numberValue` (a valid PCN)	—
Personal information	`firstName`, `lastName`, `birthday`	`middleName`, `suffix`

Rules:

birthday format is yyyy/MM/dd and must be strictly before today.
Name fields allow letters, spaces, apostrophes ('), periods (.) and hyphens (-).
suffix, when provided, must be JR, SR, or a Roman numeral from I to XV (case-insensitive).
Do not send a partial personal-information set; it fails with Name is invalid format or a parameter error.
If both numberValue and personal information are sent, numberValue takes precedence.
See numberValue length (PCN) for the accepted PCN formats.
If the upstream identity service is unavailable, Generate URL returns ERROR and no link is generated; call Generate URL again to retry.
livenessType does not apply to PCN: the PCN liveness flow is fixed, and faceDetail.livenessType / faceDetail.livenessFlowCategory always return DISTANT_CLOSE_FLASH in Get Result. A supported value is accepted and has no effect on the PCN flow or on the result; an unsupported value still fails with liveness type not found.

Request Example (personal information prefill):

{
  "returnUrl": "https://www.example.com",
  "failReturnUrl": "https://www.example.com/fail",
  "bizId": "b7c66c0f148de9519b8bd264312c4d64",
  "userId": "u8e44f0089b076e18a718eb9ca3d9467",
  "region": "PHL",
  "numberType": "PCN",
  "firstName": "JUAN",
  "middleName": "SANTOS",
  "lastName": "DELA CRUZ",
  "suffix": "JR",
  "birthday": "1990/05/15",
  "language": "en-US"
}

Thailand ThaID authorization

For region = THA and numberType = THAIEID, the returned link opens the ThaID app authorization flow. This flow does not require an ID number, personal information prefill, a document upload, or ADVANCE.AI liveness capture.

Rules:

returnUrl and failReturnUrl are both used as return destinations for the authorization flow. Use HTTPS URLs as shown below.
A browser redirect does not confirm that a final verification result is available. Save the signatureId and call Get Result API for the outcome.
scope selects the identity attributes to request. Omit it to use ["idNumber", "firstName", "lastName", "birthday"].
scope must be a non-empty array of case-sensitive names. Surrounding whitespace is trimmed and duplicates are removed. An empty array, a blank or null entry, or an unrecognized name returns PARAMETER_ERROR.
Supported scope values: idNumber, fullName, fullNameEn, birthday, address, firstName, middleName, lastName, firstNameEn, middleNameEn, lastNameEn, gender, smartcardCode, title, titleEn, ial, issueDate, expiryDate, houseAddress. See DocDatabaseDetail for field definitions.
If the authorization link cannot be created, the API returns ERROR and no link is generated; call Generate URL again to retry.

Request Example (Thailand ThaID, with a custom scope):

{
  "returnUrl": "https://www.example.com/verification/return",
  "failReturnUrl": "https://www.example.com/verification/failed",
  "bizId": "order-thaid-001",
  "userId": "user-thaid-001",
  "region": "THA",
  "numberType": "THAIEID",
  "scope": ["idNumber", "firstName", "lastName", "birthday", "issueDate", "expiryDate", "address"]
}

Response Description

Parameter	Description
code	Response Code of this Solution 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` `string`. Link for the user to complete the flow. For ADVANCE.AI H5 flows, the link expires after `ttlSeconds` (default: 3600 seconds). See Frontend Integration (H5). For `THAIEID`, this is a ThaID authorization link with a default validity of 600 seconds (10 minutes).
	`expiredTime` Link expiry as a Unix timestamp in milliseconds. After the link expires, call Generate URL again to start a new verification session.
extra	Extra response info (Exception Message)

Response Code

Status Code	Message
SUCCESS	OK
INVALID_FORMAT	Number is invalid format
	Name is invalid format
PARAMETER_ERROR	Parameter error, please check your input.
	Parameter should not be empty
	Invalid returnUrl, please check your returnUrl
	Solution code is wrong
	Prefers color scheme is wrong
	Number type and country are not match
	Number is invalid format (PCN)
	Name is invalid format (PCN)
	liveness type not found
	Invalid input，please check the format (PCN)
	ttlSeconds is below the minimum of 10 seconds
	ttlSeconds exceeds the maximum of 604800 seconds
	Invalid parameters, scope must be one of idNumber, fullName, fullNameEn, birthday, address, firstName, middleName, lastName, firstNameEn, middleNameEn, lastNameEn, gender, smartcardCode, title, titleEn, ial, issueDate, expiryDate, houseAddress. Thailand ThaID only.
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"
}

SUCCESS (Thailand ThaID)

{
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "signatureId": "8c61234ab90def21",
    "url": "https://www.example.com/thaid-authorization-link",
    "expiredTime": 1794456600000
  },
  "extra": null,
  "transactionId": "ce071a5b29d43f60",
  "pricingStrategy": "FREE"
}

REGION_WRONG

{
    "code":"PARAMETER_ERROR",
    "message":"Number type and country are not match",
    "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"
}