API Basics

The url for DocumentsAPI Production is the following one : https://documents.zelros.com

The url for DocumentsAPI Staging is the following one : https://d2i-staging.zelros.com

Notice that the API is available in a synchronous mode, meaning that in one API call, you can post a document and have the answer. Useful for one by one document’s processing.
Profile
POST /api/analyze Return the analysis of a given file

Authentication

To access our API, you will need an authentication token:

import requests

url = "https://documents.zelros.com/auth/realms/documents/protocol/openid-connect/token"
payload = 'client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>&grant_type=client_credentials'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

which returns the following json response:

{
    "access_token": "TOKEN",
    "refresh_token": "REFRESH_TOKEN",
    "token_type": "bearer",
    ...
}

The obtained token, access_token, has to be placed into the authorization tag, like this : Authorization: Bearer <TOKEN>.

You can also refresh your token to extend its lifetime, by sending the previous request with an extra refresh_token parameter, with your REFRESH_TOKEN value, and updating the grant_type value to refresh_token.

User’s table

Every user can be configured with a specific set of supported documents which will be used to determine the document type.

A flag disable_segmentator can be set to true to bypass the segmentation can be set. This flag will

  • bypass the extraction on the images from the pdf

  • bypass the segmentator model that split and crop the pages

NB: disable_segmentator flag can be overwrite by the API call.

Here is an example of the user’s table configuration:

id(uuid) name classifier mode disable_segmentator max_files max_documents document_types

xxxxxx

client_d2i

image_and_text

false

10

15

declaration_glass_breakage,ASSIGNMENT_CLAIM,ASSIGNMENT_CLAIM_NOTIFICATION,INVOICE_GLASS_BREAKAGE,QUOTATION_GLASS_BREAKAGE

xxxxxx

zelros

image_and_text

false

10

15

ALL

API Call

Request parameters:

  • file: boolean, default false, set to true to get the file in the response

  • onlineProcessing: boolean, default false, set a higher priority of the document processing

  • activateContent`: boolean, default false, set to true to get the transcript (text content) of the document

Request body:

  • files documents to analyze

  • types* type or list of types seperated by comma (e.g. CAR_REGISTRATION,DRIVER_LICENSE) which will be used to determine the document type

  • type deprecated, use types instead

  • document_tags

  • tags deprecated, use document_tags instead

  • disable_segmentator, disable the segmentation of the document, optional, default value comme from the client’s table configuration

  • max_documents, max documents (pages) allowed to be analyse, CANNOT be greater than value declared on the client configuration table

Documents are accepted in jpeg, jpg, png, and pdf.

A parameter types or document_tags can be used to give an information about the document sent.

Other parameters can be added to the request body, such as activate_content to get the transcript (text content) of the document.

Example

import requests (1)
import json

file_path = '<YOUR_FILE_PATH>'
token = '<YOUR_TOKEN>'

resp = requests.post(
    'https://documents.zelros.com/api/analyze', data={'document_tags': 'CAR_REGISTRATION' },
    files={'file':  open(file_path, 'rb')}, (2)
    headers={'Authorization': f'Bearer {token}'}
) (3)

body = json.loads(resp.content.decode('utf8'))
print(body)
1 Library import
2 File conversion into binary
3 Launch request

*: If no parameter is provided, the document goes through a classification brick that will determine it before the analysis. This option works for a certain list of document types described below.

Full code

The full code to use Documents API is available here:

import requests
import json
import time

file_path = './document.pdf'

# AuthN to the API

url = "https://documents.zelros.com/auth/realms/documents/protocol/openid-connect/token"
payload = 'client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>&grant_type=client_credentials'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
response = requests.request("POST", url, headers=headers, data = payload)
JSON_auth = json.loads(response.content.decode('utf8'))

token = JSON_auth["access_token"]
print('token','\n', token,'\n')

#  Post the document

print("wait a couple seconds... ",'\n')
start = time.time()
resp = requests.post(
    'https://documents.zelros.com/api/analyze',
    files={'file':  open(file_path, 'rb')},
    headers={'Authorization': f'Bearer {token}'}
)

body = json.loads(resp.content.decode('utf8'))

end = time.time()

print(body,'\n')
print("elasped time for sending + retrieving the document : ",end - start, "seconds")