OCR (All Fields)

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: multipart/form-data" \
-F "ocrImage=@/Users/lby/Desktop/ocrImage.jpg"\
"https://api.advance.ai/openapi/face-recognition/v3/ocr-ktp-check"

Request URL

https://api.advance.ai/openapi/face-recognition/v3/ocr-ktp-check
POST (form-data)

Request Header Parameters:

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

Request Parameters:

Parameter	Description
ocrImage	file picture of a person’s id card

Note: Please check the OCR image quality requirements in Glossary to ensure that OCR would work properly

Example of SUCCESS Response:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "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":"cb75cfe4c926a5ab",
        "pricingStrategy":"PAY"
    }

Example of SUCCESS Response when there is no comma or space recognized in the field of “birthPlaceBirthday”,
both fields of “placeOfBirth” and “birthday” will be null:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "idNumber":"33******02",
            "name":"R**A M**H A**H,",
            "bloodType":"O",
            "religion":"ISLAM",
            "gender":"PEREMPUAN",
            "birthPlaceBirthday":"LAKI-LAKI",
            "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":"null",
            "birthday":"null"
          },
        "extra":null,
        "transactionId":"cb75cfe4c926a5ab",
        "pricingStrategy":"PAY"
    }

Example of SUCCESS Response when there is invalid birthDate in the field of “birthPlaceBirthday”,
field of “birthday” will be null, and field of “placeOfBirth” will be the value of the part in front of the comma or space in the field of “birthPlaceBirthday”:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "idNumber":"33******02",
            "name":"R**A M**H A**H,",
            "bloodType":"O",
            "religion":"ISLAM",
            "gender":"PEREMPUAN",
            "birthPlaceBirthday":"SE M**N, 01-0",
            "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":"null"
          },
        "extra":null,
        "transactionId":"cb75cfe4c926a5ab",
        "pricingStrategy":"PAY"
    }

Example of SUCCESS Response when there is null in the field of “birthPlaceBirthday”,
both fields of “placeOfBirth” and “birthday” will be null accordingly:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "idNumber":"33******02",
            "name":"R**A M**H A**H,",
            "bloodType":"O",
            "religion":"ISLAM",
            "gender":"PEREMPUAN",
            "birthPlaceBirthday":"null",
            "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":"null",
            "birthday":"null"
          },
        "extra":null,
        "transactionId":"cb75cfe4c926a5ab",
        "pricingStrategy":"PAY"
    }

Example of OCR_NO_RESULT Response:

   {
        "code":"OCR_NO_RESULT",
        "message":"OCR check failed,unable to find any ktp field in the uploaded picture",
        "data":null,
        "extra":null,
        "transactionId":"4d497fd182ab144f",
        "pricingStrategy":"PAY"
    }

Example of IMAGE_INVALID_SIZE Response:

   {
        "code":"IMAGE_INVALID_SIZE",
        "message":"Invalid image size,max image size should be less than 2M,and image dimension should be between 256 * 256 and 4096 * 4096",
        "data":null,
        "extra":null,
        "transactionId":"604b31ae3adeb6c7",
        "pricingStrategy":"FREE"
    }

Example of IMAGE_INVALID_FORMAT Response:

{
    "code":"IMAGE_INVALID_FORMAT",
    "message":"Invalid image format,image format should be one of jpeg/jpg/png,and request content type should be image/jpeg or image/png",
    "data":null,
    "extra":null,
    "transactionId":"9edcb1d7bb84fa95",
    "pricingStrategy":"FREE"
}

Response Description:

Parameter	Description
code	OCR 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	idNumber : ID Number (NIK) of the Person in the KTP
	name : Name of the person in the KTP
	bloodType: Blood type of the person
	religion: Religion of the person
	gender: Gender of the person
	birthPlaceBirthday: Place and date of birth of the person
	province: Province of the person’s residence
	city: City of the person’s residence
	district: District of the person’s residence
	village: Village of the person’s residence
	rtrw: RT/RW of the person’ residence
	address: Detailed Address of the person’s residence
	occupation: Occupation of the person
	expiryDate: Expiry Date of the person’s KTP
	nationality: Nationality of the person
	maritalStatus: Marital status of the person
	placeOfBirth: place of birth of the person
	birthday: birthday of the person
extra	Extra response info (Exception Message)

Response Code

Status Code	Message
IMAGE_INVALID_FORMAT	free Invalid image format, image format should be one of jpeg/jpg/png, and request content type should be image/jpeg or image/png
IMAGE_INVALID_SIZE	free Invalid image size, max image size should be less than 2M, and image dimension should be between 256 * 256 and 4096 * 4096
OCR_NO_RESULT	pay OCR check failed, unable to find any ktp field in the uploaded picture

Note: Don’t Forget to add handler for these Status Codes in 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:

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

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

• Our API responses will contain a Status Code indicating the result of the API call, whether it was successful, or an error occurred during the process
• Each API will also have its own unique Status Codes that can only be found in the responses of the API
• Your API usage will be charged based on the response Status Code, each Status Code listed in our API document will have either a free or pay tag with it
• free means you will not be charged and paymeans that you will be charged
• pay means you will be charged if the API response contains the said status code
• Below are the commonly used Status Codes, these status codes could appear in all our API responses, so please remember to add a handler for these Status Codes

Notes:

• Please use ‘Status Code’ in your strategy instead of ‘Message’, as 'Message’ is a detailed explanation for developer’s reference and may update without ADVANCE Notice.

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:

• If the Status Code is SUCCESS, it may not be charged. Please check the code returned by each interface

Request URL & Parameters

• Request URL can be found at each API document along with the request method (POST or GET or other request method) and Content Type (application/json or other content type)
• Some parameters will have optional tag on them, this means the parameter is not mandatory for the request and they can be empty, however adding them might produce more accurate result, for example : Company check, zip code is an optional parameter but adding zip code parameter will return all the companies around that said zip code instead of all around Indonesia.
• If a parameter does not have an optional tag, it means the parameter is mandatory and making request without them will return EMPTY_PARAMETER_ERROR response
• Every parameter has a data type such as string, integer and file, please double check the parameter data type before making any request
• Here’s an example of parameter explanation that can be found on each API document

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

• ADVANCE API responds in JSON format
• ADVANCE API response consists of 4 fields:
  • code the Status Code;
  • message detailed explanation of the Status Code;
    
  • extra an exception message (should be empty most of the time);
  • data the response content from ADVANCE;
• Each service has its own data format, outlined in the API document
• If the response format is very complicated (multiple different JSON object, nested JSON object), please refer to the Breakdown section of the Response Explanation
• transactionId: It is strongly recommended to save the transactionId.
• The following is an example of Response Explanation found in each API document:

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

• The services check and extract the necessary information from the uploaded images, hence please ensure the uploaded images satisfy the following criteria:
  • Is in one of the following image formats: PNG / JPG / JPEG
  • Below 2 MB file size
  • Minimum resolution of 256 x 256
  • Maximum resolution of 4096 x 4096
• For OCR services please also ensure that the uploaded images satisfy the following criteria:
  • ID Card’s ratio in the uploaded photo is not so small that the words in the ID Card are unreadable
  • ID Card’s orientation is in Vertical or Horizontal position and NOT heavily tilted (around 45 degree)
  • Nothing is covering up the words in the ID Card (ex: Light Spot, Dirt, Ink, Shadow, etc)
  • Have a clean background (No words or other picture in the background)