Document API

Call this API to do a Document Verification without AAI's Frontend.

Request Example:

Bash

curl -X POST \
  https://ph-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/api/document \
  -H 'Content-Type: application/json' \
  -H 'X-ACCESS-TOKEN:{Your Access Token}' \
  -d '{
"callbackUrl": "https://www.example.com/callback",
"bizId": "7ac66c0f148de9519b8bd264312c4d64", 
"userId":"8e44f0089b076e18a718eb9ca3d94674",
"region":"THA",
"language": "en-US",
"docType": "TH-ID-N",
"solutionCode": "05",
"frontImageBase64":"YWJjZGVmZw==", // use real image base64 string
"noForgeryDetect": false,
"bizCode":"WhiteCard"
}'

Request Url

Thailand

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

Indonesia

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

Singapore

https://sg-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/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	Description
callbackUrl	string [Optional] The target URL to notify the caller after the H5 Identity Verification finished. 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[Optional] 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 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).
language	string[Optional] The language used by the frontend. Refer to HTTP Accept-Language.
solutionCode	string, [Optional] default to "05". Refer to solutionCode.
docType	string refer to Region and DocType.
frontImageBase64	string The front image of the document. Please provide either frontImageBase64 or frontImageUrl. Refer to Image Requriements.
frontImageUrl	string The front image of the document. Should not expire in 1 hour. Please provide either frontImageBase64 or frontImageUrl. Refer to Image Requriements .
backImageBase64	string The back image of the document. [Required] when the docType is two-sides. Please provide either backImageBase64 or backImageBase64. Refer to Image Requriements .
backImageUrl	string The back image of the document. Should be valid for at least 1 hour. Please provide either backImageBase64 or backImageBase64. Refer to Image Requriements .
bizCode	string [Optional ] The business type of the user. max size of the length is 32. only support characters a-zA-z0-9

solutionCode

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

Supported Values	Product Form
05	DOCUMENT(API)

Region and DocType

Region	Country	DocType	DocType Explained
THA	Thailand	TH-ID-N	Thailand National ID ( two-sides)
		TH-ID-PINK (will support later)	Thailand Pink ID (two-sides)
		TH-PP-N	Thailand Passport
		TH-DL-N	Thailand Driver’s License (two-sides)
IDN	Indonesia	ID-ID-KTP	Indonesia National ID
		ID-PP-N	Indonesia Passport

Response Description

the response data structure is similar with Get Result API's Response.

Parameter	Description
code	Response's Status Code
transactionId	The request id, the max length is 64
pricingStrategy	Deprecated, Always return FREE
message	Status Code Explanation
data	object : the business result of Identity Verification
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
	Solution code 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.
SIGNATURE_NOT_EXIST	This signatureId is not exist.
ERROR	Server error.

Response.data

Field	Description
signatureId	string, the signatureId of this identity verification transaction.
idvResult	string, The result code of this identity verification transaction.
errorCode	string, The fail reason when eckyResult is fail
docDetail	object, The document verification result details. this field will always be null when solutionCode in ["04"]. Refer to DocDetail.
feeDetail	list, the charging details. Refer to FeeDetail

idvResult

idvResult is the result code of the identity verification, the value is same with DocDetail.orcResult.

Value	Description
PASS	the user passed the identity verification check.
FAIL	the user failed the identity verification check.

errorCode

Response.data.idvResult	Value	Description
PASS	SUCCESS	The user passed the identity verification.
FAIL	NO_FACE_DETECTED	No face detected on the front image of the document.
	CARD_INFO_MISMATCH	The front part and the back part of the two-side document do not match with each other.
	ID_FORGERY_DETECTED	The document ( only the front part if the document is two-side) is forgery.
	NO_SUPPORTED_CARD	The card type detected from the document image is not supported.
	CARD_TYPE_MISMATCH	The card type detected from the document image doesn't match with the docType from the Generate URL API
	CARD_LOW_QUALITY_IMAGE	The document images are too poor to do identity verification.
	INCOMPLETED_CARD	The card is not completed in the document images.
	TOO_MANY_CARDS	More than one cards were detected.
	CARD_NOT_FOUND	Can't detect card from the document image.
	OCR_NO_RESULT	Can't extract ocr result from the docImages
	PARAMETER_ERROR	the data submitted by our frontend is not valid. this may indicates a frontend bug.
	USER_TIMEOUT	User did not complete the operation within the specified time（1 hour）
	ERROR	Error during processing in our backend. this may indicates a backend bug.

Response Examples

SUCCESS

pass

{
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "signatureId":"f302f5d2454a85c2",
    "idvResult": "PASS",
    "errorCode": "SUCCESS",
    "docDetail": {
      "ocrResult": "PASS",
      "docFrontImage": "https://abc.com/idFrontImage.jpg",
      "docBackImage": "https://abc.com/idBackImage.jpg",
      "ocrInfo": {
        "front": {
          "gender": "PEREMPUAN",
          "name": "****** ******",
          "address": "****** ****** ****** ******",
          "idNumber": "************",
          "religion": "",
          "birthday": "1977/10/28",
          "citizen": "MYS"
        },
        "back": {
          "secondaryIdNumber": "************"
        }
      },
      "qualityLabels": {
        "front": [],
        "back": []
      },
      "forgeryLabels": [
        "photocopy"
      ],
      "eventDetails": [
          {
              "event": "BE_DOCUMENT",
              "result": "PASS",
              "createTimestmap": 1665993522952
          }
      ]
    },
     feeDetail: [
  				{
    				"name": "SOLUTION",
    				"type": "SOLUTION"
				}
		]
  },
  "extra": null,
  "transactionId": "d3fde1547eeaf226",
  "pricingStrategy": "FREE"
}

not supported card

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
      "signatureId":"f302f5d2454a85c2",
      "idvResult":"FAIL",
      "errorCode":"NOT_SUPPORTED_CARD",
      "faceDetail": {
         "faceResult": null,
        "faceImageFar": null,
        "faceImageNear": null,
				"auditImageUrl": null,
				"faceLivenessScore": null,
        "faceSimilarityScore": null
       
      },
      "docDetail":  {
        "docResult": null,
        "docFrontImage": null,
        "docBackImage": null,
				"ocrInfo": null,
        "qualityLabels": null,
        "forgeryLabels": null
      },
     feeDetail: [
  				{
    				"name": "SOLUTION",
    				"type": "SOLUTION"
				}
		  ]
    },
    "extra": null,
    "transactionId": "d3fde1547eeaf226",
    "pricingStrategy": "FREE"
}

partial result

{
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "idvResult": null, // still in processing
    "errorCode": null,
    "docDetail": {
      "ocrResult": "PASS",
      "docFrontImage": "https://abc.com/idFrontImage.jpg",
      "docBackImage": "https://abc.com/idBackImage.jpg",
      "ocrInfo": {
        "front": {
          "birthday": "OCTOBER 28,1977",
          "name": "**************",
          "birthdayParsed": "1977/10/28",
          "idNumber": "09-*******-*"
        },
        "back": null
      },
      "qualityLabels": {
        "front": [],
        "back": []
      },
      "forgeryLabels": null, // in processing
      "eventDetails": [
          {
              "event": "BE_DOCUMENT",
              "result": "PASS",
              "createTimestmap": 1665993522952
          }
      ]
    },
     feeDetail: [
  				{
    				"name": "SOLUTION",
    				"type": "SOLUTION"
				}
		]
  },
  "extra": null,
  "transactionId": "d3fde1547eeaf226",
  "pricingStrategy": "FREE"
}

SIGNATURE_NOT_EXIST

JSON

{
    "code":"SIGNATURE_NOT_EXIST",
    "message":"This signatureId is not exist",
    "data":null,
    "extra":null,
    "transactionId":"b6d722f7e9f553ae",
    "pricingStrategy":"FREE"
}

ERROR