This page explains the overarching framework of the ADVANCE API system.
Status Code
Our API responses will contain a Status Code indicating the result of the API call, whether it was successful, or has 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. The 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 pay
- 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. Please rely on ‘Status Code’ in your error handling strategy instead of ‘Message’, as 'Message’ is a detailed explanation for developer’s reference and may update without advance notice.
| Strategy code | message | pricingStrategy |
|---|---|---|
| SUCCESS | OK | pay |
| ERROR | Server error | free |
| EMPTY_PARAMETER_ERROR | Parameter should not be empty | free |
| INSUFFICIENT_BALANCE | Insufficient balance, please top up or contact your sales manager for help | free |
| SERVICE_BUSY | 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 | free |
| IAM_FAILED | 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 | free |
| PARAMETER_ERROR | The message contains detailed error description, which is dependant on specific API product. It may include: - 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) | free |
| OVER_QUERY_LIMIT | 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 | free |
| CLIENT_ERROR | 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. | free |
| RETRY_LATER | Query failed, please retry after the suggested time in HTTP Header. Retry-After :10s | free |
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
Response
ADVANCE API responds in JSON format. 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
The following is an example of Response Explanation found in each API document:
ADVANCE API response would at least consists of 4 fields:
codethe Status Codemessage detailed explanation of the Status Code;messagedetailed explanation of the Status Code;extraan exception message (should be empty most of the time);datathe response content from ADVANCE;
transactionId: It is strongly recommended to save the transactionId.
Image Quality Requirements
Unless otherwise specified in the service API docs, please ensure the uploaded images satisfy the following criteria:
- Image format: PNG / JPG / JPEG
- Below 2 MB file size
- Minimum resolution of 256 x 256
- Maximum resolution of 4096 x 4096
For OCR services, please ensure that the uploaded images satisfy the following criteria:
- ID Card’s resolution is not so small that the characters 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 obstructing the words in the ID Card (ie. Light Spot, Dirt, Ink, Shadow)
- Have a clean background (No words or other picture in the background)