Rossum Integration Three Ways

As a unique software for invoice data extraction, Rossum is an ideal solution for many customers to their pain point of effective processing of (tens of) thousands of documents every month. In this article, we will have a look at the available options for Rossum integration within a document processing workflow. It will help you to easily integrate Rossum’s open platform within a company’s existing processes and make the whole document processing workflow more effective and smoother than ever before.

Introduction

Rossum provides three basic methods for data input and output:

Regardless of what method you choose, an invoice sent to Rossum shall meet some minimum requirements. The other thing to think about is what role Rossum plays in your data capture process – this guide might be worth a quick read. Overall, if you are not familiar with basic Rossum concepts yet, check out the developer portal and help center guides first.

No choice is forever – the most successful data capture stories are the evolving ones. Many users start prototyping using manual integration, then move on to RPA production prototype, and finally end up building a programmatic API-based integration to maximize their efficiency.

Without further ado, let’s have a look at the integration options.

Manual Integration

There are two ways to upload invoices – importing them by email or uploading them directly in Rossum user interface (Rossum UI).

Import by email

During your self-service registration, an inbox is created where you can send your invoices. If you are not sure about the inbox address, you can check it by clicking on the “Upload” button in the UI.

More invoices can be sent within one email as separate files in the email attachment and the overall size of the email shall not exceed 40 MB. (There are also other requirements and recommendations regarding the upload files you may want to go through.) After an email is sent, it may take a few seconds for the invoices to be shown in Rossum UI. After that, the AI data extraction process will start.

Import by upload in Rossum UI

Another way to upload documents to Rossum is to use the “Upload” button within the UI. As soon as a document is uploaded, it will show up in the queue and the data extraction will begin.

Export processed data

After the invoices are processed, checked by a user and then exported, they will show up in the “Exported” tab. The exported documents are now ready for bulk data export. Under the “Download all” button, you would find four options for download: CSV, XLSX, XML or JSON format. Download the file and voilá – your data is ready for integration to your accounting software or any further usage.

The “Download all” option is now limited to 1,000 invoices. If you need to export more invoices or would like to limit the export to only some invoices, you can customize the output of the manual export by yourself without need for any programmatic development.

The “Download all” option will generate multiple files for download, each with records for 1,000 documents per file for CSV and XLSX formats and 100 documents per file for JSON and XML format.

Programmatic Integration

In order to interact with the API, you need an account. If you do not have one, you can create it using this form. To communicate with API, you can use various third party tools, such as Postman. We have prepared a separate article on how to use Postman with our API. If you are not using Postman, you can check out how to use our API via command line tool below.

Preparation

All the commands we will use in this manual shall be written to a command line shell. In Linux and MacOS, it is usually called ‘Terminal’ and on Windows, it can be found under the Start menu as a Command Prompt application (which is best run as the administrator). In this manual, we are displaying the commands as they should be typed on Linux and MacOS. Windows user may need to refer to the ‘Use the API on Windows’ part of our API documentation before they continue reading. For example, the following command on Linux:

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

This would need to be written on Windows 10 as the following:

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

You also need curl or similar command line data transfer tool to interact with the API. All code samples in this blog post and our API documentation use curl. On MS Windows 10, MacOS X and most Linux distributions, curl should already be pre-installed. If not, you can download it here. We also suggest you install jq tool to make the curl output easier to read. You can download the tool here. Install the tools and, optionally, test if the tools are installed properly by typing the following command to the command line:

curl https://example.app.rossum.ai/api/v1 | jq

You should get the following output:

{
  "organizations": "https://example.app.rossum.ai/api/v1/organizations",
  "workspaces": "https://example.app.rossum.ai/api/v1/workspaces",
  "schemas": "https://example.app.rossum.ai/api/v1/schemas",
  "connectors": "https://example.app.rossum.ai/api/v1/connectors",
  "inboxes": "https://example.app.rossum.ai/api/v1/inboxes",
  "queues": "https://example.app.rossum.ai/api/v1/queues",
  "documents": "https://example.app.rossum.ai/api/v1/documents",
  "users": "https://example.app.rossum.ai/api/v1/users",
  "groups": "https://example.app.rossum.ai/api/v1/groups",
  "annotations": "https://example.app.rossum.ai/api/v1/annotations",
  "pages": "https://example.app.rossum.ai/api/v1/pages"
}

Import -> Export Data Process Walkthrough

Login credentials to work with API are the same as those to log into your account. You can trigger the login endpoint using curl:

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

You will obtain a key, of which value you will use in subsequent calls. This key will be valid for a certain pre-configured amount of time or until you log out from the sessions.

{"key": "db313f24f5738c8e04635e036ec8a45cdd6d6b03"}

To upload a PDF or image document through the API, you will first need to obtain the number of your queue:

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

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

From here, you can upload documents to the queue. Don’t forget to add the “@” sign in front of the document path:

curl -s -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -F content=@document1.pdf -F content=@document2.pdf -F content=@document3.pdf 'https://example.app.rossum.ai/api/v1/queues/8199/upload' | jq -r .results[0].annotation

You will obtain a link with your annotation object number. An annotation object contains all extracted and verified data related to a document.

https://example.app.rossum.ai/api/v1/annotations/319668

Uploaded documents are processed using Rossum’s AI Core Engine. It may take up to several minutes to process a document. You can check the status of the annotation and wait until its status is changed to to_review:

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

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

In order to export extracted and confirmed data, call the export endpoint. You can specify the status, time-range filters and annotation ID list to limit the returned results. You can choose between XML, CSV, XLSX or JSON format. For CSV, use the URL below:

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

Finally, you can dispose the token safely using the logout endpoint:

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

For more information on the Rossum API, see the documentation. You can also go through a Python example script for uploading documents or a couple of scripts in different languages you can use to export documents from your Rossum account.

Robotic Integration (RPA workflows)

Rossum is designed to be compatible with popular Robotic Process Automation platforms like UiPath (a plug & play example on automating the process of data extraction from invoices using UiPath Studio) and BluePrism (a BluePrism asset is available). With these starting points, it’s up to you just to add the flow of gathering the input documents, and entering the captured data to downstream ERPs.

How can the life with an RPA integration look like? Consider an example:
The first part of the workflow gathers the invoices and submits them to Rossum in a batch. During the night, the Rossum neural networks automatically pre-capture information from invoices. Then, during the day, the AP team logs into the Rossum web application, validates the captured data (where needed) and exports the invoices. In the evening, the second part of the RPA workflow downloads the batch of exported invoices and continues processing to post them in the client’s ERP.

Thanks to the many options of Rossum integration, various extensions can be built to fully enhance the customizability of the product and optimize the whole invoice processing workflow. An easy integration opens the door to many customer-specific extensions and verifications that can be used before or after Rossum within the invoice processing workflow.