Document API V2

Call this API to submit a Document Verification request asynchronously. After the request is accepted, the API immediately returns an acknowledgement (ACK) without any OCR, anti-forgery, or final verification result. The verification runs in the background. Use Get Result API to poll for the result, or configure Webhook to receive a notification when processing is complete.

Document API V1 has been discontinued and is no longer available in this documentation. Contact your account representative if you require the legacy V1 documentation.

Request Example:

curl -X POST \
  https://sg-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v2/api/document \
  -H 'Content-Type: application/json' \
  -H 'X-ACCESS-TOKEN: {Your Access Token}' \
  -d '{
    "bizId": "7ac66c0f148de9519b8bd264312c4d64",
    "userId": "8e44f0089b076e18a718eb9ca3d94674",
    "region": "THA",
    "docType": "TH-ID-N",
    "productLevel": "ADVANCED",
    "frontImageBase64": "<REAL_IMAGE_BASE64>",
    "bizCode": "WhiteCard"
  }'

Request Url

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

https://sg-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v2/api/document
POST (application/json)

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

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

https://my-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v2/api/document
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	Presence	Description
callbackUrl	Optional	`string`, deprecated. Use Webhook instead. The target URL to notify after verification finishes. Maximum length: 2048 characters. Refer to Callback Notification.
bizId	Required	`string`, the unique business ID of the transaction that triggered the verification, such as an order ID. Maximum length: 99 characters.
userId	Optional	`string`, the unique ID of the user performing the verification.
region	Required	`string`, the ISO 3166-1 alpha-3 code of the document-issuing country or region.
docType	Optional	`string`, the expected document type. Refer to Supported Regions & DocTypes.
bizCode	Optional	`string`, the customer's business classification. Maximum length: 32 characters; only `A-Z`, `a-z`, and `0-9` are supported.
productLevel	Required	`string`, the Document Verification service tier. Refer to ProductLevel. Missing, unsupported, or invalid values return `PARAMETER_ERROR` synchronously.
frontImageBase64	Conditional	`string`, the Base64-encoded front image. Provide exactly one of `frontImageBase64` and `frontImageUrl`. Refer to Image Requirements.
frontImageUrl	Conditional	`string`, the front-image URL. It must remain valid for at least one hour. Provide exactly one of `frontImageBase64` and `frontImageUrl`. Refer to Image Requirements.
backImageBase64	Conditional	`string`, the Base64-encoded back image. Required for a two-sided document. Provide exactly one of `backImageBase64` and `backImageUrl`. Refer to Image Requirements.
backImageUrl	Conditional	`string`, the back-image URL. Required for a two-sided document and must remain valid for at least one hour. Provide exactly one of `backImageBase64` and `backImageUrl`. Refer to Image Requirements.
returnImageType	Optional	`enum`, defaults to `URL`. Determines how image fields are returned by Get Result API. Refer to ReturnImageType.

ProductLevel

The productLevel defines the tier of the Document Verification service. Consult your sales representative to determine the tier granted to your account.

Supported Values	Description
STANDARD	Basic compliance / High coverage rate / Acceptable accuracy
ADVANCED	Medium compliance / High pass rate / High accuracy
PRO	Strong compliance / Enhanced accuracy

ReturnImageType

Supported Values	Description
URL	Image fields in the Get Result API response are returned as URLs.
BASE64	Image fields in the Get Result API response are Base64-encoded.

Response Description

This is an acknowledgement (ACK) response only. A successful ACK confirms that the request was accepted for background processing. It does not contain any OCR, anti-forgery, or final verification result. Use Get Result API to retrieve the result, or configure Webhook to receive a completion notification.

Parameter	Description
code	Response status code
transactionId	The request id, the max length is 64
pricingStrategy	`Deprecated`, Always return `FREE`
message	Status Code Explanation
data	`object`, the ACK result. See Response.data.
extra	Additional response information

Response.code

Status Code	Message
SUCCESS	OK
PARAMETER_ERROR	Parameter error. Check the request parameters.
	Parameter should not be empty
	Product level is wrong
	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.
	No image found
	Image type is not exist
ERROR	Server error.

Response.data

Field	Description
signatureId	`string`, the signature ID of this verification transaction. Use it to call Get Result API.

Success response: Only signatureId is returned in data. Fields such as overallResult, idvResult, errorCode, docDetail, and countryCodeIso3 are available from Get Result API, not from this ACK response.

Synchronous failure: If validation fails, for example because an image is missing or a parameter is invalid, the top-level transactionId is still populated but data is null. Background verification is not started. Fix the request and submit it again.

Response Examples

SUCCESS (ACK)

{
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "signatureId": "f302f5d2454a85c2"
  },
  "extra": null,
  "transactionId": "f302f5d2454a85c2",
  "pricingStrategy": "FREE"
}

PARAMETER_ERROR (e.g. product level is wrong)

{
  "code": "PARAMETER_ERROR",
  "message": "Product level is wrong",
  "data": null,
  "extra": null,
  "transactionId": "d3fde1547eeaf226",
  "pricingStrategy": "FREE"
}

PARAMETER_ERROR (e.g. no image found)

{
  "code": "PARAMETER_ERROR",
  "message": "No image found",
  "data": null,
  "extra": null,
  "transactionId": "d3fde1547eeaf226",
  "pricingStrategy": "FREE"
}

ERROR

{
  "code": "ERROR",
  "message": "Server error.",
  "data": null,
  "extra": null,
  "transactionId": "d3fde1547eeaf226",
  "pricingStrategy": "FREE"
}

Next Step

After receiving a SUCCESS ACK, call Get Result API with the returned signatureId. Document API V2 submissions continue to use the existing /v1/get-result endpoint. An empty overallResult or idvResult means processing is still in progress. PASS, FAIL, or INCOMPLETE indicates a final result; see errorCode and docDetail for details.

Alternatively, configure Webhook to receive a COMPLETED notification when processing finishes.