API Reference
DocumentationRecipesAPI Referenceincode.com

Introduction

The Incode Omni API is organized around REST. In general our API uses standard secure HTTP requests with JSON arguments and JSON responses.

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 will might contain fields additional fields depending on the data which was extracted from 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.

 { 
   "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 requested resource.
  • 406 (Not Acceptable) - Unacceptable request.
  • 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 that reason it 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:

    • 600 requests per second.
    • 10,000 requests every 5 minutes per IP.