API Migration Guide

Rossum’s principal API for processing data is the Document Management (DM) API. This API supersedes the older Data Extraction (DE) API, which was Rossum’s primary developer offering until March 2019. We prepared this guide for DE users with a few tips on how to migrate to the current DM API.

Introduction

Whereas the DE API provides only the raw interface to the extraction engine, the DM API builds on top of it to also include rich features for proper data and document management, most importantly, the ability to use a verification user interface on the extracted data, and the webhook-based extension architecture. The main differences that would be relevant to you if you want to migrate to the DM API are as follows:

API endpoints

DE API users used https://all.rir.rossum.ai as the public API endpoint for invoices in all supported languages. In the DM API, the public API endpoint used is https://elis.rossum.ai/api, valid for all cases, even if you have your own dedicated custom model. (UPDATE (Nov 2022): For new integrations use the new https://example.app.rossum.ai/api endpoint. For accounts created before Nov 2022 use the https://elis.rossum.ai/api. Read more about Base URL in documentation.)

Authentication method

In the DE API, each user had a fixed assigned authentication token that had to be sent in a header with each request. The header had the following format:

‘Authorization: secret_key YOUR_ELIS_API_KEY’

The DM API works a little differently. To start using it, you have to create an Elis demo account. Your login credentials will be the username and password to this account. To start interacting with the account features, trigger the login endpoint first. Each time it is triggered, you would obtain a token that can be used in all subsequent calls. The token will be valid for a default expiration time (currently 162 hours), until you log out from the session, or until you hit the login endpoint again. A call on such endpoint may look like this:

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'

{"key": "db313f24f5738c8e04635e036ec8a45cdd6d6b03"}

For further requests, use the token in the request header in the following format:

‘Authorization: token YOUR_ELIS_API_TOKEN’

Please note that the API key for the DE API and the API token for the DM API are not the same and cannot be used interchangeably. If you were using one of the obsolete Rossum clients for data extractions, these will not be working with the API token for the DM API. For such purposes, refer to the DM API documentation. We are also working on adding this feature to our command line tool elisctl.

To find out more about logging in using the DM API and making other requests, refer to the Getting Started section of our DM API documentation.

Different GET and POST endpoints

Besides calling different endpoints, the responses of the DM API GET requests focus on the document as a whole, rather than focusing on the raw extracted data. The response is, therefore, more general and represents a starting point for the next requests.

POST request

Before, you were using POST requests to upload a document. You received an ID of the document and the information on the document processing state. After the data was extracted from the document, you called GET and got the response on the extracted data.

With the launch of the Rossum account, it is now important, not only to specify what document you are working with, but also where it needs to be processed. For each document, there is a queue where the document should be sent and processed. To obtain the ID of the queue, you can list all your queues and pick the relevant queue. After that, you would send a POST request on the upload endpoint:

DE API

Example POST request declaration:
POST /document

Example POST request using curl:
curl -H ‘Authorization: secret_key YOUR_KEY’ -F file=@invoice.pdf https://all.rir.rossum.ai/document

Example response:
{
  “id”: “d93e03e18b044076a6976445”,
  “status”: “processing”
}

DM API

Example POST request declaration:
POST /v1/queues/{id}/upload

Example POST request using curl:
curl -H ‘Authorization: token YOUR_TOKEN’
  -F content=@invoice.pdf ‘https://example.app.rossum.ai/api/v1/queues/8236/upload’

Example response:
{
  “results”: [
{
      “annotation”: “https://example.app.rossum.ai/api/v1/annotations/315509”,
      “document”: “https://example.app.rossum.ai/api/v1/documents/315609”
}
]
}

To get a status of your document, you can send a GET request on the annotation endpoint: GET /v1/annotations/{id}

After the annotation switched to the to_review status, the document can be reviewed in the Rossum app interface and exported.

GET request

To export a document, a GET request should be called on the export endpoint.

DE API

Example GET request:
GET /document/{id}

Example GET request using curl:
curl -H “Authorization: secret_key YOUR_KEY” https://all.rir.rossum.ai/document/3af21605a5bb48ef79f752c8

Example response:
{
  “status”: “ready”,
  “message”: “The analysis is complete”,
  “original_pages”: [
    “https://unsplash.it/595/842”
  ],
  “previews”: [
    “https://unsplash.it/595/842”
  ],
  “fields”: [
{
      “name”: “account_num”,
      “title”: “Bank Account”,
      “content”: “1234567890/0100”,
      “value”: “1234567890/0100”,
      “value_type”: “text”,
      “page”: 0,
      “bbox”: [ 243, 117, 323, 145 ],
      “checks”: {
        “checksum”: “good”
   },
      “score”: 0.9587
},
{
      “name”: “amount_due”,
      “title”: “Amount Due”,
      “content”: “3 705,50”,
      “value”: “3705.50”,
      “value_type”: “number”,
      “page”: 0,
      “bbox”: [ 420, 516, 580, 532 ],
      “score”: 0.989
}
  ],
  “tables”: [
  …
  ],
  “text_lines”: {
    “content”: [
[
        “ICompnany Name INVOICE”,
     “Invoice Templale by Verlex42.corn E 2010 Verlex42 LLC”
   ]
],
“name”: “full_text”,
“title”: “Rough Content”
  }
}

DM API

Example GET request declaration:
GET /v1/queues/{id}/export?id=315509

Example GET request using curl:
curl -H ‘Authorization: token YOUR_TOKEN’ 
‘https://example.app.rossum.ai/api/v1/queues/12485/export’

Example response:
{
  “pagination”: {
“total”: 6,
    “total_pages”: 1,
“next”: null,
    “previous”: null
  },
  “results”: [
{
   “url”: “https://example.app.rossum.ai/api/v1/annotations/481890”,
      “status”: “to_review”,
      “arrived_at”: “2019-05-03T09:28:15.553888Z”,
      “exported_at”: null,
      “document”: {
        “url”: “https://example.app.rossum.ai/api/v1/documents/482044”,
        “file_name”: “sample_invoice.pdf”,
        “file”: “https://example.app.rossum.ai/api/v1/documents/482044/content”
   },
      “modifier”: {
        “url”: “https://example.app.rossum.ai/api/v1/users/13564”,
        “username”: “demo_user@example.app.rossum.ai”
   },
      “schema”: {
        “url”: “https://example.app.rossum.ai/api/v1/schemas/82972”
      },
      “metadata”: {},
      “content”: [
     {
          “category”: “section”,
          “schema_id”: “invoice_info_section”,
          “children”: [
         {
              “category”: “datapoint”,
              “schema_id”: “invoice_id”,
              “value”: “00000055”,
              “type”: “string”
         },
         {
              “category”: “datapoint”,
              “schema_id”: “order_id”,
              “value”: “”,
           “type”: “string”
         },
…

For a more detailed description on the import and export via DM API, please refer to the documentation or check out our blog post on the integration possibilities.

You may have noticed that unlike the DE API, the DM API does not capture all of the fields from the document that can be extracted by the Rossum AI engine. Only a subset is shown to the user in the sidebar and also as part of the API response. To configure the set of captured fields, you can modify the Elis DM schema accordingly.

Document Management features

The DM API was built to accommodate various data and document management requirements. It includes many rich features such as:

• Document lifetime management
• Customization of the schema with extracted fields
• Possibility for modifications to simplify the integration with third-party software
• Review process handling
• Feedback sending and others

For more information on the DM API usage, please refer to our documentation.