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

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

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

Updated 9 months ago

Did this page help you?