Getting Started

Introduction

The Rossum API allows you to programmatically access and manage your organization's Rossum data and account information. The API allows you to do the following programmatically:

Manage your organization, users, workspaces and queues
Configure captured data: select extracted fields
Integrate Rossum with other systems: import, export, extensions

On this page, you will find an introduction to the API usage from a developer perspective, and a reference to all the API objects and methods.

Developer Resources

There are several other key resources related to implementing, integrating and extending the Rossum platform:

Refer to the Rossum Developer Portal for guides, tutorials, news and a community Q&A section.
For managing and configuring your account, you can use the rossum-api library in Python.
For more information on Rossum implementation options, see the Rossum Implementation Options Overview.
If you are an RPA developer, refer to our UiPath or BluePrism guides.

You may find historical references to the Rossum API as the "Elis Document Management API". Also, formerly a different, Data Extraction API (or DE API) was also available and you may find references to it in some materials. The API is now deprecated.

We have prepared an API Migration Guide for users of the legacy API.

Quick API Tutorial

For a quick tutorial on how to authenticate, upload a document and export extracted data, see the sections below. If you want to skip this quick tutorial, continue directly to the Overview section.

It is a good idea to go through the introduction to the Rossum platform on the Knowledge Base Portal first to make sure you are up to speed on the basic Rossum concepts.

If in trouble, feel free to contact us at support@rossum.ai.

Install curl tool

All code samples included in this API documentation use curl, the command line data transfer tool. On MS Windows 10, MacOS X and most Linux distributions, curl should already be pre-installed. If not, please download it from curl.se). A sample curl command to Rossum API would look like this:

curl -H 'Content-Type: application/json' \
  -d '{"username": "east-west-trading-co@example.com", "password": "aCo2ohghBo8Oghai"}' \
  'https://<example>.rossum.app/api/v1/auth/login'

Example response:

{"key": "db313f24f5738c8e04635e036ec8a45cdd6d6b03"}

You may also want to install jq tool to make curl output human-readable:

curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
  'https://example.rossum.app/api/v1/groups' | jq

Formatted JSON response:

{
  "pagination": {
    ...
  },
  "results": [
    {
      "id": 1,
      "url": "https://example.rossum.app/api/v1/groups/1",
      "name": "viewer"
    },
    ...
  ]
}

Use the API on Windows

This API documentation is written for usage in command line interpreters running on UNIX based operation systems (Linux and Mac). Windows users may need to use the following substitutions when working with API:

Character used in this documentation	Meaning/usage	Substitute character for Windows users
'	single quotes	"
"	double quotes	"" or \"
\	continue the command on the next line	^

Example for Unix-based systems:

curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
  -d '{"target_queue": "https://example.rossum.app/api/v1/queues/8236", "target_status": "to_review"}' \
  'https://example.rossum.app/api/v1/annotations/315777/copy'

Equivalent commands for Windows:

curl -H "Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03" -H "Content-Type: application/json" ^
  -d "{""target_queue"": ""https://example.rossum.app/api/v1/queues/8236"", ""target_status"": ""to_review""}" ^
  "https://example.rossum.app/api/v1/annotations/315777/copy"


curl -H "Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03" -H "Content-Type: application/json" ^
  -d "{\"target_queue\": \"https://example.rossum.app/api/v1/queues/8236\", \"target_status\": \"to_review\"}" ^
  "https://example.rossum.app/api/v1/annotations/315777/copy"

Create an account

In order to interact with the API, you need an account. If you do not have one, you can create one via our self-service portal.

Fill-in your username and password (login credentials to work with API are the same as those to log into your account). Trigger login endpoint to obtain a key (token), that can be used in subsequent calls.

Example login request:

curl -s -H 'Content-Type: application/json' \
  -d '{"username": "east-west-trading-co@example.com", "password": "aCo2ohghBo8Oghai"}' \
  'https://example.rossum.app/api/v1/auth/login'

{"key": "db313f24f5738c8e04635e036ec8a45cdd6d6b03"}

This key will be valid for a default expire time (currently 162 hours) or until you log out from the sessions.

If you write the whole curl command on a single line rather than several as in our example, do not include the ending "\" character as part of the command.

Upload a document

In order to upload a document (PDF, image, XLSX, XLS, DOCX, DOC) through the API, you need to obtain the ID of a queue first:

curl -s -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/queues?page_size=1' | jq -r .results[0].url

Example response:

https://example.rossum.app/api/v1/queues/8199

Then you can upload document to the queue. Alternatively, you can send documents to a queue-related inbox. See upload for more information about importing files. Example request:

curl -s -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  -F content=@document.pdf 'https://example.rossum.app/api/v1/uploads?queue=8199' | jq -r .url

Example response with task URL:

https://example.rossum.app/api/v1/tasks/9231

Wait for document to be ready and review extracted data

As soon as a document is uploaded, it will show up in the queue and the data extraction will begin. It may take a few seconds to several minutes to process a document. You can check status of the annotation and wait until its status is changed to to_review:

curl -s -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/annotations/319668' | jq .status

Result:

"to_review"

After that, you can open the Rossum web interface example.rossum.app to review and confirm extracted data.

Download reviewed data

Now you can export extracted data using the export endpoint of the queue. You can select XML, CSV, XLSX or JSON format. For CSV, use URL like:

curl -s -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/queues/8199/export?status=exported&format=csv&id=319668'

Example response:

Invoice number,Invoice Date,PO Number,Due date,Vendor name,Vendor ID,Customer name,Customer ID,Total amount,
2183760194,2018-06-08,PO2231233,2018-06-08,Alza.cz a.s.,02231233,Rossum,05222322,500.00

Logout from session

Finally you can dispose token safely using logout endpoint:

curl -s -X POST -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/auth/logout'

Logout response:

{"detail":"Successfully logged out."}