API User Guide

General principals

systemize.ai uses simple, easy-to-use API calls. However, unlike regular APIs, there are some key difference that need to be understood:

  • An API has a request body and a response body
  • systemize.ai APIs extensively use HTTP Headers for request and response information
  • API responses will be based on the type of message. For example, an image recognition call will often return JSON, but APIs could also return binary data
  • All API calls must use HTTPS

Please note Free-Tier and Starter credits can only run messages as asynchronous. Refer to section Asynchronous Methods for more information.

URI structure

All APIs have the same structure, as shown below:

METHOD: POST
https://api.systemize.ai/api/message/{messagecode}/{async}

Where:

  • {messagecode} is the API message identifier
  • {async} if async specified, means the API returns before the message is complete
HTTP Request Headers

The following request headers are mandatory for each API call. However, each API may have its own unique headers, which will be documented in each of the API documentation.

CLIENT_KEY
Client key as generated from your account's Manage Keys Page
CLIENT_SECRET
Client secret as generated from your account's Manage Keys Page
Content-Type
Specify the content type of the request body being posted (e.g. text/html, image/jpeg)
HTTP Response Headers

The following is a complete list of all HTTP Response Headers that can be returned Note that not all message types will return a value for each

Content-Type
Content Type of the response body
MESSAGE_GUID
Global Unique Identifier that identifies the unique message related to the API call
MESSAGE_RESPONSE_LENGTH
Response length of message
MESSAGE_REQUEST_LENGTH
Request length of message
MESSAGE_FILES_ADDED
Total number of files added to the message (For async calls)
MESSAGE_STATUS
Status of the message, e.g. ERROR, COMPLETE
MESSAGE_PROGRESS
Progress of the message (percent) between 0 and 100 (for async)
MESSAGE_PROGRESS_TEXT
Progress text of message. This will also return any message processing errors
MESSAGE_ROWCOUNT
Number of rows processed by the message (where applicable, e.g. for pages in a PDF)
MESSAGE_RESPONSE_CODE
The API call status, this is related to the API call status, and not the message itself
MESSAGE_RESPONSE_TEXT
The API call response text, this is related to the API call status, and not the message itself. Any errors will be shown here
Using Asynchronous methods

Please note Free-Tier and Starter credits can only run messages as asynchronous

* Async message check frequency for is no less than 5 seconds for Free-Tier, 2 seconds for Starter and 1 for Pro

Async messages run immediately

Asynchronous (async) methods are API calls that do not wait until a message is completed.

The diagram below shows how an asynchronous message is used and accessed.

Async messages paused

Some APIs allow you to upload multiple files before you start a message

You can create an async message and put it on pause, to enable sequential uploading of files.

Below is a diagram that shows an async message created on hold and multiple files uploaded befire it is started

Asynchronous method APIs

Create an async message

METHOD: POST
https://api.systemize.ai/api/message/{messagecode}/async
This will immediately start the message return a MESSAGE_GUID which you will need to use for subsequent async method.

Create an async message and pause it

METHOD: POST
https://api.systemize.ai/api/message/{messagecode}/request

This will return a MESSAGE_GUID which you will need to use for subsequent async methods. The task has not been started yet.

Add a file to the async message

METHOD: PUT
https://api.systemize.ai/api/message/{messagecode}

You can either put a file as direct binary data or as multi-part form data. If putting binary data, "Content-Type" must be set

Start message

METHOD: GET
https://api.systemize.ai/api/message/{messagecode}/start

Start will only work for messages that are in a PAUSED state

Check Message Status

METHOD: GET
https://api.systemize.ai/api/message/{messagecode}/status

Get Message Response

METHOD: GET
https://api.systemize.ai/api/message/{messagecode}/response

A response is only available when a message has completed.