Document API

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

Request Example:

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

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

Request Header Parameters

ParameterDescription
X-ACCESS-TOKENstring 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 ValuesProduct Form
05DOCUMENT(API)

Region and DocType

RegionCountryDocTypeDocType Explained
THAThailandTH-ID-NThailand National ID ( two-sides)
TH-ID-PINK (will support later)Thailand Pink ID (two-sides)
TH-PP-NThailand Passport
TH-DL-NThailand Driver’s License (two-sides)
IDNIndonesiaID-ID-KTPIndonesia National ID
ID-PP-NIndonesia Passport

Response Description

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


ParameterDescription
codeResponse's Status Code
transactionIdThe request id, the max length is 64
pricingStrategyDeprecated, Always return FREE
messageStatus Code Explanation
dataobject : the business result of Identity Verification
extraExtra response info (Exception Message)

Response.code

Status CodeMessage
SUCCESSOK
PARAMETER_ERRORParameter 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_EXISTThis signatureId is not exist.
ERRORServer 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.

ValueDescription
PASSthe user passed the identity verification check.
FAILthe 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

{
  "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"
}
{
    "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"
}
{
  "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

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

ERROR