Introduction

Authentication

REST API calls must be authenticated using a custom HTTP header X-Incode-Hardware-Id — along with a JSON web token. Additionally, every API call has to contain x-api-key header with valid client API key.

Please check the section Create an Access Token for an explanation of how access tokens are generated and used

API Responses

Incode Omni uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• Codes in the 2XX range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided (e.g. missing required parameter). These usually mean you need to fix your request.
• Codes in the 5xx range indicate server side errors (these are rare).

Some 2XX responses of the Omni API have a dynamic nature. For example, the Fetch ocr data endpoint might contain additional fields depending on the data which was extracted from the provided ID Document in the session. If you are using typed languages such as Java or C#, consider these cases to avoid having serialization exception when reading the JSON responses.

4XX errors that can be handled programmatically on your end include status of an error and message that briefly explains the error reported.

Arguments:

• timestamp: Long, UTC timestamp in milliseconds
• status: Integer, custom error code or http status code
• error: String, Http status error
• message: String, custom error message
• path: String, endpoint path

Custom error codes are given for each endpoint.

Example response with custom error

 {
   "timestamp": 1584639032757,
   "status": 405,
   "error": "Spoof attempt detected",
   "message": "BadRequestException: Spoof attempt detected.",
   "path": "/omni/add/face"
}

HTTP status code summary:

• 200(OK) - Everything worked as expected.
• 400(Bad Request) - The request was unacceptable, often due to missing a required parameter.
• 401(Unauthorized) - Invalid or missing access token.
• 403(Forbidden) - Invalid or missing api key.
• 404(Not Found) - The requested resource doesn't exist.
• 405(Method Not Allowed) - Unacceptable HTTP method for the requested resource.
• 406(Not Acceptable) - Unacceptable request.
• 429(Too Many Requests) - See rate limits below.
• 500, 502, 503, 504(Server Errors) - Something went wrong on server side. (These are rare.)

API Limitations

Maximum Request Size

There is a limitation of 10Mb as the maximum possible request / response size in all our API endpoints, for this reason; it's is not possible to upload or fetch images/files larger than 10 Mb.

Timeout

There is a hard limit of 30 seconds for all of our endpoints. If any request takes longer than that, you will receive a Request Timeout error.

Rate limits

We rate limit our APIs via throttling based on the "tokens in a bucket" approach:

• Each endpoint call requires a token (each organization has a bucket of tokens per endpoint category)
• Bucket capacity (burst) defines how many tokens can be withdrawn at once
• Tokens are refilled until the bucket reaches maximum capacity based on the refill rate (maxRps)

There are three endpoint categories, each one with its own bucket:

1. SUPER_HEAVY: ID endpoints triggered by the SDK normally (e.g. add/front, add/back, process/id)
2. HEAVY: Face endpoints triggered by the SDK normally (e.g. add/face, process/face)
3. OTHER: All other endpoints

For special cases (only) where these limits are not enough, our Customer Success team can help you adjust as needed.

Rate limit example:

The endpoints add/front, add/back, and process/id are in the SUPER_HEAVY category. The maximum bucket capacity is 5, meaning the max amount of requests that can be done in a second is 5. Every request will deplete the bucket by 1. If all 5 requests are consumed within the same second, the bucket is emptied, and any additional requests within the same second will receive the response: 429 Too Many Requests.

The SUPER_HEAVY bucket has a refill rate of 1 (maxRps) per second, so it will refill by 1 unit every second until it's filled (5).