The Document Processing API endpoint in Detail

The central API endpoint for any document processing is the POST /processing/{workflow} route. It can be used to submit documents of various file types and returns all relevant results of a selected workflow in a single response object.

Parameters

Field	Type	Description
{workflow}	string	It is passed as a part of the query path and determines the kind of analysis, that should be performed for the submitted document file. Common choices are ocr, invoice_capturing or accounting_workflow. A resulting URL including the workflow parameter could look like this: https://api.natif.ai/processing/ocr
file	binary multipart/form-data	The actual file bytes encoded into a multipart/form-data request body.
include	string (optional)	Can be included as a query parameter multiple times. (.../processing/ocr?include=<value1>&include=<value2>[...]) Possible values are currently ocr ‐ All detected pieces of text including their bounding boxes for each document page. See OCR Format extractions ‐ All entities that could be identified in and extracted from the document. The exact structure and set of available entities depends on the selected workflow. See Extractions Format By default all available results are included.
parameters	JSON stringified object (optional)	Some workflows can be configured with additional parameters. These can be passed as a JSON configuration object with this multipart/form-data parameter. The specification of supported settings for each workflow is documented in the respective workflow documentation.

Hint

All popular programming languages have at least one common HTTP library, that conveniently encapsulates the creation of a well-formed multipart/form-data POST request, so you probably don't need to worry about doing so by hand. See the next section for a bunch of code examples, that illustrate this.

Example of a multipart/form-data HTTP request

POST https://testapi.natif.ai/processing/invoice_extraction?include=ocr&include=extractions&wait_for=120
accept: application/json
Authorization: ApiKey <API_KEY_SECRET>
Content-Type: multipart/form-data; boundary=WebAppBoundary

--WebAppBoundary
Content-Disposition: form-data; name="file"; filename="invoice.png"

<FILE_CONTENT_BYTES>
--WebAppBoundary
Content-Disposition: form-data; name="parameters"

{
    "language": "de"
}
--WebAppBoundary--

Implementation examples

PythonShell

import urllib.parse
import requests

headers = {"Accept": "application/json", "Authorization": "ApiKey " + YOUR_API_KEY_SECRET}
query_params = {"include": ['ocr', 'extractions']}
workflow_config = {}
url = "https://api.natif.ai/processing/{workflow}?{params}".format(
    workflow=WORKFLOW_IDENTIFIER,
    params=urllib.parse.urlencode(query_params)
)
with open(FILE_PATH, 'rb') as file:
    response = requests.post(url, headers=headers, files={"file": file}, data={"parameters": workflow_config})

curl -X 'POST' \
  'https://api.natif.ai/processing/invoice_extraction?include=ocr&include=extractions&wait_for=120' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -H 'Authorization: ApiKey <API_KEY_SECRET>' \
  -F 'file=@FILE_PATH;type=image/png' \
  -F 'parameters={"language": "de"}'

Responses

This endpoint may respond with one of the following HTTP-status-codes:

HTTP-Status-Code	Description
201	Processing request completed.
202	Processing request is still in progress.
401	Credentials could not be validated.
403	Credentials could not be authorized for this processing request.
404	No such workflow.
422	Validation Error (most likely regarding the request payload).
429	Temporary rate limit exceeded or uploaded document too large.
500	Processing request failed to complete.

Response format

In most cases the POST /processing/{workflow} endpoint should respond with an HTTP code 201 - Created. The response body is then of type application/json, and contains:

• Always:
  • processing_id: A unique identifier for the respective processing instance. It can be used to retrieve the same results object again later.
• Depending on the result types supported by the respective workflow:
  • ocr: All detected text segments for the document with bounding boxes, as well as fulltext for each document page
  • extractions: A tree-like object containing all entities and their values from the document. The exact set of supported entities and their tree structure depends on the workflow.
  • further extraction details and references to processing result artifacts

The different result types are further documented in the Response Formats section.

Hint

If you want to access re-previous processing results, you can do so uning the processing_id returned by the 201 and 200 responses from this endpoint. See Re-fetching the entire processing output or Fetching individual processing results