NAV Navbar
Logo

Global Document Verification

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

There are 3 steps for Global Document Verification.

Code Sample

curl -X POST \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: application/json" \
-d '{"licenseEffectiveSeconds": 600,"applicationId": "appId1,appId2" }' \
"https://api.advance.ai/intl/openapi/face-identity/document-verification/v1/auth-license"

Request Url

https://api.advance.ai/intl/openapi/face-identity/document-verification/v1/auth-license
POST (application/json)

Notes:

Request Header Parameters:

Parameter Description
X-ACCESS-TOKEN string Please Click here to get your access token

Request Parameters:

Parameter Description
licenseEffectiveSeconds int optional The license effective period， default is 600 seconds, the maximum is 86400 seconds
applicationId string optional The list of valid applicationId

URL Example of Success Response:

{
    "code":"SUCCESS",
    "transactionId": "196eb0c777789e58",
    "pricingStrategy": "PAY",
    "message":"OK",
    "data":{
        "license":"jpgEkQQFKD+EXHBmIFLOycYOMkohFVyJzhfq5M0F95pp3EDcLf8Z31e4xqyeyhNXfW......",
        "expireTimestamp": 1603164618149
    },
    "extra":null
}

Example of Access Denied Response:

{
     "code": "ACCESS_DENIED",
     "message": "Access denied",
     "transactionId": "eb0c771967789e58",
     "data": null,
     "extra": null,
     "pricingStrategy": "FREE"
}

Example of Service Disabled Response:

{
     "code": "SERVICE_DISABLED",
     "message": "Service disabled",
     "transactionId": "789196eb0c777e58",
     "data": null,
     "extra": null,
     "pricingStrategy": "FREE"
}

Response Description:

Parameter Description
code Global Document Verification’s license 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 license : Authorization code within validity period
expireTimestamp : Expiration timestamp
extra Extra response info (Exception Message)

Response Code

Status Code Message
ACCESS_DENIED free Access denied
SERVICE_DISABLED free Service disabled

Note: Don’t Forget to add handler for these Status Codes in Glossary as well

SDK Integration

Android

iOS

latest version 1.0.8 - released on 07-05-2022

Query

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

Code Sample

curl -X POST \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: application/json" \
-d '{ "IDVID":"ba959a16-a06c-4b82-ae1f-22452b5bbcf3","resultType":"IMAGE_URL"}' \
"https://api.advance.ai/intl/openapi/face-identity/document-verification/v1/query"

Request URL

https://api.advance.ai/intl/openapi/face-identity/document-verification/v1/query
POST (application/json)

Notes:

Request Header Parameters:

Parameter Description
X-ACCESS-TOKEN string Please Click here to get your access token

Request Parameters:

Parameter Description
IDVID string an identifier from the SDK
resultType string optional the preferred format for the returned image, IMAGE_URL or IMAGE_BASE64. The default will be IMAGE_URL

Notes:

Image URL Example of Success Response:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
        "image":"https://prod-guardian-cv-sg.../global-iqa/.../Global-IQA-SCAN-DOCUMENT_VERIFICATION-FRONT-d187c6c1d58a5fb3.png?Expires=1640863024&...",
        "OCR":{
            "idNumber":"1272034601930001",
            "fullName":"SRI HASIPAH",
            "fullNameLocal":"SRI HASIPAH",
            "expiryDate":"SEUMUR HIDUP",
            "state":"SUMATERA UTARA",
            "city":"KOTA PEMATANGSIANTAR",
            "district":"SIANTAR UTARA",
            "subdistrict":"BARU",
            "fullAddress":"JL.MOJOPAHIT NO.80",
            "gender":"PEREMPUAN",
            "bloodType":"O",
            "religion":"ISLAM",
            "nationality":"WNI",
            "others":{
                    "rtrw":"002/006",
                    "occupation":"PELAJAR/MAHASISWA",
                    "birthPlaceBirthday":"PEMATANGSIANTAR 06-01-1993",
                    "maritalStatus":"BELUM KAWIN"
            }
        },
        "idForgery":{
            "result":"pass",
            "data":"valid"
        }
    },
    "extra":null,
    "transactionId":"2819211458288028",
    "pricingStrategy":"FREE"
}

Image Base64 Example of Success Response:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
        "image":"/9j/4AAQSkZJRgABAQAAAQABAAD/..",
        "OCR":{
            "idNumber":"1272034601930001",
            "fullName":"SRI HASIPAH",
            "fullNameLocal":"SRI HASIPAH",
            "expiryDate":"SEUMUR HIDUP",
            "state":"SUMATERA UTARA",
            "city":"KOTA PEMATANGSIANTAR",
            "district":"SIANTAR UTARA",
            "subdistrict":"BARU",
            "fullAddress":"JL.MOJOPAHIT NO.80",
            "gender":"PEREMPUAN",
            "bloodType":"O",
            "religion":"ISLAM",
            "nationality":"WNI",
            "others":{
                    "rtrw":"002/006",
                    "occupation":"PELAJAR/MAHASISWA",
                    "birthPlaceBirthday":"PEMATANGSIANTAR 06-01-1993",
                    "maritalStatus":"BELUM KAWIN"
            }
        },
        "idForgery":{
            "result":"pass",
            "data":"valid"
        }
    },
    "extra":null,
    "transactionId":"e7c159166fadc815",
    "pricingStrategy":"FREE"
}

Example of IDVID_NOT_EXISTS Response:

{
    "code":"IDVID_NOT_EXISTS",
    "message":"The IDVID not exists",
    "data":null,
    "extra":null,
    "transactionId":"c67b620fb3607c83",
    "pricingStrategy":"FREE"
}

Example of PARAMETER_ERROR Response:

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

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter error,please check your request whether has illegal parameters",
    "data":null,
    "extra":null,
    "transactionId":"ed6398e55da06693",
    "pricingStrategy":"FREE"
}

Response Description:

Parameter Description
code Query result 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 object image : The image URL or the image base64
OCR : The specifically recognized info on the card
idForgery : result : “pass”: test passed, ID is not forged,“fail”: test failed, ID is forged； detail : null if result is pass, and please click here for the specific reasons if result is fail
extra Extra response info (Exception Message)

Reasons for Fail

Specific reasons
Retake/Screenshot
Colorful photocopied/Cut off corner
Black and white photocopied
Pasted face
Modified NIK

Response Code

Status Code Message
IDVID_NOT_EXISTS free The IDVID not exists

Note: Please remember to add a handler for the Status Codes in the Glossary as well

Token Authentication

Request Parameters:

Parameter Description
accessKey string the accessKey
timestamp string 13-digit-long timestamp, suggested 300 seconds before or after the current time when requesting the token
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:

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"

Request Url

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

Example of Success Response:

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

Example of 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"
}

Example of ACCOUNT_DISABLED Response:

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

Example of CLIENT_ERROR Response:

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

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 free OK
PARAMETER_ERROR free Parameter should not be empty
free Timestamp error
free Signature error
ACCOUNT_DISABLED free Account Disabled
CLIENT_ERROR free HTTP 400 - Bad Request

Glossary

Welcome to the Glossary!

Please read the following to understand how ADVANCE API system, for a smooth integration. We will explain all the basics you need to know about our API.

Status Code

Notes:

Status Code Message
SUCCESS pay OK
ERROR free Server error
EMPTY_PARAMETER_ERROR free Parameter should not be empty
INSUFFICIENT_BALANCE free Insufficient balance, please top up or contact your sales manager for help
SERVICE_BUSY free Messages may look like:
Rate limit is exceeded, please retry after the suggested time in HTTP Header.
Retry-After :10s
p.s. Please also note that this code may migrate to HTTP 429 Too Many Requests in the future.

Quota exceeded: You have exceeded the daily quota for free queries, please contact out tech support for help
IAM_FAILED free Access denied. Messages may look like:
You are not authorized by the Identity and Access Management system
Access Key not found
Token not found or expired
Access Key not found or expired
Account not authorized for this country
Account not authorized for this domain
Account is expired. Please contact your sales manager for help
Account is disabled. Please contact your sales manager for help
Access denied: Token not found or expired
PARAMETER_ERROR free The message is detailed error description, may includes:
Parameter should not be empty
Invalid phone number, please check your phone number format
etc.
p.s. Mobile number format should be country code + phone number(without leading 0 or dash or space e.g. +xx12345678); fixed-line number should be country code + area code + number(without leading 0)
OVER_QUERY_LIMIT free Messages may look like:
Quota exceeded. you have exceeded free query quota, please contact your sales manager for help
Quota exceeded: You have exceeded free query quota for test account, please contact your sales manager for help
CLIENT_ERROR free HTTP client error. Messages may look like:
HTTP 400 - Bad Request
HTTP 404 - Not Found
HTTP 405 - Method Not Allowed
etc.
If you get this error, please check the API document or contact our tech support for help.
RETRY_LATER free Query failed, please retry after the suggested time in HTTP Header.
Retry-After :10s

Notes:

Request URL & Parameters

Parameter Description
requestString string String value for API request
requestFile file Request file for API request
requestInteger optional integer Number value for API request

Response

Parameter Description
code API Status Code
message Status Code Explanation
data field1: explanation of the first information that will be returned from ADVANCE
field2: explanation of the second information that will be returned from ADVANCE
extra Extra response info (Exception Message)

Image Quality Requirements