Back-end Integration

Notes : Please first check the Glossary for basic information about ADVANCE API.

Generate URL API

Call this API to generate an IDV link , which is the IDV process page.

Request Example:

curl -X POST  \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: application/json" \
-d '{"returnUrl": "https://www.example.com",
"failReturnUrl":"https://www.example.com/fail",
"userId":"8e44f0089b076e18a718eb9ca3d94674",
"region":"IDN"}' \ 
"https://api.advance.ai/intl/openapi/face-identity/h5-idv/v1/generate-url"

Request Url

https://api.advance.ai/intl/openapi/face-identity/h5-idv/v1/generate-url
POST (application/json)
Notes:

If your test/official environment is in China, please request the service via VPN to avoid packet loss, service timeout and other problems

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 of the web page jump after successfully completing the H5 Document Verification
failReturnUrl	`string` The target URL of the web page jump after the H5 Document Verification fails to obtain OCR results
region	`string` The region of the service support, format please refer to ISO ALPHA-3 Country Code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
userId	`string`[Optional] The unique userId to identify the user who is performing the Document Verification

supported regions are:

Region	Corresponding Country
IDN	Indonesia

Response Description

Parameter	Description
code	H5 Document Verification Status Code
transactionId	The request id, the max length is 64
pricingStrategy	Whether the request will be charged, enum type: FREE, PAY
message	Status Code Explanation
data	`signatureId` signatureId which can use it to get the H5 IDV result
	`url` Get H5 IDV URL(this URL is valid in 3600 seconds.)
	`expiredTime` Expiration timestamp
extra	Extra response info (Exception Message)

Response Code

Status Code	Message
SUCCESS	`free` OK
PARAMETER_ERROR	`free` Parameter error,please check you input.
	`free` Parameter should not be empty
	`free` Invalid returnUrl, please check your returnUrl
	`free` Region is wrong
ERROR	`free` Server error

Response Examples

SUCCESS Response

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "signatureId": "ed8b21c0c87ad617",
        "url": "https://h5.advance.ai/h5-idv/?token=eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJoNV9saXZlbmVzcyIsInN1YiI6IntcImN1c3RvbWVySWRcIjozMTUwMjk4LFwiYWNjb3VudElkXCI6MzE1MDI5OSxcIl90aW1lc3RhbXBcIjoxNzA4NTA5ODk5OTI4LFwiX3V1aWRcIjpcIjFmYzEzOWExMTY1YjRjMTBiY2U4MDFkM2RkMjRhYzI4XCJ9IiwiYXVkIjoiV0VCIiwiaWF0IjoxNzA4NTA5ODk5LCJleHAiOjE3MDg1MTM0OTl9.VKpPl8fDtdhD2y6Y2VwUYOdlnJKusRrDtmfw4FY6lq2kbStk0J45VdchdEHl4oa9SZq9_b9hYBJ1KzCSegAglA&signatureId=ed8b21c0c87ad617",
        "expiredTime":1642580192430
    },
    "extra": null,
    "transactionId": "ed8b21c0c87ad617",
    "pricingStrategy": "FREE"
}

REGION_WRONG Response

{
    "code":"REGION_WRONG",
    "message":"Region is wrong",
    "data":null,
    "extra":null,
    "transactionId":"0f74aeb4dd3f1d48",
    "pricingStrategy":"FREE"
}

PARAMETER_ERROR Response

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter error,please check you 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"
}

Get Result API

After the Document Verification process is done on the user side, you can request the IDV result by calling the Get Result API.

Request Example:

curl -X POST  \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: application/json" \
-d '{"signatureId": "f302f5d2454a85c2"}' \
"https://api.advance.ai/intl/openapi/face-identity/h5-idv/v1/get-result"

Request Url

https://api.advance.ai/intl/openapi/face-identity/h5-idv/v1/get-result
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
signatureId	`string` signatureId which can use it to get the H5 IDV result

Response Description

Parameter	Description
code	H5 Document Verification Status Code
transactionId	The request id, the max length is 64
pricingStrategy	Whether the request will be charged, enum type: FREE, PAY
message	Status Code Explanation
data	image : the link of the full image captured to facilitate easier human review. This link will be expired in 1 day; if the link is expired ,you need to re query this endpoint to get a new link.
	croppedImage : the image is cropped to the edges of the document. The image link will expire in 24 hours. If the link has expired, you need to re-query this endpoint to obtain a new link.
	imageType : indicate that image is scanned or manually uploaded, enum type:SCAN, MANUAL
	ocrCode: the ocr status code of image
	ocrResult: the ocr result of image
	idvCode: the idv status code of image
	idvResult: the idv result of image
extra	Extra response info (Exception Message)

Note：

The difference between image and croppedImage can be better illustrated in the below example:
You can enable the video feature based on your requirement of verification standards.
The user experience may be affected if the video feature is enabled, since it takes time to upload the video.

Response Code

Status Code	Message
SUCCESS	OK
SIGNATURE_NOT_EXIST	This signatureId is not exist.
ERROR	Server error.

Note：

There will be image (link) and image type returned in the data of JSON response body for response code SUCCESS
Please remember to add a handler for the Status Codes in the Glossary as well

idvCode

Value	Description
SUCCESS	Document Verification is successful.
LOW_QUALITY_IMAGE	Lower quality images, please make sure that the content of the shot is visible and readable.
FORGERY_DETECTED	The id card is considered forged, check idvResult.forgeryLabels for reason.
CARD_NOT_FOUND	No documents detected.
TOO_MANY_CARDS	Multiple documents detected, use a single one.
NO_SUPPORTED_CARD	Please use KTP documents.
INCOMPLETED_CARD	Please take a full photo of your documents.
TOO_SMALL_CARD	Please shoot close to the documents.
ERROR	Document Verification Server error.

idvResult

Field	Description
isLowQuality	Indicates if the image is considered low quality.
forgeryLabels	The list of reasons why the id card is considered forged. If empty ,the id card is not forged. possible values (enum): - retake - colorPhotocopied - cutoffCorner - pastedPhoto - b&wPhotocopied - modifiedNIK - oldKTP

ocrCode

Value	Description
SUCCESS	OCR is successful.
OCR_NO_RESULT	OCR is completed but there is no result.
ERROR	OCR Server error.

Note：

Only when idvCode is SUCCESS or FORGERY_DETECTED, ocrCode will have value; otherwise ocrCode will always return null.
When idvCode is FORGERY_DETECTED , idvResult.forgeryLabels shows the reason.
When idvCode is LOW_QUALITY_IMAGE , idvResult.qualityLabels shows the reason.

ocrResult

Field	Description
idNumber	`string`,ID Number (NIK) of the Person in the KTP, null if parsed failed.
name	`string`,Name of the person in the KTP, null if parsed failed.
bloodType	`string`, Blood type of the person, null if parsed failed.
religion	`string`, Religion of the person, null if parsed failed.
gender	`string`, Gender of the person, null if parsed failed.
birthPlaceBirthday	`string`, Place and date of birth of the person, null if parsed failed. format is "Place,, DD-MM-YYYY"
province	`string`, Province of the person’s residence, null if parsed failed.
city	`string`, City of the person’s residence, null if parsed failed.
district	`string`, District of the person’s residence, null if parsed failed.
village	`string`, Village of the person’s residence, null if parsed failed.
rtrw	`string`, RT/RW of the person’ residence, null if parsed failed.
occupation	`string`, Occupation of the person, null if parsed failed.
expiryDate	`string`, Expiry Date of the person’s KTP, null if parsed failed.
nationality	`string`, Nationality of the person, null if parsed failed.
maritalStatus	`string`, Marital status of the person, null if parsed failed.
address	`string`, Detailed Address of the person’s residence, null if parsed failed.
placeOfBirth	`string`, Place of birth of the person, null if parsed failed.
birthday	`string`, Birthday of the person , null if parsed failed. date format is "YYYY/MM/DD"

Note：

For every field, the original text on the KTP card is returned if parsed successfully.

Response Examples

SUCCESS Response

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "image": "https://stg-guardian-cv.oss-ap-southeast-5.aliyuncs.com/h5_iqa/h5_iqa_3150298_3150299_1708509491998_2a91fa20503307e3_v1_front_MANUAL.png?Expires=1708657481&OSSAccessKeyId=LTAI4G9ERfJA1Em5gfCFS191&Signature=ioMc4tH%2Bp8lZuuqlLcPKBbaBaAg%3D",
       	"croppedImage": "https://stg-guardian-cv.oss-ap-southeast-5.aliyuncs.com/h5_iqa/h5_iqa_3150298_3150299_1718624444603_f8ed4b26b17d8334_v1_processed.png?Expires=1722055502&OSSAccessKeyId=LTAI4GEzM3cQKRSSukxGk76L&Signature=yO6XT7NNH6LjqS0kHRuF33R5kOk%3D",
      	"imageType": "SCAN",
        "idvCode": "SUCCESS",
        "idvResult": {
            "forgeryLabels":["screenshot", "scan"],
            "isLowQuality": true,
            "qualityLabels":["blur", "dim"]
        },
        "ocrCode": "SUCCESS",
        "ocrResult": {
            "idNumber":"33******02",
            "name":"R**A M**H A**H,",
            "bloodType":"O",
            "religion":"ISLAM",
            "gender":"PEREMPUAN",
            "birthPlaceBirthday":"SE M**N, 01-06-1989",
            "province":"J**A T**H",
            "city":"K**A S**G",
            "district":"N**N",
            "village":"W**I",
            "rtrw":"011/002",
            "occupation":"M**S R**H T**A",
            "expiryDate":"S**R H**P",
            "nationality":"WNI",
            "maritalStatus":"K**N",
            "address":"JL. G**G J**I T**R R**A",
            "placeOfBirth":"SE M**N",
            "birthday":"1989/06/01"
          }
    },
    "extra": null,
    "transactionId": "d3fde1547eeaf226",
    "pricingStrategy": "FREE"
}

SIGNATURE_NOT_EXIST Response

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

ERROR Response

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

Token Authentication API

This is the API for getting the Access Token.

Request Url

https://api.advance.ai/openapi/auth/ticket/v1/generate-token
POST (application/json)

Request Parameters

Parameter	Description
accessKey	`string` the accessKey
timestamp	`string` 13-digit-long timestamp
signature	`string` Combined accessKey, secretKey and timestamp, encrypted by SHA256. eg. accessKey: sampleaccesskey secretKey: samplesecretkey timestamp: 1665993522952 Combined: sampleaccesskeysamplesecretkey1665993522952 Encrypted based on the combined: 02209bbeaf0d0a3dd587f6a1ba22f84c98d142e3b545e77db7e4906ca56349f5
periodSecond	`string` optional Validity period defaults to 3600 seconds, minimum 60 seconds, maximum 86400 seconds. Unit is seconds

Note:

You can find accessKey, secretKey on the Websaas Platform -> Account -> Account Management
The timestamp in the “signature” must be consistent with parameter timestamp
Please remember to re-obtain a new valid token to do the authentication for the open APIs when the previous one is expired

Code Sample

curl -X POST \
-H "Content-Type: application/json" \
-d '{"accessKey":"22**70b","signature":"f786441e7b3d95f*****853a5a244f9522","timestamp":1648785145789,"periodSecond":120}' \
"https://api.advance.ai/openapi/auth/ticket/v1/generate-token"

Response Description

Parameter	Description
code	Response Status Code
message	Message returned from server
data	`token` AccessToken
	`expiredTime` Expiration timestamp
extra	Extra response info such as exception message
transactionId	the request id, the max length is 64
pricingStrategy	whether the request will be charged, enum type: FREE, PAY

Response Code

Status Code	Message
SUCCESS	OK
PARAMETER_ERROR	Timestamp error
	Parameter should not be empty
	Signature error
ACCOUNT_DISABLED	Account Disabled
CLIENT_ERROR	HTTP 400 - Bad Request

Response Examples

SUCCESS Response

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
    "token":"eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJoNV9saXZlbmVzcyIsInN1YiI6IntcImN1c3RvbWVySWRcIjo1NTAwMDI4MixcImFjY291bnRJZFwiOjU1MDAwMjg0LFwicmVhbElwXCI6XCI0NS4yNTEuMTA3LjExMVwifSIsImF1ZCI6IldFQiIsImlhdCI6MTY0MjU4MDA3MiwiZXhwIjoxNjQyNTgwMTkyfQ.HmIDcuSW67A59x7bnumjGp0Wdcz-FmoDrnHF1YGui6wVPfulLn4Izonay5LQnySgph1dbyC1E0LtifS-BJo8VA",
    "expiredTime":1642580192430
    },
    "extra":null,
    "transactionId":"6c2c50a3049ce67e",
    "pricingStrategy":"FREE"
}

PARAMETER_ERROR Response

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter should not be empty",
    "data":null,
    "extra":null,
    "transactionId":"040e769e38f87e3e",
    "pricingStrategy":"FREE"
 }

{
    "code":"PARAMETER_ERROR",
    "message":"Timestamp error",
    "data":null,
    "extra":null,
    "transactionId":"a9c2a6c199ad5db5",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Signature error",
    "data":null,
    "extra":null,
    "transactionId":"00b05cb9cf6f0fed",
    "pricingStrategy":"FREE"
}

ACCOUNT_DISABLED Response

{
    "code":"ACCOUNT_DISABLED",
    "message":"Account Disabled",
    "data":null,
    "extra":null,
    "transactionId":"5e00fded1272490e",
    "pricingStrategy":"FREE"
}

CLIENT_ERROR Response

{
    "code":"CLIENT_ERROR",
    "message":"HTTP 400 - Bad Request",
    "data":null,
    "extra":null,
    "transactionId":"bd5d5653c45d4c6e",
    "pricingStrategy":"FREE"
 }