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.
- Subscribe to the rossum-api-announcements group to stay up to date on the API and platform updates.
- For managing and configuring your account, use the rossum command-line tool. (Setup instructions.)
- For a management overview of Rossum implementation options, see the Rossum Integration Whitepaper.
- If you are an RPA developer, refer to our UiPath or BluePrism guides.
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 Developer 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
Test curl is installed properly
curl https://api.elis.rossum.ai/v1
{"organizations":"https://api.elis.rossum.ai/v1/organizations","workspaces":"htt
ps://api.elis.rossum.ai/v1/workspaces","schemas":"https://api.elis.rossum.ai/v1/
schemas","connectors":"https://api.elis.rossum.ai/v1/connectors","inboxes":"http
s://api.elis.rossum.ai/v1/inboxes","queues":"https://api.elis.rossum.ai/v1/queue
s","documents":"https://api.elis.rossum.ai/v1/documents","users":"https://api.el
is.rossum.ai/v1/users","groups":"https://api.elis.rossum.ai/v1/groups","annotati
ons":"https://api.elis.rossum.ai/v1/annotations","pages":"https://api.elis.rossu
m.ai/v1/pages"}
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.haxx.se).
Optionally use
jq
tool to pretty-print JSON output
curl https://api.elis.rossum.ai/v1 | jq
{
"organizations": "https://api.elis.rossum.ai/v1/organizations",
"workspaces": "https://api.elis.rossum.ai/v1/workspaces",
"schemas": "https://api.elis.rossum.ai/v1/schemas",
"connectors": "https://api.elis.rossum.ai/v1/connectors",
"inboxes": "https://api.elis.rossum.ai/v1/inboxes",
"queues": "https://api.elis.rossum.ai/v1/queues",
"documents": "https://api.elis.rossum.ai/v1/documents",
"users": "https://api.elis.rossum.ai/v1/users",
"groups": "https://api.elis.rossum.ai/v1/groups",
"annotations": "https://api.elis.rossum.ai/v1/annotations",
"pages": "https://api.elis.rossum.ai/v1/pages"
}
You may also want to install jq
tool to make curl output human-readable.
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 of API call on UNIX-based OS
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"target_queue": "https://api.elis.rossum.ai/v1/queues/8236", "target_status": "to_review"}' \
'https://api.elis.rossum.ai/v1/annotations/315777/copy'
Examples of API call on Windows
curl -H "Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03" -H "Content-Type: application/json" ^
-d "{""target_queue"": ""https://api.elis.rossum.ai/v1/queues/8236"", ""target_status"": ""to_review""}" ^
"https://api.elis.rossum.ai/v1/annotations/315777/copy"
curl -H "Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03" -H "Content-Type: application/json" ^
-d "{\"target_queue\": \"https://api.elis.rossum.ai/v1/queues/8236\", \"target_status\": \"to_review\"}" ^
"https://api.elis.rossum.ai/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.
Login to the account
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.
curl -s -H 'Content-Type: application/json' \ -d '{"username": "east-west-trading-co@elis.rossum.ai", "password": "aCo2ohghBo8Oghai"}' \ 'https://api.elis.rossum.ai/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.
Upload a document
In order to upload a document (PDF or image) through the API, you need to obtain the id of a queue first.
curl -s -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' 'https://api.elis.rossum.ai/v1/queues?page_size=1' | jq -r .results[0].url https://api.elis.rossum.ai/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.
curl -s -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \ -F content=@document.pdf 'https://api.elis.rossum.ai/v1/queues/8199/upload' | jq -r .results[0].annotation https://api.elis.rossum.ai/v1/annotations/319668
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: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \ 'https://api.elis.rossum.ai/v1/annotations/319668' | jq .status "to_review"
After that, you can open the Rossum web interface elis.rossum.ai 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: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \ 'https://api.elis.rossum.ai/v1/queues/8199/export?status=exported&format=csv&id=319668' 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
Finally you can dispose token safely using logout endpoint:
curl -s -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \ 'https://api.elis.rossum.ai/v1/auth/logout' {"detail":"Successfully logged out."}
What's new
List of recent API updates related to Elis integrations and extensions.
Relation object was introduced to track annotation dependencies (e.g. children-parent relationship of split documents). (7/15/2020)
Automated flag was introduced to allow easy tracking of automated documents. (7/15/2020)
It is now possible to update/add/delete multiple datapoints using a bulk operations API. (7/6/2020)
Autopilot configuration has been moved from Workspace to Queue. (6/5/2020)
We are renaming webhook API objects to hook in order to generalize API to allow simple integration of third-party code and services. Please note that queue object was also updated to support hook objects. (6/1/2020)
It is now possible to pass annotation metadata during file upload. (5/29/2020)
Overview
HTTP and REST
The Rossum API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.
HTTP Verbs
Call the API using the following standard HTTP methods:
- GET to retrieve an object or multiple objects in a specific category
- POST to create an object
- PUT to modify entire object
- PATCH to modify fields of the object
- DELETE to delete an object
We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application. JSON is returned by API responses, including errors (except when another format is requested, e.g. XML).
Base URL
Base API endpoint URL depends on the deployment type and location, e.g.
https://api.elis.rossum.ai
. If you are not sure
about correct URL, please contact us at
support@rossum.ai.
Please note that Rossum frontend may use different API endpoints, e.g.
https://elis.rossum.ai/api/
, but these are not meant for third-party
integrations and should not be used without consent from Rossum.
Authentication
Most of the API endpoints require user to be authenticated. To login to the Rossum
API, post an object with username
and password
fields. Login returns new
authentication key to be used in token authentication.
User may delete a token using logout endpoint or automatically after a
configured time (default expire time is 162 hours). Default expire time can be lowered using max_token_lifetime_s
field. When token expires, 401 status is returned.
Users are expected to re-login to obtain a new token.
Login
Login user using username and password
curl -H 'Content-Type: application/json' \
-d '{"username": "east-west-trading-co@elis.rossum.ai", "password": "aCo2ohghBo8Oghai"}' \
'https://api.elis.rossum.ai/v1/auth/login'
{
"key": "db313f24f5738c8e04635e036ec8a45cdd6d6b03"
}
POST /v1/auth/login
Use token key in requests
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/organizations/406'
Login user expiring after 1 hour
curl -H 'Content-Type: application/json' \
-d '{"username": "east-west-trading-co@elis.rossum.ai", "password": "aCo2ohghBo8Oghai", "max_token_lifetime_s": 3600}' \
'https://api.elis.rossum.ai/v1/auth/login'
{
"key": "ltcg2p2w7o9vxju313f04rq7lcc4xu2bwso423b3"
}
Response
Status: 200
Returns object with "key", which is an actual authentication token.
Logout
Logout user
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/auth/logout'
{
"detail": "Successfully logged out."
}
POST /v1/auth/logout
Logout user, discard auth token.
Response
Status: 200
Single Sign-On (SSO)
Rossum allows customers to integrate with their own identity provider, such as Google, Azure AD or any other provider using OAuth2 OpenID Connect protocol (OIDC). Rossum then acts as a service provider.
When SSO is enabled for an organization, user is redirected to a configured identity provider login page
and only allowed to access Rossum application when successfully authenticated.
Identity provider user claim (e.g. email
(default), sub
, preferred_username
, unique_name
)
is used to match a user account in Rossum. Please note that Rossum user accounts still must be created for every
user before logging to Rossum.
Required setup of the OIDC identity provider:
- Redirect URI (also known as Reply URL):
https://elis.rossum.ai/api/oauth/code
Required information to allow OIDC setup for the Rossum service provider:
- OIDC endpoint, such as https://accounts.google.com. It should support openid configuration, e.g. https://accounts.google.com/.well-known/openid-configuration
- client id
- client secret
- claim that should be matched in Rossum
- Rossum organization id
If you need to setup SSO for your organization, please contact support@rossum.ai.
Pagination
All object list operations are paged by default, so you may need several API calls to obtain all objects of given type.
Parameter | Default | Maximum | Description |
---|---|---|---|
page_size | 20 | 100 |
Number of results per page |
page | 1 | Page of results |
Filters and ordering
List queues of workspace
7540
, with localeen_US
and order results byname
.
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/queues?workspace=7540&locale=en_US&ordering=name'
Lists may be filtered using various attributes. Multiple attributes are combined with & in the URL, which results in more specific response. Please refer to the particular object description.
Ordering of results may be enforced by the ordering
parameter and one or more
keys delimited by a comma. Preceding key with a minus sign -
enforces
descending order.
Metadata
Example metadata in a document object
{
"id": 319768,
"url": "https://api.elis.rossum.ai/v1/documents/319768",
"s3_name": "05feca6b90d13e389c31c8fdeb7fea26",
"annotations": [
"https://api.elis.rossum.ai/v1/annotations/319668"
],
"mime_type": "application/pdf",
"arrived_at": "2019-02-11T19:22:33.993427Z",
"original_file_name": "document.pdf",
"content": "https://api.elis.rossum.ai/v1/documents/319768/content",
"metadata": {
"customer-id": "f205ec8a-5597-4dbb-8d66-5a53ea96cdea",
"source": 9581,
"authors": ["Joe Smith", "Peter Doe"]
}
}
When working with API objects, it may be useful to attach some information to
the object (e.g. customer id to a document). You can store custom JSON object
in a metadata
section available in most objects.
List of objects with metadata support: organization, workspace, user, queue, schema, connector, inbox, document, annotation, page.
Total metadata size may be up to 1 kB per object.
Versioning
API Version is part of the URL, e.g. https://api.elis.rossum.ai/v1/users
.
To allow API progress, we consider addition of a field in a JSON object to be a backward-compatible operation that may be introduced at any time. Clients are expected to deal with such changes.
In order to be notified about future API changes and improvements, please subscribe to the rossum-api-announcements group.
Dates
All dates fields are represented as ISO 8601
formatted strings, e.g. 2018-06-01T21:36:42.223415Z
. All returned dates are in UTC timezone.
Errors
Our API uses conventional HTTP response codes to indicate the success or failure of an API request.
Code | Status | Meaning |
---|---|---|
400 | Bad Request | Invalid input data or error from connector. |
401 | Unauthorized | The username/password is invalid or token is invalid (e.g. expired). |
403 | Forbidden | Insufficient permission, missing authentication, invalid CSRF token and similar issues. |
404 | Not Found | Entity not found (e.g. already deleted). |
405 | Method Not Allowed | You tried to access an endpoint with an invalid method. |
409 | Conflict | Trying to change annotation not currently assigned or assigned to another user. |
413 | Payload Too Large | for too large payload (especially for files uploaded). |
500 | Internal Server Error | We had a problem with the server. Try again later. |
503 | Service Unavailable | We're temporarily offline for maintenance. Please try again later. |
Import and Export
Documents may be imported into Rossum using the REST API and email gateway. Supported file formats are PDF, PNG, JPEG and TIFF.`
In order to get the best results from Rossum the documents should be in A4 format of at least 150 DPI (in case of scans/photos). Read more about import recommendations.
Upload
You can upload a document to the queue using upload endpoint with one or more files to be uploaded. You can also specify additional field values in upload endpoint, e.g. your internal document id. As soon as a document is uploaded, data extraction is started.
Upload endpoint supports basic authentication to enable easy integration with third-party systems.
Import by Email
It is also possible to send documents by email using a properly configured inbox that is associated with a queue. Users then only need to know the email address to forward emails to.
For every incoming email, Rossum extracts PDF documents and images, stores them in the queue and starts data extraction process.
Small images (up to 100x100 pixels) are ignored, see inbox for reference.
You can use selected email header data (e.g. Subject) to initialize additional
field values, see rir_field_names
attribute
description for details.
Export
In order to export extracted and confirmed data you can call export endpoint. You can specify status, time-range filters and annotation id list to limit returned results.
Export endpoint supports basic authentication to enable easy integration with third-party systems.
Auto-split of document
It is possible to process a single PDF file that contains several invoices. Just insert a special separator page between the documents. You can print this page and insert it between documents while scanning.
Rossum will recognize a QR code on the page and split the PDF into individual documents
automatically. Produced documents are imported to the queue, while the original document
is set to a split
state.
Document Schema
Every queue has an associated schema that specifies which fields will be extracted from documents as well as the structure of the data sent to connector and exported from the platform.
Rossum schema supports data fields with single values (datapoint
),
fields with multiple values (multivalue
) or tuples of fields (tuple
). At the
topmost level, each schema consists of section
s, which may either directly
contain actual data fields (datapoints
) or use nested multivalue
s and tuple
s as
containers for single datapoints.
But while schema may theoretically consist of an arbitrary number of nested containers, the Rossum UI supports only certain particular combinations of datapoint types. The supported shapes are:
- simple: atomic datapoints of type
number
,string
,date
or enum - list: simple datapoint within a multivalue
- tabular: simple datapoint within a "multivalue tuple" (a multivalue list containing a tuple for every row)
Schema content
Schema content consists of a list of section objects.
Common attributes
The following attributes are common for all schema objects:
Attribute | Type | Description | Required |
---|---|---|---|
category | string | Category of an object, one of section , multivalue , tuple or datapoint . |
yes |
id | string | Unique identifier of an object. | yes |
label | string | User-friendly label for an object, shown in the user interface | yes |
hidden | boolean | If set to true , the object is not visible in the user interface, but remains stored in the database and may be exported. Default is false. |
no |
Section
Example of a section
{
"category": "section",
"id": "amounts_section",
"label": "Amounts",
"children": [...],
"icon": ""
}
Section represents a logical part of the document, such as amounts or vendor info. It is allowed only at the top level. Schema allows multiple sections, and there should be at least one section in the schema.
Attribute | Type | Description | Required |
---|---|---|---|
children | list[object] | Specifies objects grouped under a given section. It can contain multivalue or datapoint objects. |
yes |
icon | string | The icon that appears on the left panel in the UI for a given section (not yet supported on UI). |
Datapoint
A datapoint represents a single value, typically a field of a document or some global document information. Fields common to all datapoint types:
Attribute | Type | Description | Required |
---|---|---|---|
type | string | Data type of the object, must be one of the following: string , number , date , enum , button |
yes |
can_export | boolean | If set to false , datapoint is not exported through export endpoint. Default is true. |
|
can_collapse | boolean | If set to true , tabular (multivalue-tuple) datapoint may be collapsed in the UI. Default is false. |
|
rir_field_names | list[string] | List of references used to initialize an object value. See below for the description. | |
default_value | string | Default value used either for fields that do not use hints from AI engine predictions (i.e. rir_field_names are not specified), or when the AI engine does not return any data for the field. |
|
constraints | object | A map of various constraints for the field. See Value constraints. | |
width | integer | Width of the column (in characters). Default widths are: number: 8, string: 20, date: 10, enum: 20. Only supported for table datapoints. | |
stretch | boolean | If total width of columns doesn’t fill up the screen, datapoints with stretch set to true will be expanded proportionally to other stretching columns. Only supported for table datapoints. | |
width_chars | integer | Deprecated. Use width and stretch properties instead. |
|
score_threshold | float [0;1] | Threshold used to automatically validate field content based on AI confidence scores. If not set, queue.default_score_threshold is used. |
rir_field_names
attribute allows to specify source of initial value of the object. List items may be:
- one of extracted field types to use the AI engine prediction value
upload:id
to identify a value specified while uploading the documentemail_header:<id>
to use a value extracted from email headers. Supported email headers:from
,to
,subject
,message-id
,date
.email_body:<id>
to select email body. Supported values aretext_html
for HTML body ortext_plain
for plain text body.
If more list items in rir_field_names
are specified, the first available value will be used.
String type
Example string datapoint
{
"category": "datapoint",
"id": "document_id",
"label": "Invoice ID",
"type": "string",
"default_value": null,
"rir_field_names": ["document_id"],
"constraints": {
"length": {
"exact": null,
"max": 16,
"min": null
},
"regexp": {
"pattern": "^INV[0-9]+$"
},
"required": false
}
}
String datapoint does not have any special attribute.
Date type
Example date datapoint
{
"id": "item_delivered",
"type": "date",
"label": "Item Delivered",
"format": "MM/DD/YYYY",
"category": "datapoint"
}
Attributes specific to Date datapoint:
Attribute | Type | Description | Required |
---|---|---|---|
format | string | Enforces a format for date datapoint on the UI. See Date format below for more details. Default is YYYY-MM-DD . |
Date format supported: available tokens
D/M/YYYY
: e.g. 23/1/2019MM/DD/YYYY
: e.g. 01/23/2019YYYY-MM-DD
: e.g. 2019-01-23 (ISO date format)
Number type
Example number datapoint
{
"id": "item_quantity",
"type": "number",
"label": "Quantity",
"format": "#,##0.#",
"category": "datapoint"
}
Attributes specific to Number datapoint:
Attribute | Type | Default | Description | Required |
---|---|---|---|---|
format | string | # ##0.# |
Available choices for number format show table bellow. null value is allowed. |
|
aggregations | object | A map of various aggregations for the field. See aggregations. |
The following table shows numeric formats with their examples.
Format | Example |
---|---|
# ##0,# |
1 234,5 or 1234,5 |
# ##0.# |
1 234.5 or 1234.5 |
#,##0.# |
1,234.5 |
# ##0 |
1 234 or 1234 |
#,##0 |
1,234 |
Aggregations
Example aggregations
{
"id": "quantity",
"type": "number",
"label": "Quantity",
"category": "datapoint",
"aggregations": {
"sum": {
"label": "Total"
}
},
"default_value": null,
"rir_field_names": []
}
Aggregations allow computation of some informative values, e.g. a sum of a table column with numeric values.
These are returned among messages
when /annotations/{id}/validate
endpoint is called.
Aggregations can be computed only for tables (multivalues
of tuples
).
Attribute | Type | Description | Required |
---|---|---|---|
sum | object | Sum of values in a column. Default label : "Sum". |
All aggregation objects can have an attribute label
that will be shown in the UI.
Enum type
Example enum datapoint with options
{
"id": "document_type",
"type": "enum",
"label": "Document type",
"hidden": false,
"category": "datapoint",
"options": [
{
"label": "Invoice Received",
"value": "21"
},
{
"label": "Invoice Sent",
"value": "22"
},
{
"label": "Receipt",
"value": "23"
}
],
"default_value": "21",
"rir_field_names": []
}
Attributes specific to Enum datapoint:
Attribute | Type | Description | Required |
---|---|---|---|
options | object | See object description below. | yes |
Every option consists of an object with keys:
Attribute | Type | Description | Required |
---|---|---|---|
value | string | Value of the option. | yes |
label | string | User-friendly label for the option, shown in the UI. | yes |
Enum datapoint value is matched in a case insensitive mode, e.g. EUR
currency value returned by the AI Core Engine is
matched successfully against {"value": "eur", "label": "Euro"}
option.
Button type
Specifies a button shown in Rossum UI. For more details please refer to custom UI extension.
Example button datapoint
{
"id": "show_email",
"type": "button",
"category": "datapoint",
"popup_url": "http://example.com/show_customer_data",
}
Despite being a datapoint object, button currently cannot hold any value. Therefore, the set of available Button datapoint attributes is limited to:
Attribute | Type | Description | Required |
---|---|---|---|
type | string | Data type of the object, must be one of the following: string , number , date , enum , button |
yes |
can_export | boolean | If set to false , datapoint is not exported through export endpoint. Default is true. |
|
can_collapse | boolean | If set to true , tabular (multivalue-tuple) datapoint may be collapsed in the UI. Default is false. |
|
popup_url | string | URL of a popup window to be opened when button is pressed. | yes |
Value constraints
Example value constraints
{
"id": "document_id",
"type": "string",
"label": "Invoice ID",
"category": "datapoint",
"constraints": {
"length": {
"max": 32,
"min": 5
},
"required": false
},
"default_value": null,
"rir_field_names": [
"document_id"
]
}
Constraints limit allowed values. When constraints is not satisfied, annotation is considered invalid and cannot be exported.
Attribute | Type | Description | Required |
---|---|---|---|
length | object | Defines minimum, maximum or exact length for the datapoint value. By default, minimum and maximum are 0 and infinity, respectively. Supported attributes: min , max and exact |
|
regexp | object | When specified, content must match a regular expression. Supported attributes: pattern . To ensure that entire value matches, surround your regular expression with ^ and $ . |
|
required | boolean | Specifies if the datapoint is required by the schema. Default value is true . |
Multivalue
Example of a multivalue:
{
"category": "multivalue",
"id": "line_item",
"label": "Line Item",
"children": {
...
},
"show_grid_by_default": false,
"min_occurrences": null,
"max_occurrences": null,
"rir_field_names": null
}
Example of a multivalue with grid row-types specification:
{
"category": "multivalue",
"id": "line_item",
"label": "Line Item",
"children": {
...
},
"grid": {
"row_types": [
"header", "data", "footer"
],
"default_row_type": "data",
"row_types_to_extract": [
"data"
]
},
"min_occurrences": null,
"max_occurrences": null,
"rir_field_names": ["line_items"]
}
Multivalue is list of datapoint
s or tuple
s of the same type.
It represents a container for data with multiple occurrences
(such as line items) and can contain only objects with the same id
.
Attribute | Type | Description | Required |
---|---|---|---|
children | object | Object specifying type of children. It can contain only objects with categories tuple or datapoint . |
yes |
min_occurrences | integer | Minimum number of occurrences of nested objects. If condition of min_occurrences is violated corresponding fields should be manually reviewed. Minimum required value for the field is 0. If not specified, it is set to 0 by default. | |
max_occurrences | integer | Maximum number of occurrences of nested objects. All additional rows above max_occurrences are removed by extraction process. Minimum required value for the field is 1. If not specified, it is set to infinity by default. | |
grid | object | Configure magic-grid feature properties, see below. | |
show_grid_by_default | boolean | If set to true , the magic-grid is opened instead of footer upon entering the multivalue. Default false . Applied only in UI. Useful when annotating documents for custom training. |
|
rir_field_names | list[string] | List of names used to initialize content from the AI engine predictions. If specified, the value of the first field from the array is used, otherwise default name line_items is used. Attribute can be set only for multivalue containing objects with category tuple . |
no |
Multivalue grid object
Multivalue grid
object allows to specify a row type for each row of the
grid. For data representation of actual grid data rows see Grid object description.
Attribute | Type | Description | Default | Required |
---|---|---|---|---|
row_types | list[string] | List of allowed row type values. | ["data"] |
yes |
default_row_type | string | Row type to be used by default | data |
yes |
row_types_to_extract | string | Types of rows to be extracted to related table | data |
yes |
For example to distinguish two header types and a footer in the validation interface, following row types may be used: header
,
subsection_header
, data
and footer
.
Currently, data extraction classifies every row as either data
or header
(additional row types may be introduced
in the future). We remove rows returned by data extraction that are not in row_types
list (e.g. header
by
default) and are on the top/bottom of the table. When they are in the middle of the table, we mark them as skipped
(null
).
There are three visual modes, based on row_types
quantity:
- More than two row types defined: User selects row types freely to any non-default row type. Clearing row type resets to a default row type. We support up to 6 colors to easily distinguish row types visually.
- Two row types defined (header and default): User only marks header and skipped rows. Clearing row type resets to a default row type.
- One row type defined: User is only able to mark row as skipped (
null
value in data). This is also a default behavior when nogrid
row types configuration is specified in the schema.
Tuple
Example of a tuple:
{
"category": "tuple",
"id": "tax_details",
"label": "Tax Details",
"children": [
...
],
"rir_field_names": [
"tax_details"
]
}
Container representing tabular data with related values, such as tax details.
A tuple
must be nested within a multivalue
object, but unlike multivalue
,
it may consist of objects with different id
s.
Attribute | Type | Description | Required |
---|---|---|---|
children | list[object] | Array specifying objects that belong to a given tuple . It can contain only objects with category datapoint . |
yes |
rir_field_names | list[string] | List of names used to initialize content from the AI engine predictions. If specified, the value of the first extracted field from the array is used, otherwise, no AI engine initialization is done for the object. |
Updating Schema
When project evolves, it is a common practice to enhance or change the extracted field set. This is done by updating the schema object.
By design, Rossum supports multiple schema versions at the same time. However, each document annotation is related to only one of those schemas. If the schema is updated, all related document annotations are updated accordingly. See preserving data on schema change below for limitations of schema updates.
In addition, every queue is linked to a schema, which is used for all newly imported documents.
When updating a schema, there are two possible approaches:
- Update the schema object (PUT/PATCH). All related annotations will be
updated to match current schema shape (even
exported
anddeleted
documents). - Create a new schema object (POST) and link it to the queue. In such case, only newly created objects will use the current schema. All previously created objects will remain in the shape of their linked schema.
Use case 1 - Initial setting of a schema
- Situation: User is initially setting up the schema. This might be an iterative process.
- Recommendation: Edit the existing schema by updating schema (PUT) or updating part of a schema (PATCH).
Use case 2 - Updating attributes of a field (label, constraints, options, etc.)
- Situation: User is updating field, e.g. changing label, number format, constraints, enum options, hidden flag, etc.
- Recommendation: Edit existing schema (see Use case 1).
Use case 3 - Adding new field to a schema, even for already imported documents.
- Situation: User is extending a production schema by adding a new field. Moreover, user would like to see all annotations (
to_review
,postponed
,exported
,deleted
, etc. states) in the look of the newly extended schema. - Recommendation: Edit existing schema (see Use case 1). Data of already created annotations will be transformed to the shape of the updated schema. New fields of annotations in
to_review
andpostponed
state that are linked to extracted fields types will be filled by AI Engine, if available. New fields for alreadyexported
ordeleted
annotations (alsopurged
,exporting
andfailed_export
) will be filled with empty or default values.
Use case 4 - Adding new field to schema, only for newly imported documents
- Situation: User is extending a production schema by adding a new field. However, with the intention that the user does not want to see the newly added field on previously created annotations.
- Recommendation: Create a new schema object (POST) and link it to the queue. Annotation data of previously created annotations will be preserved according to the original schema. This approach is recommended if there is an organizational need to keep different field sets before and after the schema update.
Use case 5 - Deleting schema field, even for already imported documents.
- Situation: User is changing a production schema by removing a field that was used previously. However, user would like to see all annotations (
to_review
,postponed
,exported
,deleted
, etc. states) in the look of the newly extended schema. There is no need to see the original fields in already exported annotations. - Recommendation: Edit existing schema (see Use case 1).
Use case 6 - Deleting schema field, only for newly imported documents
- Situation: User is changing a production schema by removing a field that was used previously. However, with the intention that the user will still be able to see the removed fields on previously created annotations.
- Recommendation: Create a new schema object (see Use case 4). Annotation data of previously created annotations will be preserved according to the original schema. This approach is recommended if there is an organizational need to retrieve the data in the original state.
Preserving data on schema change
In order to transfer annotation field values properly during the schema update,
a datapoint's category
and schema_id
must be preserved.
Supported operations that preserve fields values are:
- adding a new datapoint (filled from AI Engine, if available)
- reordering datapoints on the same level
- moving datapoints from section to another section
- moving datapoints to and from a tuple
- reordering datapoints inside a tuple
- making datapoint a multivalue (original datapoint is the only value in a new multivalue container)
- making datapoint non-multivalue (only first datapoint value is preserved)
Extracted field types
AI engine currently automatically extracts the following fields at the all
endpoint, subject to ongoing expansion.
Identifiers
Example of a schema with different identifiers:
[
{
"category": "section",
"children": [
{
"category": "datapoint",
"constraints": {
"required": false
},
"default_value": null,
"id": "document_id",
"label": "Invoice number",
"rir_field_names": [
"document_id"
],
"type": "string"
},
{
"category": "datapoint",
"constraints": {
"required": false
},
"default_value": null,
"format": "D/M/YYYY",
"id": "date_issue",
"label": "Issue date",
"rir_field_names": [
"date_issue"
],
"type": "date"
},
{
"category": "datapoint",
"constraints": {
"required": false
},
"default_value": null,
"id": "terms",
"label": "Terms",
"rir_field_names": [
"terms"
],
"type": "string"
}
],
"icon": null,
"id": "invoice_info_section",
"label": "Basic information"
}
]
Attr. rir_field_names | Field label | Description |
---|---|---|
account_num | Bank Account | Bank account number |
bank_num | Sort Code | Sort code. Numerical code of the bank. |
iban | IBAN | Bank account number in IBAN format. |
bic | BIC/SWIFT | Bank BIC or SWIFT code. |
const_sym | Constant Symbol | Statistical code on payment order. |
spec_sym | Specific Symbol | Payee id on the payment order, or similar. |
var_sym | Payment reference | In some countries used by the supplier to match the payment received against the invoice. |
terms | Terms | Payment terms as written on the document (e.g. "45 days", "upon receipt"). |
payment_method | Payment method | [BETA] Payment method defined on a document (e.g. 'Cheque', 'Pay order', 'Before delivery') |
customer_id | Customer Number | The number by which the customer is registered in the system of the supplier. |
date_due | Date Due | The due date of the invoice. |
date_issue | Issue Date | Date of issue of the document. |
date_uzp | Tax Point Date | The date of taxable event. |
document_id | Document Identifier | Document number. |
order_id | Order Number | Purchase order identification. (Order Numbers not captured as "sender_order_id") |
recipient_address | Recipient Address | Address of the customer. |
recipient_dic | Recipient Tax Number | Tax identification number of the customer. |
recipient_ic | Recipient Company ID | Company identification number of the customer. |
recipient_name | Recipient Name | Name of the customer. |
recipient_vat_id | Recipient VAT Number | Customer VAT Number |
recipient_delivery_name | Recipient Delivery Name | [BETA] Name of the recipient to whom the goods will be delivered. |
recipient_delivery_address | Recipient Delivery Address | [BETA] Address of the reciepient where the goods will be delivered. |
sender_address | Supplier Address | Address of the supplier. |
sender_dic | Supplier Tax Number | Tax identification number of the supplier. |
sender_ic | Supplier Company ID | Business/organization identification number of the supplier. |
sender_name | Supplier Name | Name of the supplier. |
sender_vat_id | Supplier VAT Number | VAT identification number of the supplier. |
sender_email | Supplier Email | [BETA] Email of the sender. |
sender_order_id | Supplier's Order ID | [BETA] Internal order ID in the suppliers system. |
delivery_note_id | Delivery Note ID | [BETA] Delivery note ID defined on the invoice. |
supply_place | Place of Supply | [BETA] Place of supply (the name of the city or state where the goods will be supplied). |
Document attributes
Attr. rir_field_names | Field label | Description |
---|---|---|
currency | Currency | The currency which the invoice is to be paid in. Possible values: CZK, DKK, EUR, GBP, NOK, SEK, USD, or other. May be also in lowercase. |
document_type | Document Type | Possible values: credit_note, debit_note, tax_invoice (most typical), proforma, receipt, delivery_note or other. |
language | Language | The language which the document was written in. Possible values: ces, deu, eng, fra, slk or other. |
Amounts
Attr. rir_field_names | Field label | Description |
---|---|---|
amount_due | Amount Due | Final amount including tax to be paid after deducting all discounts and advances. |
amount_rounding | Amount Rounding | Remainder after rounding amount_total. |
amount_total | Total Amount | Subtotal over all items, including tax. |
amount_paid | Amount paid | Amount paid already. |
amount_total_base | Tax Base Total | Base amount for tax calculation. |
amount_total_tax | Tax Total | Total tax amount. |
Typical relations (may depend on local laws):
amount_total = amount_total_base + amount_total_tax amount_rounding = amount_total - round(amount_total) amount_due = amount_total - amount_paid + amount_rounding
All amounts are in the main currency of the invoice (as identified in the currency response field). Amounts in other currencies are generally excluded.
Tables
At the moment, the AI engine automatically extracts 2 types of tables.
In order to pick one of the possible choices, set rir_field_names
attribute on multivalue
.
Attr. rir_field_names | Table |
---|---|
tax_details | Tax details |
line_items | Line items |
Tax details
Example of a tax details table:
{
"category": "section",
"children": [
{
"category": "multivalue",
"children": {
"category": "tuple",
"children": [
{
"category": "datapoint",
"constraints": {
"required": false
},
"default_value": null,
"format": "# ##0.#",
"id": "vat_detail_rate",
"label": "VAT rate",
"rir_field_names": [
"tax_detail_rate"
],
"type": "number",
"width": 15
},
...
],
"id": "vat_detail",
"label": "VAT detail"
},
"default_value": null,
"id": "vat_details",
"label": "VAT details",
"max_occurrences": null,
"min_occurrences": null,
"rir_field_names": [
"tax_details"
]
}
],
"icon": null,
"id": "amounts_section",
"label": "Amounts section"
}
Tax details table and breakdown by tax rates.
Attr. rir_field_names | Field label | Description |
---|---|---|
tax_detail_base | Tax Base | Sum of tax bases for items with the same tax rate. |
tax_detail_rate | Tax Rate | One of the tax rates in the tax breakdown. |
tax_detail_tax | Tax Amount | Sum of taxes for items with the same tax rate. |
tax_detail_total | Tax Total | Total amount including tax for all items with the same tax rate. |
tax_detail_code | Tax Code | [BETA] Text on document describing tax code of the tax rate (e.g. 'GST', 'CGST', 'DPH', 'TVA'). If multiple tax rates belong to one tax code on the document, the tax code will be assigned only to the first tax rate. (in future such tax code will be distributed to all matching tax rates.) |
Line items
Example of a line items table:
{
"category": "section",
"children": [
{
"category": "multivalue",
"children": {
"category": "tuple",
"children": [
{
"category": "datapoint",
"constraints": {
"required": true
},
"default_value": null,
"id": "item_desc",
"label": "Description",
"rir_field_names": [
"table_column_description"
],
"type": "string",
"stretch": true
},
{
"category": "datapoint",
"constraints": {
"required": false
},
"default_value": null,
"format": "# ##0.#",
"id": "item_quantity",
"label": "Quantity",
"rir_field_names": [
"table_column_quantity"
],
"type": "number",
"width": 15
},
{
"category": "datapoint",
"constraints": {
"required": false
},
"default_value": null,
"format": "# ##0.#",
"id": "item_amount_total",
"label": "Price w tax",
"rir_field_names": [
"table_column_amount_total"
],
"type": "number"
}
],
"id": "line_item",
"label": "Line item",
"rir_field_names": []
},
"default_value": null,
"id": "line_items",
"label": "Line item",
"max_occurrences": null,
"min_occurrences": null,
"rir_field_names": [
"line_items"
]
}
],
"icon": null,
"id": "line_items_section",
"label": "Line items"
}
AI engine currently automatically extracts line item table content and recognizes row and column types as detailed below. Invoice line items come in a wide variety of different shapes and forms. The current implementation can deal with (or learn) most layouts, with borders or not, different spacings, header rows, etc. We currently make two further assumptions:
- The table generally follows a grid structure - that is, columns and rows may be represented as rectangle spans. In practice, this means that we may currently cut off text that overlaps from one cell to the next column. We are also not optimizing for table rows that are wrapped to multiple physical lines.
- The table contains just a flat structure of line items, without subsection headers, nested tables, etc.
We plan to gradually remove both assumptions in the future.
Attribute rir_field_names | Field label | Description |
---|---|---|
table_column_code | Item Code/Id | Can be the SKU, EAN, a custom code (string of letters/numbers) or even just the line number. |
table_column_description | Item Description | Line item description. Can be multi-line with details. |
table_column_quantity | Item Quantity | Quantity of the item. |
table_column_uom | Item Unit of Measure | Unit of measure of the item (kg, container, piece, gallon, ...). |
table_column_rate | Item Rate | Tax rate for the line item. |
table_column_tax | Item Tax | Tax amount for the line. Rule of thumb: tax = rate * amount_base . |
table_column_amount_base | Amount Base | Unit price without tax. (This is the primary unit price extracted.) |
table_column_amount | Amount | Unit price with tax. Rule of thumb: amount = amount_base + tax . |
table_column_amount_total_base | Amount Total Base | The total amount to be paid for all the items excluding the tax. Rule of thumb: amount_total_base = amount_base * quantity . |
table_column_amount_total | Amount Total | The total amount to be paid for all the items including the tax. Rule of thumb: amount_total = amount * quantity . |
table_column_other | Other | Unrecognized data type. |
Annotation Lifecycle
When a document is submitted to Rossum within a given queue, an annotation object is assigned to it. An annotation goes through a variety of states as it is processed, and eventually exported.
State | Description |
---|---|
importing | Document is being processed by the AI Engine for data extraction; initial state of the annotation. |
failed_import | Import failed e.g. due to a malformed document file. |
split | Annotation was split in user interface and new annotations were created from it. |
to_review | Initial extraction step is done and the annotation is waiting for user validation. |
reviewing | Annotation is undergoing validation in the user interface. |
confirmed | Annotation is validated and confirmed by the user. This status must be explicitly enabled on the queue to be present. |
exporting | Annotation is validated and is now awaiting the completion of connector save call. See connector extension for more information on this status. |
exported | Annotation is validated and successfully passed all hooks; this is the typical terminal state of an annotation. |
failed_export | When the connector returned an error. |
postponed | Operator has chosen to postpone the annotation instead of exporting it. |
deleted | When the annotation was deleted by the user. |
purged | Only metadata was preserved after a deletion. Internal status, shall not be used in production. |
Usage report
In order to obtain an overview of the Rossum usage, you can download Excel file with basic Rossum statistics.
The statistics contains following attributes:
- Username (may be empty in case document was not modified by any user)
- Workspace name
- Queue name
- Imported: count of all documents that were imported during the time period
- Deleted: count of documents that were deleted during the time period
- Exported: count of documents that were successfully exported during the time period
- Net time: total time spent by a user validating the successfully exported documents
Download usage statistics (January 2019).
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/manage/usage-report?from=2019-01-01&to=2019-01-31'
Excel file (xlsx) may be downloaded from https://api.elis.rossum.ai/manage/usage-report
.
You may specify date range using from
and to
parameters (inclusive). If not
specified, a report for last 12 months is generated.
New API
A new API, which contains more information, is being introduced.
Eventually, it will replace the original https://api.elis.rossum.ai/manage/usage-report
usage report.
Download usage report (December 2019 - February 2020).
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
'https://api.elis.rossum.ai/v1/annotations/usage-report' -d '{"filter": {"begin_date": "2019-12-01", "end_date": "2020-01-31"}}'
Request
POST /v1/annotations/usage-report
Attribute | Type | Description |
---|---|---|
filter | object | Filters to be applied on documents used for the computation of usage report |
filter.users | list[URL] | Filter documents modified by the specified users (not applied to imported_count ) |
filter.queues | list[URL] | Filter documents from the specified queues |
filter.begin_date | datetime | Filter documents that has date (arrived_at for imported_count , modified_at for deleted_count , or exported_at for the rest) greater than specified. |
filter.end_date | datetime | Filter documents that has date (arrived_at for imported_count , modified_at for deleted_count , or exported_at for the rest) lower than specified. |
exported_on_time_threshold_s | float | Threshold (in seconds) under which are documents denoted as on_time . |
group_by | list[string] | List of attributes by which the series should be grouped. Possible values: user , workspace , queue , month , week , day . |
{
"filter": {
"users": [
"https://api.elis.rossum.ai/v1/users/173"
],
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"begin_date": "2019-12-01",
"end_date": "2020-01-31"
},
"exported_on_time_threshold_s": 86400,
"group_by": [
"user",
"workspace",
"queue",
"month"
]
}
Response
Status: 200
{
"series": [
{
"begin_date": "2019-12-01",
"end_date": "2020-01-01",
"queue": "https://api.elis.rossum.ai/v1/queues/8199",
"workspace": "https://api.elis.rossum.ai/v1/workspaces/7540",
"values": {
"imported_count": 2,
"deleted_count": null,
"exported_count": null,
"turnaround_avg_s": null,
"corrections_per_document_avg": null,
"exported_on_time_count": null,
"exported_late_count": null,
"time_per_document_avg_s": null,
"time_and_corrections_per_field": []
}
},
{
"begin_date": "2020-01-01",
"end_date": "2020-02-01",
"queue": "https://api.elis.rossum.ai/v1/queues/8199",
"workspace": "https://api.elis.rossum.ai/v1/workspaces/7540",
"user": "https://api.elis.rossum.ai/v1/users/173",
"values": {
"imported_count": null,
"deleted_count": 2,
"exported_count": 2,
"turnaround_avg_s": 1341000,
"corrections_per_document_avg": 1.0,
"exported_on_time_count": 1,
"exported_late_count": 1,
"time_per_document_avg_s": 70.0,
"time_and_corrections_per_field": [
{
"schema_id": "date_due",
"label": "Date due",
"total_count": 1,
"corrected_ratio": 0.0,
"time_spent_avg_s": 0.0
},
...
]
}
},
...
],
"totals": {
"imported_count": 7,
"deleted_count": 2,
"exported_count": 3,
"turnaround_avg_s": 894000,
"corrections_per_document_avg": 1.0,
"exported_on_time_count": 2,
"exported_late_count": 1,
"time_per_document_avg_s": 70.0
}
}
The response consists of two parts: totals
and series
.
Totals
Totals
contain summary information for the whole period (between begin_date
and end_date
).
Attribute | Type | Description |
---|---|---|
imported_count | int | Count of documents that were uploaded to Rossum |
deleted_count | int | Count of documents that were deleted |
exported_count | int | Count of documents that were successfully exported |
turnaround_avg_s | float | Average time (in seconds) that a document spends in Rossum (computed as time exported_at - arrived_at ) |
corrections_per_document_avg | float | Average count of corrections on documents |
exported_on_time_count | int | Number of documents of which turnaround was under exported_on_time_threshold |
exported_late_count | int | Number of documents of which turnaround was above exported_on_time_threshold |
time_per_document_avg_s | float | Average time (in seconds) that users spent validating documents |
Series
Series
contain information grouped by fields defined in group_by
.
The data (see above) are wrapped in values
object,
and accompanied by the values of of attributes that were used for grouping.
Attribute | Type | Description |
---|---|---|
user | URL | User, who modified documents within the group |
workspace | URL | Workspace, in which are the documents within the group |
queue | URL | Queue, in which are the documents within the group |
begin_date | date | Start date, of the documents within the group |
end_date | date | Final date, of the documents within the group |
values | object | Contains the data of totals and time_and_corrections_per_field list (for details see below). |
In addition to the totals
data, series
contain time_and_corrections_per_field
list
that provides detailed data about statistics on each field.
Series details
The detail object contains statistics grouped per field (schema_id
).
Attribute | Type | Description |
---|---|---|
schema_id | string | Reference mapping of the data object to the schema tree |
label | string | Label of the data object (taken from schema). |
total_count | int | Number of data objects |
corrected_ratio | float [0;1] | Ratio of data objects that must have been corrected after automatic extraction. |
time_spent_avg_s | float | Average time (in seconds) spent on validating the data objects |
Extensions
The Rossum platform may be extended via third-party, externally running
services or custom functions. These extensions are registered to receive
callbacks from the Rossum platform on various occasions and allow to modify
the platform behavior. Currently we support these callback extensions:
Webhooks, Serverless Functions,
and Connectors.
Webhooks and connectors require a third-party service accessible through a HTTP endpoint. This may incur additional operational and implementation costs. User-defined serverless functions, on the contrary, are executed within Rossum platform and no additional setup is necessary. They share the interface (input and output data format, error handling) with webhooks.
See the Building Your Own Extension set of guides in Rossum's developer portal for an introduction to Rossum extensions.
Webhook Extension
The webhook component is the most flexible extension. It covers all the most frequent use cases:
- displaying messages to users in validation screen,
- applying custom business rules to check, change, or autofill missing values,
- reacting to document status change in your workflow,
- sending reviewed data to an external systems.
Implement a webhook
Webhooks are designed to be implemented using a push-model using common HTTPS protocol. When an event is triggered, the webhook endpoint is called with a relevant request payload. The webhook must be deployed with a public IP address so that the Rossum platform can call its endpoints; for testing, a middleware like ngrok or serveo may come useful.
Webhook vs. Connector
Webhook extensions are similar to connectors, but they are more flexible and easier to use. A webhook is notified when a defined type of webhook event occurs for a related queue.
Advantages of webhooks over connectors:
- There may be multiple webhooks defined for a single queue
- No hard-coded endpoint names (
/validate
,/save
) - Robust retry mechanism in case of webhook failure
Webhooks are defined using a hook
object of type webhook. For a description
how to create and manage hooks, see the Hook API.
Webhook Events
Example data sent for
annotation_status
event to the hook.config.url when status of the annotation changes
{
"request_id": "ae7bc8dd-73bd-489b-a3d2-f5514b209591",
"timestamp": "2020-01-01T00:00:00.000000Z",
"hook": "https://api.elis.rossum.ai/v1/hooks/789",
"action": "changed",
"event": "annotation_status",
"annotation": {
"document": "https://api.elis.rossum.ai/v1/documents/314621",
"id": 314521,
"queue": "https://api.elis.rossum.ai/v1/queues/8236",
"schema": "https://api.elis.rossum.ai/v1/schemas/223",
"pages": [
"https://api.elis.rossum.ai/v1/pages/551518"
],
"modifier": null,
"modified_at": null,
"confirmed_at": null,
"exported_at": null,
"assigned_at": null,
"status": "to_review",
"previous_status": "importing",
"rir_poll_id": "54f6b91cfb751289e71ddf12",
"messages": null,
"url": "https://api.elis.rossum.ai/v1/annotations/314521",
"content": "https://api.elis.rossum.ai/v1/annotations/314521/content",
"time_spent": 0,
"metadata": {}
},
"document": {
"id": 314621,
"url": "https://api.elis.rossum.ai/v1/documents/314621",
"s3_name": "272c2f41ae84a4f19a422cb432a490bb",
"mime_type": "application/pdf",
"arrived_at": "2019-02-06T23:04:00.933658Z",
"original_file_name": "test_invoice_1.pdf",
"content": "https://api.elis.rossum.ai/v1/documents/314621/content",
"metadata": {}
}
}
Example data sent for
annotation_content
event to the hook.config.url when user updates a value in UI
{
"request_id": "ae7bc8dd-73bd-489b-a3d2-f5214b209591",
"timestamp": "2020-01-01T00:00:00.000000Z",
"hook": "https://api.elis.rossum.ai/v1/hooks/781",
"action": "user_update",
"event": "annotation_content",
"annotation": {
"document": "https://api.elis.rossum.ai/v1/documents/314621",
"id": 314521,
"queue": "https://api.elis.rossum.ai/v1/queues/8236",
"schema": "https://api.elis.rossum.ai/v1/schemas/223",
"pages": [
"https://api.elis.rossum.ai/v1/pages/551518"
],
"modifier": null,
"modified_at": null,
"confirmed_at": null,
"exported_at": null,
"assigned_at": null,
"status": "to_review",
"previous_status": "importing",
"rir_poll_id": "54f6b91cfb751289e71ddf12",
"messages": null,
"url": "https://api.elis.rossum.ai/v1/annotations/314521",
"content": [
{
"id": 1123123,
"url": "https://api.elis.rossum.ai/v1/annotations/314521/content/1123123",
"schema_id": "basic_info",
"category": "section",
"children": [
{
"id": 20456864,
"url": "https://api.elis.rossum.ai/v1/annotations/1/content/20456864",
"content": {
"value": "18 492.48",
"normalized_value": "18492.48",
"page": 2,
...
},
"category": "datapoint",
"schema_id": "number",
"validation_sources": [
"checks",
"score"
],
"time_spent": 0
}
]
}
],
"time_spent": 0,
"metadata": {}
},
"document": {
"id": 314621,
"url": "https://api.elis.rossum.ai/v1/documents/314621",
"s3_name": "272c2f41ae84a4f19a422cb432a490bb",
"mime_type": "application/pdf",
"arrived_at": "2019-02-06T23:04:00.933658Z",
"original_file_name": "test_invoice_1.pdf",
"content": "https://api.elis.rossum.ai/v1/documents/314621/content",
"metadata": {}
},
"updated_datapoints": [11213211]
}
Example of a response for
annotation_content
hook
{
"messages": [
{
"content": "Invalid invoice number format",
"id": 197467,
"type": "error"
}
],
"operations": [
{
"op": "replace",
"id": 198143,
"value": {
"content": {
"value": "John",
"position": [103, 110, 121, 122],
"page": 1
},
"hidden": false,
"options": [],
"validation_sources": ["human"]
}
},
{
"op": "remove",
"id": 884061
},
{
"op": "add",
"id": 884060,
"value": [
{
"schema_id": "item_description",
"content": {
"page": 1,
"position": [162, 852, 371, 875],
"value": "Bottle"
}
}
]
}
]
}
Example data sent for
{
"request_id": "ae7bc8dd-73bd-489b-a3d2-f5214b209591",
"timestamp": "2020-01-01T00:00:00.000000Z",
"hook": "https://api.elis.rossum.ai/v1/hooks/781",
"action": "received",
"event": "email",
"files": [
{
"id": "1",
"filename": "image.png",
"mime_type": "image/png",
"n_pages": 1,
"height_px": 100.0,
"width_px": 150.0
},
{
"id": "2",
"filename": "MS word.docx",
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"n_pages": 1,
"height_px": null,
"width_px": null
},
{
"id": "3",
"filename": "A4 pdf.pdf",
"mime_type": "application/pdf",
"n_pages": 3,
"height_px": 3510.0,
"width_px": 2480.0
},
{
"id": "4",
"filename": "unknown_file",
"mime_type": "text/xml",
"n_pages": 1,
"height_px": null,
"width_px": null
}
],
"headers": {
"from": "test@example.com",
"to": "east-west-trading-co-a34f3a@elis.rossum.ai",
"subject": "Some subject",
"date": "Mon, 04 May 2020 11:01:32 +0200",
"message-id": "15909e7e68e4b5f56fd78a3b4263c4765df6cc4d"
}
}
Example of a response for
{
"files": [
{
"id": "3"
}
]
}
Webhook events specify when the hook should be notified. They can be defined as following:
- either as whole event containing all supported actions for its type (for example
annotation_status
) - or as separately named actions for specified event (for example
annotation_status.changed
)
Supported events and their actions
Event and Action | Payload | Response | Description | Retry on failure |
---|---|---|---|---|
annotation_status.changed |
annotation, document | N/A | Annotation status change occurred |
yes |
annotation_content.initialize |
annotation + content, document, updated_datapoints (empty) | operations, messages | Annotation was initialized (data extracted) | yes |
annotation_content.user_update |
annotation + content, document, updated_datapoints | operations, messages | Annotation was updated by the user | no (interactive) |
annotation_content.export |
annotation + content, document, updated_datapoints (empty) | operations, messages | Annotation is being moved to exported state | yes |
email.received |
files, headers | files | Email with attachments was received | yes |
- When
annotation_content.export
action fails, annotation is switched to thefailed_export
state. - In case a non-interactive webhook call fails (HTTP status >= 400), it is retried within 30 seconds. There are up to 10 attempts performed.
updated_datapoints
list is always empty forannotation_content.initialize
andannotation_content.export
actions.updated_datapoints
list may also be empty forannotation_content.user_update
in case of an action triggered interactively by a user, but with no data changes (e.g. first validation after opening a validation UI or changes confirmation).
Annotation status event data format
annotation_status
event contains following additional event specific attributes.
Key | Type | Description |
---|---|---|
annotation | object | annotation object (enriched with attribute previous_status ) |
document | object | document object (attribute annotations is excluded) |
queues* | list[object] | list of related queue objects |
modifiers* | list[object] | list of related modifier objects |
schemas* | list[object] | list of related schema objects |
* Attribute is only included in the request when specified in hook.sideload
.
Example data sent to hook with sideloaded queue objects
{
"request_id": "ae7bc8dd-73bd-489b-a3d2-f5214b209591",
"timestamp": "2020-01-01T00:00:00.000000Z",
"hook": "https://api.elis.rossum.ai/v1/hooks/781",
"action": "changed",
"event": "annotation_status",
...
"queues": [
{
"id": 8198,
"name": "Received invoices",
"url": "https://api.elis.rossum.ai/v1/queues/8198",
...
"metadata": {},
"use_confirmed_state": false,
"settings": {}
}
]
}
Annotation content event data format
annotation_content
event contains following additional event specific attributes.
Key | Type | Description |
---|---|---|
annotation | object | annotation object. Content is pre-loaded with annotation data. Annotation data are enriched with normalized_value , see example. |
document | object | document object (attribute annotations is excluded) |
updated_datapoints | list[int] | List of IDs of datapoints that were changed by last event. |
queues* | list[object] | list of related queue objects |
modifiers* | list[object] | list of related modifier objects |
schemas* | list[object] | list of related schema objects |
* Attribute is only included in the request when specified in hook.sideload
.
Annotation content event response format
All of the annotation_content
events expect a JSON object with the following
optional lists in the response: messages
and operations
The message
object contains attributes:
Key | Type | Description |
---|---|---|
id | integer | Optional unique id of the concerned datapoint; omit for a document-wide issues |
type | enum | One of: error, warning or info. |
content | string | A descriptive message to be shown to the user |
For example, you may use error for fatals like a missing required field, whereas info is suitable to decorate a supplier company id with its name as looked up in the suppliers database.
The operations
object describes operation to be performed on the annotation
data (replace, add, remove). Format of the operations
key is the same as for
bulk update of annotations, please refer to the annotation
data API for complete description.
Email received event data format
email
event contains following additional event specific attributes.
Key | Type | Description |
---|---|---|
files | list[object] | List of objects with metadata of each attachment contained in the arriving email. |
headers | object | Headers extracted from the arriving email. |
The files
object contains attributes:
Key | Type | Description |
---|---|---|
id | string | Some arbitrary identifier. |
filename | string | Name of the attachment. |
mime_type | string | MIME type of the attachment. |
n_pages | integer | Number of pages (defaults to 1 if it could not be acquired). |
height_px | float | Height in pixels (300 DPI is assumed for PDF files, defaults to null if it could not be acquired). |
width_px | float | Width in pixels (300 DPI is assumed for PDF files, defaults to null if it could not be acquired). |
The headers
object contains the same values as are available for initialization of values in email_header:<id>
(namely: from
, to
, subject
, message-id
, date
).
Email received event response format
All of the email
events expect a JSON object with the following list in the response: files
The files
object contains attributes:
Key | Type | Description |
---|---|---|
id | int | id of file that will be used for creating an annotation |
This is useful for filtering out unwanted files by some measures that are not available in Rossum by default.
Validating payloads from Rossum
Example of hook receiver, which verifies the validity of Rossum request
import hashlib
import hmac
from flask import Flask, request, abort
app = Flask(__name__)
SECRET_KEY = "<Your secret key stored in hook.config.secret>" # never store this in code
@app.route("/test_hook", methods=["POST"])
def test_hook():
digest = hmac.new(SECRET_KEY.encode(), request.data, hashlib.sha1).hexdigest()
try:
prefix, signature = request.headers["X-Elis-Signature"].split("=")
except ValueError:
abort(401, "Incorrect header format")
if not (prefix == "sha1" and hmac.compare_digest(signature, digest)):
abort(401, "Authorization failed.")
return
For authorization of payloads, the shared secret method is used.
When a secret token is set in hook.config.secret
, Rossum uses it to create a hash signature with each payload.
This hash signature is passed along with each request in the headers as X-Elis-Signature
.
The goal is to compute a hash using hook.config.secret
and the request body,
and ensure that the signature produced by Rossum is the same. Rossum uses HMAC SHA1 signature.
Webhook requests may be autenticated using a client SSL certificate, see Hook API for reference.
Serverless Function Extension
Serverless functions allows to extend Rossum functionality without setup and maintenance of additional services.
Webhooks and Serverless functions share a basic setup: input and output data format and error handling. They are both configured using a hook API object.
Unlike webhooks, serverless functions do not send the event and action notifications to a specific URL. Instead, the function's code snippet is executed within the Rossum platform. See function API description for details about how to setup a serverless function and connect it to the queue.
Supported events and their actions
For description of supported events, actions and input/output data examples, please refer to Webhook Extensions section.
Supported runtimes
Currently Rossum supports NodeJS 12 runtime
(nodejs12.x
) to execute JavaScript functions. If you would like to use
another runtime, please let us know at product@rossum.ai.
Please be aware that we may eventually deprecate and remove runtimes in the future (deprecation will be announced at least 6 months before the deprecation date).
Limitations
Serverless functions do not have internet access by default. If your functions require internet access to work properly, e.g. when exporting data over API to ERP system, please let us know at product@rossum.ai.
Implementation
Example serverless function usable for
annotation_content
event (JavaScript implementation).
// This serverless function example can be used for annotation_content events
// (e.g. user_update action). annotation_content events provide annotation
// content tree as the input.
//
// The function below shows how to:
// 1. Display a warning message to the user if "item_amount_base" field of
// a line item exceeds a predefined threshold
// 2. Removes all dashes from the "invoice_id" field
//
// item_amount_base and invoice_id should be fields defined in a schema.
// --- ROSSUM HOOK REQUEST HANDLER ---
// The rossum_hook_request_handler is an obligatory main function that accepts
// input and produces output of the rossum serverless function hook. Currently,
// the only available programming language is Javascript executed on Node.js 12 environment.
// @param {Object} annotation - see https://api.elis.rossum.ai/docs/#annotation-content-event-data-format
// @returns {Object} - the messages and operations that update the annotation content
exports.rossum_hook_request_handler = ({
annotation: {
content
}
}) => {
try {
// Values over the threshold trigger a warning message
const TOO_BIG_THRESHOLD = 1000000;
// List of all datapoints of item_amount_base schema id
const amountBaseColumnDatapoints = findBySchemaId(
content,
'item_amount_base',
);
messages = [];
for (var i = 0; i < amountBaseColumnDatapoints.length; i++) {
// Use normalized_value for comparing values of Date and Number fields (https://api.elis.rossum.ai/docs/#content-object)
if (amountBaseColumnDatapoints[i].content.normalized_value >= TOO_BIG_THRESHOLD) {
messages.push(
createMessage(
'warning',
'Value is too big',
amountBaseColumnDatapoints[i].id,
),
);
}
}
// There should be only one datapoint of invoice_id schema id
const [invoiceIdDatapoint] = findBySchemaId(content, 'invoice_id');
// "Replace" operation is returned to update the invoice_id value
const operations = [
createReplaceOperation(
invoiceIdDatapoint,
invoiceIdDatapoint.content.value.replace(/-/g, ''),
),
];
// Return messages and operations to be used to update current annotation data
return {
messages,
operations,
};
} catch (e) {
// In case of exception, create and return error message. This may be useful for debugging.
const messages = [
createMessage('error', 'Serverless Function: ' + e.message)
];
return {
messages,
};
}
};
// --- HELPER FUNCTIONS ---
// Return datapoints matching a schema id.
// @param {Object} content - the annotation content tree (see https://api.elis.rossum.ai/docs/#annotation-data)
// @param {string} schemaId - the field's ID as defined in the extraction schema(see https://api.elis.rossum.ai/docs/#document-schema)
// @returns {Array} - the list of datapoints matching the schema ID
const findBySchemaId = (content, schemaId) =>
content.reduce(
(results, dp) =>
dp.schema_id === schemaId ? [...results, dp] :
dp.children ? [...results, ...findBySchemaId(dp.children, schemaId)] :
results,
[],
);
// Create a message which will be shown to the user
// @param {number} datapointId - the id of the datapoint where the message will appear (null for "global" messages).
// @param {String} messageType - the type of the message, any of {info|warning|error}. Errors prevent confirmation in the UI.
// @param {String} messageContent - the message shown to the user
// @returns {Object} - the JSON message definition (see https://api.elis.rossum.ai/docs/#annotation-content-event-response-format)
const createMessage = (type, content, datapointId = null) => ({
content: content,
type: type,
id: datapointId,
});
// Replace the value of the datapoint with a new value.
// @param {Object} datapoint - the content of the datapoint
// @param {string} - the new value of the datapoint
// @return {Object} - the JSON replace operation definition (see https://api.elis.rossum.ai/docs/#annotation-content-event-response-format)
const createReplaceOperation = (datapoint, newValue) => ({
op: 'replace',
id: datapoint.id,
value: {
content: {
value: newValue,
},
},
});
To implement a serverless function, create a hook object of type
function
. Use code
object config attribute to specify a serialized source
code.
Connector Extension
The connector component is aimed at two main use-cases: applying custom business rules during data validation, and direct integration of Rossum with downstream systems.
The connector component receives two types of callbacks - an on-the-fly validation callback on every update of captured data, and an on-export save callback when the document capture is finalized.
The custom business rules take use chiefly of the on-the-fly validation callback. The connector can auto-validate and transform both the initial AI-based extractions and each user operator edit within the validation screen; based on the input, it can push user-visible messages and value updates back to Rossum. This allows for both simple tweaks (like verifying that two amounts sum together or transforming decimal points to thousand separators) and complex functionality like intelligent PO match.
The integration with downstream systems on the other hand relies mainly on the save callback. At the same moment a document is exported from Rossum, it can be imported to a downstream system. Since there are typically constraints on the captured data, these constraints can be enforced even within the validation callback.
Implement a connector
Connectors are designed to be implemented using a push-model using common HTTPS protocol. When annotation data is changed, or when data export is triggered, specific connector endpoint is called with annotation data as a request payload. The connector must be deployed with a public IP address so that the Rossum platform can call its endpoints; for testing, a middleware like ngrok or serveo may come useful.
Example of a valid no-op (empty)
validate
response
{"messages": [], "updated_datapoints": []}
Example of a valid no-op (empty)
save
response
{}
The connector API consists of two endpoints, validate and save, described below. A connector must always implement both endpoints (though they may not necessarily perform a function in a particular connector - see the right column for an empty reply example), the platform raises an error if it is not able to run a endpoint.
Setup a connector
The next step after implementing the first version of a connector is configuring it in the Rossum platform.
In Rossum, a connector object defines service_url
and params
for
construction of HTTPS requests and authorization_token
that is passed in
every request to authenticate the caller as the actual Rossum server. It may also
uniquely identify the organization when multiple Rossum organizations share the
same connector server.
To set-up a connector for a queue, create a connector object using either our API or the rossum tool – follow these instructions. A connector object may be associated with one or more queues. One queue can only have one connector object associated with it.
Connector API
Example data sent to connector (
validate
,save
)
{
"meta": {
"document_url": "https://api.elis.rossum.ai/v1/documents/6780",
"arrived_at": "2019-01-30T07:55:13.208304Z",
"original_file": "https://api.elis.rossum.ai/v1/original/bf0db41937df8525aa7f3f9b18a562f3",
"original_filename": "Invoice.pdf",
"queue_name": "Invoices",
"workspace_name": "EU",
"organization_name": "East West Trading Co",
"annotation": "https://api.elis.rossum.ai/v1/annotations/4710",
"queue": "https://api.elis.rossum.ai/v1/queues/63",
"workspace": "https://api.elis.rossum.ai/v1/workspaces/62",
"organization": "https://api.elis.rossum.ai/v1/organizations/1",
"modifier": "https://api.elis.rossum.ai/v1/users/27",
"updated_datapoint_ids": ["197468"],
"modifier_metadata": {},
"queue_metadata": {},
"annotation_metadata": {},
"rir_poll_id": "54f6b9ecfa751789f71ddf12",
"automated": false
},
"content": [
{
"id": "197466",
"category": "section",
"schema_id": "invoice_info_section",
"children": [
{
"id": "197467",
"category": "datapoint",
"schema_id": "invoice_number",
"page": 1,
"position": [916, 168, 1190, 222],
"rir_position": [916, 168, 1190, 222],
"rir_confidence": 0.97657,
"value": "FV103828806S",
"validation_sources": ["score"],
"type": "string"
},
{
"id": "197468",
"category": "datapoint",
"schema_id": "date_due",
"page": 1,
"position": [938, 618, 1000, 654],
"rir_position": [940, 618, 1020, 655],
"rir_confidence": 0.98279,
"value": "12/22/2018",
"validation_sources": ["score"],
"type": "date"
},
{
"id": "197469",
"category": "datapoint",
"schema_id": "amount_due",
"page": 1,
"position": [1134, 1050, 1190, 1080],
"rir_position": [1134, 1050, 1190, 1080],
"rir_confidence": 0.74237,
"value": "55.20",
"validation_sources": ["human"],
"type": "number"
}
]
},
{
"id": "197500",
"category": "section",
"schema_id": "line_items_section",
"children": [
{
"id": "197501",
"category": "multivalue",
"schema_id": "line_items",
"children": [
{
"id": "198139",
"category": "tuple",
"schema_id": "line_item",
"children": [
{
"id": "198140",
"category": "datapoint",
"schema_id": "item_desc",
"page": 1,
"position": [173, 883, 395, 904],
"rir_position": null,
"rir_confidence": null,
"value": "Red Rose",
"validation_sources": [],
"type": "string"
},
{
"id": "198142",
"category": "datapoint",
"schema_id": "item_net_unit_price",
"page": 1,
"position": [714, 846, 768, 870],
"rir_position": null,
"rir_confidence": null,
"value": "1532.02",
"validation_sources": ["human"],
"type": "number"
}
]
}
]
}
]
}
]
}
All connector endpoints, representing particular points in the
document lifetime, are simple verbs that receive a JSON POST
ed and
potentially expect a JSON returned in turn.
The authorization type and authorization token is passed as an Authorization
HTTP header. Authorization type may be secret_key
(shared secret) or Basic
for HTTP basic authentication.
Please note that for Basic authentication, authorization_token
is passed
as-is, therefore it must be set to a correct base64 encoded value. For example
username connector
and password secure123
is encoded as
Y29ubmVjdG9yOnNlY3VyZTEyMw==
authorization token.
Connector requests may be autenticated using a client SSL certificate, see Connector API for reference.
Errors
If a connector does not implement an endpoint, it may return HTTP status 404. An endpoint may fail, returning either HTTP 4xx or HTTP 5xx; for some endpoints (like validate and save), this may trigger a user interface message; either the error key of a JSON response is used, or the response body itself in case it is not JSON. The connector endpoint save can be called in asynchronous (default) as well as synchronous mode (useful for embedded mode).
Data format
The received JSON object contains two keys, meta
carrying the metadata and content
carrying endpoint-specific content.
The metadata identify the concerned document, containing attributes:
Key | Type | Description |
---|---|---|
document_url | URL | document URL |
arrived_at | timestamp | A time of document arrival in Rossum (ISO 8601) |
original_file | URL | Permanent URL for the document original file |
original_filename | string | Filename of the document on arrival in Rossum |
queue_name | string | Name of the document's queue |
workspace_name | string | Name of the document's workspace |
organization_name | string | Name of the document's organization |
annotation | URL | Annotation URL |
queue | URL | Document's queue URL |
workspace | URL | Document's workspace URL |
organization | URL | Document's organization URL |
modifier | URL | Modifier URL |
modifier_metadata | object | Metadata attribute of the modifier, see metadata |
queue_metadata | object | Metadata attribute of the queue, see metadata |
annotation_metadata | object | Metadata attribute of the annotation, see metadata |
rir_poll_id | string | Internal extractor processing id |
updated_datapoint_ids | list[string] | Ids of objects that were recently modified by user |
automated | bool | Flag whether annotation was automated |
A common class of content is the annotation tree, which is a JSON object that can contain nested datapoint objects, and matches the schema datapoint tree.
Intermediate nodes have the following structure:
Key | Type | Description |
---|---|---|
id | integer | A unique id of the given node |
schema_id | string | Reference mapping the node to the schema tree |
category | string | One of section, multivalue, tuple |
children | list | A list of other nodes |
Datapoint (leaf) nodes structure contains actual data:
Key | Type | Description |
---|---|---|
id | integer | A unique id of the given node |
schema_id | string | Reference mapping the node to the schema tree |
category | string | datapoint |
type | string | One of string, date or number, as specified in the schema |
value | string | The datapoint value, string represented but normalizes, to that they are machine readable: ISO format for dates, a decimal for numbers |
page | integer | A 1-based integer index of the page, optional |
position | list[float] | List of four floats describing the x1, y1, x2, y2 bounding box coordinates |
rir_position | list[float] | Bounding box of the value as detected by the data extractor. Format is the same as for position . |
rir_confidence | float | Confidence (estimated probability) that this field was extracted correctly. |
Annotation lifecycle with a connector
If an asynchronous connector is deployed to a queue, an annotation status will change from reviewing
to exporting
and subsequently to exported
or failed_export
. If no connector extension is deployed to a queue or if the attribute asynchronous
is set to false
, an annotation status will change from reviewing
to exported
(or failed_export
) directly.
Endpoint: validate
This endpoint is called after the document processing has finished, when operator opens a document
in the Rossum verification interface and then every time after operator updates a field. After the
processing is finished, the initial validate call is marked with initial=true
URL parameter.
For the other calls, only /validate
without the parameter is called.
The request path is fixed to /validate
and cannot be changed.
It may:
- validate the given annotation tree and return a list of messages commenting on it (e.g. pointing out errors or showing matched suppliers).
- update the annotation tree by returning a list of replace, add and remove operations
Both the messages and the updated data are shown in the verification interface. Moreover, the messages may block confirmation in the case of errors.
This endpoint should be fast as it is part of an interactive workflow.
Receives an annotation tree as content.
Returns a JSON object with the lists: messages
, operations
and updated_datapoints
.
Keys messages
, operations
(optional)
The description of these keys was moved to the Hook Extension. See the description here.
Key updated_datapoints
(optional, deprecated)
We also support a simplified version of updates using updated_datapoints
response key. It only supports updates (no add or remove operations) and is now
deprecated. The updated datapoint object contains attributes:
Key | Type | Description |
---|---|---|
id | string | A unique id of the concerned datapoint, currently only datapoints of category datapoint can be updated |
value | string | New value of the datapoint. Value is formatted according to the datapoint type (e.g. date is string representation of ISO 8601 format). |
hidden | boolean | Toggle for hiding/showing of the datapoint, see datapoint |
options | list[object] | Options of the datapoint -- valid only for type=enum , see enum options |
position | list[float] | New position of the datapoint, list of four numbers. |
Validate endpoint should always return 200 OK status.
An error message returned from the connector prevents user from confirming the document.
Endpoint: save
This endpoint is called when the invoice transitions to the exported
state.
Connector may process the final document annotation and save it to the target
system. It receives an annotation tree as content
. The request path is fixed
to /save
and cannot be changed.
The save endpoint is called asynchronously (unless synchronous mode is set in related connector object. Timeout of the save endpoint is 60 seconds.
For successful export, the request should have 2xx status.
Example of successful
save
response without messages in UI
HTTP/1.1 204 No Content
HTTP/1.1 200 OK
Content-Type: text/plain
this response body is ignored
HTTP/1.1 200 OK
Content-Type: application/json
{
"messages": []
}
When messages are expected to be displayed in the UI, they should be sent in the same format as in validate endpoint.
Example of successful
save
response with messages in UI
HTTP/1.1 200 OK
Content-Type: application/json
{
"messages": [
{
"content": "Everything is OK.",
"id": null,
"type": "info"
}
]
}
If the endpoint fails with an HTTP error and/or message of type error
is received,
the document transitions to the failed_export
state - it is then available
to the operators for manual review and re-queuing to the to_review
state
in the user interface. Re-queuing may be done also programmatically via
the API using a PATCH call to set to_review
annotation status. Patching
annotation status to exporting
state triggers an export retry.
Example of unsuccessful
save
response with messages in UI
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"messages": [
{
"content": "Even though this message is info, the export will fail due to the status code.",
"id": null,
"type": "info"
}
]
}
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain
An errror message "Export failed." will show up in the UI
HTTP/1.1 200 OK
Content-Type: application/json
{
"messages": [
{
"content": "Proper status code could not be set.",
"id": null,
"type": "error"
}
]
}
Custom UI Extension
Sometimes users might want to extend the behavior of UI validation view with something special. That should be the goal of custom UI extensions.
Buttons
Currently, there are two different ways of using a custom button:
- Popup Button - opens a specific URL in the web browser
- Validate Button - triggers a standard validate call to connector
If you would like to read more about how to create a button, see the Button schema.
Popup Button
Popup Button opens a website completely managed by the user in a separate tab. It runs in parallel to the validation interface session in the app. Such website can be used for any interface that will assist operators in the reviewing process.
Example Use Cases of Popup Button:
- opening an email linked to the annotated document
- creating a new item in external database according to extracted data
Communication with the Validation Interface
Although it is completely possible to query our API from within your popup, direct way of communication with the validation interface may be desired for the sake of simplicity. Such communication uses standard browser API of window.postMessage.
You will need to use window.addEventListeners in order to receive messages from the validation interface:
Once the listener is in place, you can post one of supported message types:
- GET_DATAPOINTS - returns the same tree structure you’d get by requesting annotation data
- FINISH - informs the Rossum app that the popup process is ready to be closed. After this message is posted, popup will be closed and Rossum app will trigger a validate call.
Providing message type to postMessage lets Rossum interface know what operation user requests and determines the type of the answer which could be used to match appropriate response.
Validate button
If popup_url
key is missing in button's schema, clicking the button will trigger a standard validate call to connector. In such call, updated_datapoint_ids
will contain the ID of the pressed button.
Note: if you’re missing some annotation data that you’d like to receive in a similar way, do contact our support team. We’re collecting feedback to further expand this list.
Automation
All imported documents are processed by the data extraction process to obtain values of fields specified in the schema. Extracted values are then available for validation in the UI.
Using per-queue automation settings, it is possible to skip manual UI validation step and automatically switch document to confirmed state or proceed with the export of the document. Decision to export document or switch it to confirmed state is based on Queue settings.
Currently, there are three levels of automation:
No automation: User has to review all documents in the UI to validate extracted data (default).
Partial automation: User only reviews documents with low data extraction confidence ("eye" icon is displayed for one or more fields) or validation errors.
Full automation: All documents with no validation errors are exported or switched to confirmed state.
An error triggered by a schema field constraint or connector validation blocks auto-export even in full-automation level. In such case, non-required fields with validation errors are cleared and validation is performed again. In case the error persists, the document must be reviewed manually, otherwise it is exported or switched to confirmed state.
Read more about the Automation framework on our developer hub.
Sources of field validation
Low-confidence fields are marked in the UI by an "eye" icon, we consider them
to be not validated. On the API level they have an empty validation_sources
list.
Validation of a field may be introduced by various sources: data extraction
confidence above a threshold, computation of various checksums (e.g. VAT rate,
net amount and gross amount) or a human review. These validations are recorded in
the validation_source
list. The data extraction confidence threshold may be
adjusted, see validation sources for details.
AI Confidence Scores
While there are multiple ways to automatically pre-validate fields, the most prominent one is score-based validation based on AI Core Engine confidence scores.
The confidence score predicted for each AI-extractd field is stored in the
rir_confidence
attribute. The score is a number between 0 and 1, and is
calibrated in such a way that it corresponds to the probability of a given
value to be correct. In other words, a field with score 0.80 is expected
to be correct 4 out of 5 times.
The value of the score_threshold
(can be set on queue,
or individually per datapoint in schema; default is 0.975)
attribute represents the minimum score that triggers
automatic validation. Because of the score meaning, this directly corresponds
to the achieved accuracy. For example, if a score threshold for validation is
set at 0.975, that gives an expected error rate of 2.5% for that field.
Autopilot
Autopilot is a automatic process removing "eye" icon from fields. This process is based on past occurrence of field value on documents which has been already processed in the same queue.
Read more about this Automation component on our developer hub.
Autopilot configuration
Default Autopilot configuration
{
"autopilot": {
"enabled": true,
"search_history":{
"rir_field_names": ["sender_ic", "sender_dic", "account_num", "iban", "sender_name"],
"matching_fields_threshold": 2
},
"automate_fields":{
"rir_field_names": [
"account_num",
"bank_num",
"iban",
"bic",
"sender_dic",
"sender_ic",
"recipient_dic",
"recipient_ic",
"const_sym"
],
"field_repeated_min": 3
}
}
}
Autopilot configuration can be modified in Queue.settings where you can set
rules for each queue.
If Autopilot is not explicitly disabled by switch enabled
set to false
, Autopilot is enabled.
Configuration is divided into two sections:
History search
This section configures process of finding documents from the same sender as the document which is currently being processed. Annotation is considered from the same sender if it contains fields with same rir_field_name and value as the current document.
When at least two fields listed in
rir_field_names
match values of the current document, document is is considered to have same sender
{
"search_history":{
"rir_field_names": ["sender_ic", "sender_dic", "account_num"],
"matching_fields_threshold": 2
}
}
Attribute | Type | Description |
---|---|---|
rir_field_names | list | List of rir_field_names used to find annotations from the same sender. This should contain fields which are unique for each sender. For example sender_ic or sender_dic .Please note that due to technical reasons it is not possible to use document_type in this field and it will be ignored. |
matching_fields_threshold | int | At least matching_fields_threshold fields must match current annotation in order to be considered from the same sender. See example on the right side. |
Automate fields
This section describes rules which will be applied on annotations found in previous step History search.
Field will have "eye" icon removed, if we have found at least field_repeated_min
fields with same rir_field_name and value
on documents found in step History search.
Attribute | Type | Description |
---|---|---|
rir_field_names | list | List of rir_field_names which can be validated based on past occurrence |
field_repeated_min | int | Number of times field must be repeated in order to be validated |
If any config section is missing, default value which you can see on the right side is applied.
Embedded Mode
In some use-cases, it is desirable to use only the per-annotation validation view of the Rossum application. Rossum may be integrated with other systems using so-called embedded mode.
In embedded mode, special URL is constructed and then used in iframe or popup browser window to show Rossum annotation view. Some view navigation widgets are hidden (such as home, postpone and delete buttons), so that user is only allowed to update and confirm all field values.
Embedded mode can be used to view annotations only in status to_review, reviewing, postponed, or confirmed.
Embedded mode workflow
The host application first uploads a document using standard Rossum
API. During this process, an annotation object
is created. It is possible to obtain a status of the annotation object and wait for
the status to became to_review
(ready for checking) using annotation endpoint.
As soon as importing of the annotation object has finished, an authenticated user
may call start_embedded endpoint to obtain a URL that is
to be included in iframe or popup browser window of the host application. Parameters of the call
are return_url
and cancel_url
that are used to redirect to in a browser when user finishes
the annotation.
The URL contains security token that is used by embedded Rossum application to access Rossum API.
When the checking of the document has finished, user clicks
on done button and host application is notified about finished annotation through
save
endpoint of the connector HTTP API. By default, this call is made asynchronously, which
causes a lag (up to a few seconds) between the click on done button and the call to save
endpoint. However, it is possible to switch the calls to synchronous mode by switching the
connector
asynchronous
toggle to false
(see connector for reference).
API Reference
For introduction to the Rossum API, see Overview
Most of the API endpoints require user to be authenticated, see Authentication for details.
Organization
Example organization object
{
"id": 406,
"url": "https://api.elis.rossum.ai/v1/organizations/406",
"name": "East West Trading Co",
"workspaces": [
"https://api.elis.rossum.ai/v1/workspaces/7540"
],
"users": [
"https://api.elis.rossum.ai/v1/users/10775"
],
"ui_settings": {},
"metadata": {},
"trial_expires_at": "2020-09-02T14:28:11.000000Z",
"is_trial": true
}
Organization is a basic unit that contains all objects that are required to fully use Rossum platform.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the organization | true | |
name | string | Name of the organization (not visible in UI) | ||
url | URL | URL of the organization | true | |
workspaces | list[URL] | List of workspaces objects in the organization | true | |
users | list[URL] | List of users in the organization | true | |
ui_settings | object | {} |
Organization-wide frontend UI settings (e.g. locales). Rossum internal. | |
metadata | object | {} |
Client data, see metadata. | |
is_trial | bool | Property indicates whether this license is a trial license | ||
trial_expires_at | timestamp | Timestamp for when the trial period ended (ISO 8601) |
Create new organization
curl -s -X POST -H 'Content-Type: application/json' \
-d '{"template_name": "UK Demo Template", "organization_name": "East West Trading Co", "user_fullname": "John Doe", "user_email": "john@east-west-trading.com", "user_password": "owo1aiG9ua9Aihai", "user_ui_settings": { "locale": "en" }, "create_key": "13156106d6f185df24648ac7ff20f64f1c5c06c144927be217189e26f8262c4a"}' \
'https://api.elis.rossum.ai/v1/organizations/create'
{
"organization": {
"id": 105,
"url": "https://api.elis.rossum.ai/v1/organizations/105",
"name": "East West Trading Co",
"workspaces": [
"https://api.elis.rossum.ai/v1/workspaces/160"
],
"users": [
"https://api.elis.rossum.ai/v1/users/173"
],
"ui_settings": {},
"metadata": {},
"trial_expires_at": "2020-09-02T14:28:11.000000Z",
"is_trial": true
}
}
POST /v1/organizations/create
Create new organization and related objects (workspace, queue, user, schema, inbox).
Attribute | Type | Description |
---|---|---|
template_name | enum | Template to use for new organization (see below) |
organization_name | string | Name of the organization. Will be also used as a base for inbox e-mail address. |
user_fullname | string | Full user name |
user_email | Valid email of the user (also used as Rossum login) | |
user_password | string | Initial user password |
user_ui_settings | object | Initial UI settings, default: {"locale": "en"} |
create_key | string | A key that allows to create an organization |
You need a create_key
in order to create an organization. Please contact support@rossum.ai to obtain one.
Selected template_name
affects default schema and extracted fields. Please
note that the demo templates may be updated as new features are introduced.
Available templates:
Template name | Description | Is demo |
---|---|---|
EU Demo Template | VAT invoices with EU-style bank information | yes |
US Demo Template | Tax invoices in the US and internationally | yes |
UK Demo Template | Also best for India, Canada and Australia | yes |
CZ Demo Template | Czech standard invoices | yes |
Empty Organization Template | Empty organization, suitable for further customization | no |
Response
Status: 200
Returns object with organization
key and organization object value.
Billing for organization
In order to obtain an overview of the billed items, you can get basic billing statistics.
Download billing report (February 1, 2019 - February 5, 2019).
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
'https://api.elis.rossum.ai/v1/organizations/789/billing' -d '{"filter": {"begin_date": "2019-02-01", "end_date": "2020-02-05"}}'
POST /v1/organizations/{id}/billing
Attribute | Type | Description |
---|---|---|
filter | object | Filters used for the computation of billed items counts |
filter.queues | list[URL] | Filter billed items for the specified queues to be counted to the report |
filter.begin_date | datetime | Filter billed items that was issued since the specified date (including the specified date) to be counted to the report. |
filter.end_date | datetime | Filter billed items that was issued up to the specified date (including the specified date) to be counted to the report. |
group_by | list[string] | List of attributes by which the series should be grouped. Possible values: queue . |
{
"filter": {
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"begin_date": "2019-02-01",
"end_date": "2019-02-03"
},
"group_by": [
"queue",
]
}
Response
Status: 200
{
"series": [
{
"begin_date": "2019-02-01",
"end_date": "2019-02-01",
"queue": "https://api.elis.rossum.ai/v1/queues/8199",
"values": {
"header_fields_per_page": 2,
"header_fields_per_document": 5,
"header_fields_and_line_items_per_page": 9,
"header_fields_and_line_items_per_document": 20
}
},
{
"begin_date": "2019-02-02",
"end_date": "2019-02-02",
"queue": "https://api.elis.rossum.ai/v1/queues/8199",
"values": {
"header_fields_per_page": 2,
"header_fields_per_document": 5,
"header_fields_and_line_items_per_page": 9,
"header_fields_and_line_items_per_document": 20
}
},,
...
],
"totals": {
"header_fields_per_page": 8,
"header_fields_per_document": 16,
"header_fields_and_line_items_per_page": 20,
"header_fields_and_line_items_per_document": 43
}
}
The response consists of two parts: totals
and series
.
Billing totals
Totals
contain summary information for the whole period (between begin_date
and end_date
).
Attribute | Type | Description |
---|---|---|
header_fields_per_page | int | Number of pages that were processed by Rossum AI Engine and where only header fields were supposed to be captured. |
header_fields_per_document | int | Number of documents that were processed by Rossum AI Engine and where only header fields were supposed to be captured. |
header_fields_and_line_items_per_page | int | Number of pages that were processed by Rossum AI Engine and where line item fields were supposed to be captured. |
header_fields_and_line_items_per_document | int | Number of documents that were processed by Rossum AI Engine and where line item fields were supposed to be captured. |
Billing series
Series
contain information grouped by fields defined in group_by
. Only grouping by queue
is allowed.
The data (see above) are wrapped in values
object,
and accompanied by the values of attributes that were used for grouping.
Attribute | Type | Description |
---|---|---|
queue | URL | Queue of billed pages or documents |
begin_date | date | Start date of the documents with billed items within the group |
end_date | date | Final date of the documents with billed items within the group |
values | object | Contains the data of totals list grouped by queue and date. |
List all organizations
List all organizations
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/organizations'
{
"pagination": {
"total": 1,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 406,
"url": "https://api.elis.rossum.ai/v1/organizations/406",
"name": "East West Trading Co",
"workspaces": [
"https://api.elis.rossum.ai/v1/workspaces/7540"
],
"users": [
"https://api.elis.rossum.ai/v1/users/10775"
],
"ui_settings": {},
"metadata": {},
"trial_expires_at": "2020-09-02T14:28:11.000000Z",
"is_trial": true
}
]
}
GET /v1/organizations
Retrieve all organization objects.
Supported filters: id
, name
Supported ordering: id
, name
Response
Status: 200
Returns paginated response with a list of organization objects. Usually, there would only be one organization.
Retrieve a organization
Get organization object
406
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/organizations/406'
{
"id": 406,
"url": "https://api.elis.rossum.ai/v1/organizations/406",
"name": "East West Trading Co",
"workspaces": [
"https://api.elis.rossum.ai/v1/workspaces/7540"
],
"users": [
"https://api.elis.rossum.ai/v1/users/10775"
],
"ui_settings": {},
"metadata": {},
"trial_expires_at": "2020-09-02T14:28:11.000000Z",
"is_trial": true
}
GET /v1/organizations/{id}
Get an organization object.
Response
Status: 200
Returns organization object.
User
Example user object
{
"id": 10775,
"url": "https://api.elis.rossum.ai/v1/users/10775",
"first_name": "John",
"last_name": "Doe",
"email": "john-doe@east-west-trading.com",
"date_joined": "2018-09-19T13:44:56.000000Z",
"username": "john-doe@east-west-trading.com",
"groups": [
"https://api.elis.rossum.ai/v1/groups/3"
],
"organization": "https://api.elis.rossum.ai/v1/organizations/406",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"is_active": true,
"last_login": "2019-02-07T16:20:18.652253Z",
"ui_settings": {},
"metadata": {}
}
A user object represents individual user of Rossum. Every user is assigned to an organization.
A user can be assigned user role (permission groups): viewer
, annotator
, manager
, admin
.
User may be assigned to one or more queues and can only access annotations from the assigned queues. This restriction is not applied to admin users, who may access annotations from all queues.
Users cannot be deleted, but can be disabled (set is_active
to false
).
Field email
cannot be changed through the API (due to security reasons).
Field password
can be set on user creation but cannot be changed through the API (due to security reasons).
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the user | true | |
url | URL | URL of the user | true | |
first_name | string | First name of the user | ||
last_name | string | Last name of the user | ||
string | Email of the user | true | ||
password | string | Password (not shown on API) | ||
date_joined | datetime | Date of user join | ||
username | string | Username of a user | ||
groups | list[URL] | [] |
List of user role (permission groups) | |
organization | URL | Related organization | ||
queues | list[URL] | [] |
List of queues user is assigned to. | |
is_active | bool | true |
Whether user is enabled or disabled | |
last_login | datetime | Date of last login | ||
ui_settings | object | {} |
User-related frontend UI settings (e.g. locales). Rossum internal. | |
metadata | object | {} |
Client data, see metadata. |
List all users
List all users in the organization.
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/users'
{
"pagination": {
"total": 1,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 10775,
"url": "https://api.elis.rossum.ai/v1/users/10775",
"first_name": "John",
"last_name": "Doe",
"email": "john-doe@east-west-trading.com",
"date_joined": "2018-09-19T13:44:56.000000Z",
"username": "john-doe@east-west-trading.com",
...
}
]
}
GET /v1/users
Retrieve all user objects.
Supported filters: id
, organization
, username
, first_name
, last_name
, email
, is_active
, last_login
, groups
, queues
Supported ordering: id
, username
, first_name
, last_name
, email
, last_login
, date_joined
Response
Status: 200
Returns paginated response with a list of user objects.
Create new user
Create new user in organization
406
curl -s -X POST -H 'Content-Type: application/json' -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-d '{"organization": "https://api.elis.rossum.ai/v1/organizations/406", "username": "jane@east-west-trading.com", "email": "jane@east-west-trading.com", "queues": ["https://api.elis.rossum.ai/v1/queues/8236"], "groups": ["https://api.elis.rossum.ai/v1/groups/2"]}' \
'https://api.elis.rossum.ai/v1/users'
{
"id": 10997,
"url": "https://api.elis.rossum.ai/v1/users/10997",
"first_name": "",
"last_name": "",
"email": "jane@east-west-trading.com",
"date_joined": "2019-02-09T22:16:38.969904Z",
"username": "jane@east-west-trading.com",
"groups": [
"https://api.elis.rossum.ai/v1/groups/2"
],
"organization": "https://api.elis.rossum.ai/v1/organizations/406",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8236"
],
"is_active": true,
"last_login": null,
"ui_settings": {}
}
Create a new user with password and no email (a technical user)
curl -s -X POST -H 'Content-Type: application/json' -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-d '{"organization": "https://api.elis.rossum.ai/v1/organizations/406", "username": "technical-user@east-west-trading.com", "password": "secret"}' \
'https://api.elis.rossum.ai/v1/users'
{
"id": 10998,
"url": "https://api.elis.rossum.ai/v1/users/10998",
"first_name": "",
"last_name": "",
"email": "",
"date_joined": "2020-09-25T14:30:38.969904Z",
"username": "technical-user@east-west-trading.com",
"groups": [],
"organization": "https://api.elis.rossum.ai/v1/organizations/406",
"queues": [],
"is_active": true,
"last_login": null,
"ui_settings": {}
}
POST /v1/users
Create a new user object.
Response
Status: 201
Returns created user object.
Retrieve a user
Get user object
10997
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/users/10997'
{
"id": 10997,
"url": "https://api.elis.rossum.ai/v1/users/10997",
"first_name": "Jane",
"last_name": "Bond",
"email": "jane@east-west-trading.com",
"date_joined": "2019-02-09T22:16:38.969904Z",
"username": "jane@east-west-trading.com",
...
}
GET /v1/users/{id}
Get a user object.
Response
Status: 200
Returns user object.
Update a user
Update user object
10997
curl -s -X PUT -H 'Content-Type: application/json' -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-d '{"organization": "https://api.elis.rossum.ai/v1/organizations/406", "username": "jane@east-west-trading.com", "queues": ["https://api.elis.rossum.ai/v1/queues/8236"], "groups": ["https://api.elis.rossum.ai/v1/groups/2"], "first_name": "Jane"}' \
'https://api.elis.rossum.ai/v1/users/10997'
{
"id": 10997,
"url": "https://api.elis.rossum.ai/v1/users/10997",
"first_name": "Jane",
"last_name": "",
"email": "jane@east-west-trading.com",
...
}
PUT /v1/users/{id}
Update user object.
Response
Status: 200
Returns updated user object.
Update part of a user
Update
first_name
of user object10997
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"first_name": "Emma"}' \
'https://api.elis.rossum.ai/v1/users/10997'
{
"id": 10997,
"url": "https://api.elis.rossum.ai/v1/users/10997",
"first_name": "Emma",
"last_name": "",
...
}
PATCH /v1/users/{id}
Update part of user object.
Response
Status: 200
Returns updated user object.
Password
Due to security reasons, user passwords cannot be set directly using the standard CRUD operations. Instead, the following endpoints can be used for resetting and changing passwords.
Change password
Change password of user object
10997
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"new_password1": "new_password", "new_password2": "new_password", "old_password": "old_password"}' \
'https://api.elis.rossum.ai/v1/auth/password/change'
{
"id": 10997,
"url": "https://api.elis.rossum.ai/v1/users/10997",
...
}
POST /v1/auth/password/change
Change password of current user.
Response
Status: 200
Returns user object.
Reset password
Reset password of a user with email
jane@east-west-trading.com
curl -X POST -H 'Content-Type: application/json' \
-d '{"email": "jane@east-west-trading.com"}' \
'https://api.elis.rossum.ai/v1/auth/password/reset'
{"detail": "Password reset e-mail has been sent."}
POST /v1/auth/password/reset
Reset password to a users specified by their emails. The users are sent an email with a verification URL leading to web form, where they can set their password.
Response
Status: 200
User Role
Example role object
{
"id": 3,
"url": "https://api.elis.rossum.ai/v1/groups/3",
"name": "admin"
}
User role is a group of permissions that are assigned to the user. Permissions are assigned to individual operations on objects.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the user role | true | |
url | URL | URL of the user role | true | |
name | string | Name oft the user role | true |
There are three pre-defined roles:
Role | Description |
---|---|
viewer | Read-only user, cannot change any API object. May be useful for automated data export or auditor access. |
annotator_limited | User that is allowed to change annotation and its datapoints. Note: this role is under active development and should not be used in production environment. |
annotator | In addition to permissions of annotator_limited the user is also allowed to import a document. |
manager | In addition to permissions of annotator the user is also allowed to access usage-reports. |
admin | User can modify API objects to set-up organization (e.g. workspaces, queues, schemas) |
User can only access annotations from queues it is assigned to, with the exception of admin
role that can access any queue.
Permissions assigned to the role cannot be changed through the API.
List all user roles
List all user roles (groups)
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/groups'
{
"pagination": {
"total": 3,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"url": "https://api.elis.rossum.ai/v1/groups/1",
"name": "viewer"
},
{
"url": "https://api.elis.rossum.ai/v1/groups/2",
"name": "annotator"
},
{
"url": "https://api.elis.rossum.ai/v1/groups/3",
"name": "admin"
}
]
}
GET /v1/groups
Retrieve all organization objects.
Supported filters: name
Supported ordering: name
Response
Status: 200
Returns paginated response with a list of group objects.
Retrieve a user role
Get group object
2
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/groups/2'
{
"url": "https://api.elis.rossum.ai/v1/groups/2",
"name": "annotator"
}
GET /v1/groups/{id}
Get a user role object.
Response
Status: 200
Returns group object.
Workspace
Example workspace object
{
"id": 7540,
"name": "East West Trading Co",
"url": "https://api.elis.rossum.ai/v1/workspaces/7540",
"autopilot": true,
"organization": "https://api.elis.rossum.ai/v1/organizations/406",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199",
"https://api.elis.rossum.ai/v1/queues/8236"
],
"metadata": {}
}
A workspace object is a container of queue objects.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the workspace | true | |
name | string | Name of the workspace | ||
url | URL | URL of the workspace | true | |
autopilot | bool | (Deprecated) Whether to automatically confirm datapoints (hide eyes) from previously seen annotations | true | |
organization | URL | Related organization | ||
queues | list[URL] | [] | List of queues that belongs to the workspace | true |
metadata | object | {} |
Client data, see metadata. |
List all workspaces
List all workspaces
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/workspaces'
{
"pagination": {
"total": 1,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 7540,
"name": "East West Trading Co",
"url": "https://api.elis.rossum.ai/v1/workspaces/7540",
"autopilot": true,
"organization": "https://api.elis.rossum.ai/v1/organizations/406",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199",
"https://api.elis.rossum.ai/v1/queues/8236"
],
"metadata": {}
}
]
}
GET /v1/workspaces
Retrieve all workspace objects.
Supported filters: id
, name
, organization
Supported ordering: id
, name
Response
Status: 200
Returns paginated response with a list of workspace objects.
Create a new workspace
Create new workspace in organization
406
named Test Workspace
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "Test Workspace", "organization": "https://api.elis.rossum.ai/v1/organizations/406"}' \
'https://api.elis.rossum.ai/v1/workspaces'
{
"id": 7694,
"name": "Test Workspace",
"url": "https://api.elis.rossum.ai/v1/workspaces/7694",
"autopilot": false,
"organization": "https://api.elis.rossum.ai/v1/organizations/406",
"queues": [],
"metadata": {}
}
POST /v1/workspaces
Create a new workspace object.
Response
Status: 201
Returns created workspace object.
Retrieve a workspace
Get workspace object
7694
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/workspaces/7694'
{
"id": 7694,
"name": "Test Workspace",
"url": "https://api.elis.rossum.ai/v1/workspaces/7694",
"autopilot": false,
"organization": "https://api.elis.rossum.ai/v1/organizations/406",
"queues": [],
"metadata": {}
}
GET /v1/workspaces/{id}
Get an workspace object.
Response
Status: 200
Returns workspace object.
Update a workspace
Update workspace object
7694
curl -X PUT -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "My Workspace", "organization": "https://api.elis.rossum.ai/v1/organizations/406"}' \
'https://api.elis.rossum.ai/v1/workspaces/7694'
{
"id": 7694,
"name": "My Workspace",
"url": "https://api.elis.rossum.ai/v1/workspaces/7694",
"autopilot": false,
"organization": "https://api.elis.rossum.ai/v1/organizations/406",
"queues": [],
"metadata": {}
}
PUT /v1/workspaces/{id}
Update workspace object.
Response
Status: 200
Returns updated workspace object.
Update part of a workspace
Update name of workspace object
7694
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "Important Workspace"}' \
'https://api.elis.rossum.ai/v1/workspaces/7694'
{
"id": 7694,
"name": "Important Workspace",
"url": "https://api.elis.rossum.ai/v1/workspaces/7694",
"autopilot": false,
"organization": "https://api.elis.rossum.ai/v1/organizations/406",
"queues": [],
"metadata": {}
}
PATCH /v1/workspaces/{id}
Update part of workspace object.
Response
Status: 200
Returns updated workspace object.
Delete a workspace
Delete workspace
7694
curl -X DELETE -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/workspaces/7694'
DELETE /v1/workspaces/{id}
Delete workspace object.
Response
Status: 204
Queue
Example queue object
{
"id": 8198,
"name": "Received invoices",
"url": "https://api.elis.rossum.ai/v1/queues/8198",
"workspace": "https://api.elis.rossum.ai/v1/workspaces/7540",
"connector": null,
"webhooks": [],
"hooks": [],
"schema": "https://api.elis.rossum.ai/v1/schemas/31336",
"inbox": "https://api.elis.rossum.ai/v1/inboxes/1229",
"users": [
"https://api.elis.rossum.ai/v1/users/10775"
],
"session_timeout": "01:00:00",
"rir_url": "https://all.rir.rossum.ai",
"rir_params": null,
"counts": {
"importing": 0,
"split": 0,
"failed_import": 0,
"to_review": 2,
"reviewing": 0,
"exporting": 0,
"postponed": 0,
"failed_export": 0,
"exported": 0,
"deleted": 0,
"purged": 0
},
"default_score_threshold": 0.975,
"automation_enabled": false,
"automation_level": "never",
"locale": "en_US",
"metadata": {},
"use_confirmed_state": false,
"settings": {
"columns": [{"schema_id": "tags"}],
"hide_export_button": true
}
}
A queue object represents a basic organization unit of annotations. Annotations are imported to a queue either through a REST API upload endpoint or by sending an email to a related inbox. Export is also performed on a queue using export endpoint.
Queue also specifies a schema for annotations and a connector.
Annotators and viewers only see queues they are assigned to.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the queue | true | |
name | string | Name of the queue | ||
url | URL | URL of the queue | true | |
workspace | URL | Workspace in which the queue should be placed | ||
connector | URL | null |
Connector associated with the queue | |
webhooks | list[URL] | [] |
Webhooks associated with the queue (deprecated; serves as an alias for hooks attribute) |
|
hooks | list[URL] | [] |
Hooks associated with the queue | |
schema | URL | Schema which will be applied to annotations in this queue | ||
inbox | URL | null |
Inbox for import to this queue | |
users | list[URL] | [] |
Users associated with this queue | |
session_timeout | timedelta | 1 hour | Time before annotation will be returned from revieving status to to_review |
|
rir_url | URL | null |
URL representing the particular AI Core Engine variant used for document processing. Usually https://all.rir.rossum.ai , will vary for custom model training users. |
|
rir_params | string | null |
URL parameters to be passed to the AI Core Engine, see below | |
counts | object | Count of annotations per status | true | |
default_score_threshold | float [0;1] | 0.975 | Threshold used to automatically validate field content based on AI confidence scores. | |
automation_enabled | bool | false |
Toggle for switching automation on/off | |
automation_level | string | never | Set level of automation, see Automation level. | |
locale | string | en_GB | Typical originating region of documents processed in this queue specified in the locale format, see below. | |
metadata | object | {} |
Client data, see metadata. | |
use_confirmed_state | bool | false |
Affects exporting: when true , confirm endpoint transitions annotation to confirmed status instead to exporting . |
|
settings | object | {} |
Queue UI settings, see settings. |
More specific AI Core Engine parameters influencing the extraction may be set using rir_params
field.
So far, these parameters are publicly available:
effective_page_count
(int): Limits the extraction to the firsteffective_page_count
pages of the document.- Useful to prevent data extraction from additional pages of unrelated, but included documents.
- Default: total number of pages in the document.
tables
(boolean): Allows disabling line item data extraction.- Useful to speed up data extraction when line item details are not required, especially on long documents with large tables.
- Default: true (line items are being extracted).
The locale
field is a hint for the AI Engine on how to resolve some ambiguous cases during data extraction, concerning e.g. date formats or decimal separators that may depend on the locale. For example, in US the typical date format is mm/dd/yyyy whilst in Europe it is dd.mm.yyyy. A date such as "12. 6. 2018" will be extracted as Jun 12 when locale is en_GB
, while the same date will be extracted as Dec 6 when locale is en_US
.
For backward compatibility, webhooks
attribute is an alias of hooks
. If both attributes are specified, webhooks
overrides hooks
. For new integrations, do not specify webhooks
attribute.
Automation level
With queue attribute automation_level
you can set at which circumstances
should be annotation auto-exported after the AI-based data extraction, without
validation in the UI (skipping the to_review
and reviewing
state).
Attribute can have following options:
Automation level | Description |
---|---|
always | Auto-export all documents with no validation errors. When there is an error triggered for a non-required field, such values are deleted and export is re-tried. |
confident | Auto-export documents with at least one validation source and no validation errors. |
never | Annotation is not automatically exported and must be validated in UI manually. |
Settings attribute
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
columns | list[object] | [] | List that contains schema ids to be shown on a dashboard | |
hide_export_button | bool | true |
Toggle to uncover "Export" button on dashboard (useful when queue.use_confirmed_state = true ), which allows manual export of annotations in confirmed status. |
|
autopilot | object | null |
Autopilot configuration describing which fields can be confirmed automatically. | |
accepted_mime_types | list[str] | [] | List of MIME types which can be uploaded to the queue. This can contain wildcards such as image/* or exact type like application/pdf . |
Import a document
Upload file using a form (multipart/form-data)
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-F content=@document.pdf \
'https://api.elis.rossum.ai/v1/queues/8236/upload'
Upload file in a request body
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-H 'Content-Disposition: attachment; filename=document.pdf' --data-binary @file.pdf \
'https://api.elis.rossum.ai/v1/queues/8236/upload'
Upload file in a request body (UTF-8 filename must be URL encoded)
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-H "Content-Disposition: attachment; filename*=utf-8''document%20%F0%9F%8E%81.pdf" --data-binary @file.pdf \
'https://api.elis.rossum.ai/v1/queues/8236/upload'
Upload file in a request body with a filename in URL (UTF-8 filename must be URL encoded)
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
--data-binary @file.pdf \
'https://api.elis.rossum.ai/v1/queues/8236/upload/document%20%F0%9F%8E%81.pdf'
Upload multiple files using multipart/form-data
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-F content=@document1.pdf -F content=@document2.pdf \
'https://api.elis.rossum.ai/v1/queues/8236/upload'
Upload file using basic authentication
curl -u 'east-west-trading-co@elis.rossum.ai:secret' \
-F content=@document.pdf \
'https://api.elis.rossum.ai/v1/queues/8236/upload'
Upload file with additional field values and metadata
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-F content=@document.pdf \
-F values='{"upload:organization_unit":"Sales"}' \
-F metadata='{"project":"Market ABC"}' \
'https://api.elis.rossum.ai/v1/queues/8236/upload'
POST /v1/queues/{id}/upload
POST /v1/queues/{id}/upload/{filename}
Uploads a document to the queue (starting in the importing state). This creates a document object and an empty annotation object.
The file can be sent as a part of multipart/form-data or, alternatively, in the request body. Multiple files upload is supported, the total size of the data uploaded may not exceed 40 MB. UTF-8 filenames are supported, see examples.
You can also specify additional properties using form field:
- metadata could be passed using
metadata
form field. Metadata will be set to newly created annotation object. - values could be passed using
values
form field. It may be used to initialize datapoint values by setting the value ofrir_field_names
in the schema.
For example upload:organization_unit
field may be referenced in a schema like this:
{ "category": "datapoint", "id": "organization_unit", "label": "Org unit", "type": "string", "rir_field_names": ["upload:organization_unit"] ... }
Upload endpoint also supports basic authentication to enable easy integration with third-party systems.
Response
Status: 200
Response contains a list of annotations and documents created. Top-level keys
annotation
and document
are obsolete and should be ignored.
Example upload response
{ "results": [ { "annotation": "https://api.elis.rossum.ai/v1/annotations/315509", "document": "https://api.elis.rossum.ai/v1/documents/315609" }, { "annotation": "https://api.elis.rossum.ai/v1/annotations/315510", "document": "https://api.elis.rossum.ai/v1/documents/315610" } ], "annotation": "https://api.elis.rossum.ai/v1/annotations/315509", "document": "https://api.elis.rossum.ai/v1/documents/315609" }
Export annotations
Download CSV file with selected columns from annotations
315777
and315778
.
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/queues/8236/export?format=csv&columns=meta_file_name,document_id,date_issue,sender_name,amount_total&id=315777,315778'
meta_file_name,Invoice number,Invoice Date,Sender Name,Total amount
template_invoice.pdf,12345,2017-06-01,"Peter, Paul and Merry",900.00
quora.pdf,2183760194,2018-08-06,"Quora, Inc",500.00
Download CSV file with prepend_columns and append_columns from annotations
315777
and315778
.
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/queues/8236/export?format=csv&prepend_columns=meta_file_name&append_columns=meta_url&id=315777,315778'
meta_file_name,Invoice number,Invoice Date,Sender Name,Total amount,meta_url
template_invoice.pdf,12345,2017-06-01,"Peter, Paul and Merry",900.00,https://api.elis.rossum.ai/v1/annotations/315777
quora.pdf,2183760194,2018-08-06,"Quora, Inc",500.00,https://api.elis.rossum.ai/v1/annotations/315778
Download CSV file for a specific page when downloading large amounts of data.
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/queues/8236/export?format=csv&status=exported&page=1&page_size=1000'
Download XML file with all exported annotations
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/queues/8236/export?format=xml&status=exported'
<?xml version="1.0" encoding="utf-8"?>
<export>
<results>
<annotation url="https://api.elis.rossum.ai/v1/annotations/315777">
<status>exported</status>
<arrived_at>2019-10-13T21:33:01.509886Z</arrived_at>
<exported_at>2019-10-13T12:00:01.000133Z</exported_at>
<document url="https://api.elis.rossum.ai/v1/documents/315877">
<file_name>template_invoice.pdf</file_name>
<file>https://api.elis.rossum.ai/v1/documents/315877/content</file>
</document>
<modifier/>
<schema url="https://api.elis.rossum.ai/v1/schemas/31336"/>
<metadata/>
<content>
<section schema_id="invoice_details_section">
<datapoint schema_id="document_id" type="string" rir_confidence="0.99">12345</datapoint>
...
</section>
</content>
</annotation>
</results>
<pagination>
<next/>
<previous/>
<total>1</total>
<total_pages>1</total_pages>
</pagination>
</export>
Download JSON file with all exported annotations that were imported on October 13th 2019.
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/queues/8236/export?format=json&status=exported&arrived_at_after=2019-10-13&arrived_at_before=2019-10-14'
{
"pagination": {
"total": 5,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"url": "https://api.elis.rossum.ai/v1/annotations/315777",
"status": "exported",
"arrived_at": "2019-10-13T21:33:01.509886Z",
"exported_at": "2019-10-14T12:00:01.000133Z",
"document": {
"url": "https://api.elis.rossum.ai/v1/documents/315877",
"file_name": "template_invoice.pdf",
"file": "https://api.elis.rossum.ai/v1/documents/315877/content"
},
"modifier": null,
"schema": {
"url": "https://api.elis.rossum.ai/v1/schemas/31336"
},
"metadata": {},
"content": [
{
"category": "section",
"schema_id": "invoice_details_section",
"children": [
{
"category": "datapoint",
"schema_id": "document_id",
"value": "12345",
"type": "string",
"rir_confidence": 0.99
},
...
]
}
]
}
]
}
Download and set the status of annotations to
exporting
.
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/queues/8236/export?to_status=exporting&status=confirmed'
{
"pagination": {
"total": 5,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"status": "exporting",
...
}
]
}
GET /v1/queues/{id}/export
or POST /v1/queues/{id}/export
Export annotations from the queue in XML, CSV or JSON format.
Output format is negotiated by Accept header or format
parameter. Supported formats are: csv
, xml
, xlsx
and json
.
Filters
Filters may be specified to limit annotations to be exported, all filters applicable to the annotation list are supported. Multiple filter attributes are combined with AND, which results in more specific response.
The most common filters are either list of ids or specifying a time period:
Attribute | Description |
---|---|
id | Id of annotation to be exported, multiple ids may be separated by a comma. |
status | Annotation status |
modifier | User id |
arrived_at_before | ISO 8601 timestamp (e.g. arrived_at_before=2019-11-15 ) |
arrived_at_after | ISO 8601 timestamp (e.g. arrived_at_after=2019-11-14 ) |
exported_at_before | ISO 8601 timestamp (e.g. exported_at_before=2019-11-14 22:00:00 ) |
exported_at_after | ISO 8601 timestamp (e.g. exported_at_after=2019-11-14 12:00:00 ) |
page_size | Number of the documents to be exported. To be used together with page attribute. See pagination. |
page | Number of a page to be exported when using pagination. Useful for exports of large amounts of data. To be used together with the page_size attribute. |
to_status | status of annotations under export is switched to defined to_status state (useful when queue.use_confirmed_state = true ). This parameter is only valid with POST method, status can be changed only to exporting or exported . Annotations with current status exported or exporting are left untouched. |
Response
Status: 200
Returns paginated response that contains annotation data in one of the following format.
CSV
Columns included in CSV output are defined by columns
, prepend_columns
and append_columns
URL parameters.
prepend_columns
parameter defines columns at the beginning of the row while append_columns
at the end. All stated parameters
are specified by datapoint schema ids and meta-columns. Default is to export
all fields defined in a schema.
Supported meta-columns are: meta_arrived_at
, meta_file
, meta_file_name
, meta_status
, meta_url
, meta_automated
, meta_modified_at
, meta_assigned_at
.
XLSX
XLSX export behaves exactly same as CSV export, including URL parameters. The only difference is output format.
XML
XML format is described by XML Schema Definition queues_export.xsd.
JSON
JSON format uses format similar to the XML format above.
List all queues
List all queues in workspace
7540
ordered byname
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/queues?workspace=7540&ordering=name'
{
"pagination": {
"total": 2,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 8199,
"name": "Receipts",
"url": "https://api.elis.rossum.ai/v1/queues/8199",
"workspace": "https://api.elis.rossum.ai/v1/workspaces/7540",
...
},
{
"id": 8198,
"name": "Received invoices",
"url": "https://api.elis.rossum.ai/v1/queues/8198",
"workspace": "https://api.elis.rossum.ai/v1/workspaces/7540",
...
}
]
}
GET /v1/queues
Retrieve all queue objects.
Supported ordering: id
, name
, workspace
, connector
, webhooks
, schema
, inbox
, locale
Filters
Attribute | Description |
---|---|
id | Id of a queue |
name | Name of a queue |
workspace | Id of a workspace |
inbox | Id of an inbox |
connector | Id of a connector |
webhooks | Ids of hooks |
hooks | Ids of hooks |
locale | Queue object locale |
Response
Status: 200
Returns paginated response with a list of queue objects.
Create new queue
Create new queue in workspace
7540
named Test Queue
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "Test Queue", "workspace": "https://api.elis.rossum.ai/v1/workspaces/7540", "schema": "https://api.elis.rossum.ai/v1/schemas/31336"}' \
'https://api.elis.rossum.ai/v1/queues'
{
"id": 8236,
"name": "Test Queue",
"url": "https://api.elis.rossum.ai/v1/queues/8236",
"workspace": "https://api.elis.rossum.ai/v1/workspaces/7540",
...
}
POST /v1/queues
Create a new queue object.
Response
Status: 201
Returns created queue object.
Retrieve a queue
Get queue object
8198
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/queues/8198'
{
"id": 8198,
"name": "Received invoices",
"url": "https://api.elis.rossum.ai/v1/queues/8198",
"workspace": "https://api.elis.rossum.ai/v1/workspaces/7540",
...
}
GET /v1/queues/{id}
Get a queue object.
Response
Status: 200
Returns queue object.
Update a queue
Update queue object
8236
curl -X PUT -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "My Queue", "workspace": "https://api.elis.rossum.ai/v1/workspaces/7540", "schema": "https://api.elis.rossum.ai/v1/schemas/31336"}' \
'https://api.elis.rossum.ai/v1/queues/8236'
{
"id": 8236,
"name": "My Queue",
"url": "https://api.elis.rossum.ai/v1/queues/8236",
"workspace": "https://api.elis.rossum.ai/v1/workspaces/7540",
...
}
PUT /v1/queues/{id}
Update queue object.
Response
Status: 200
Returns updated queue object.
Update part of a queue
Update name of queue object
8236
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "New Queue"}' \
'https://api.elis.rossum.ai/v1/queues/8236'
{
"id": 8236,
"name": "New Queue",
"url": "https://api.elis.rossum.ai/v1/queues/8236",
"workspace": "https://api.elis.rossum.ai/v1/workspaces/7540",
...
}
PATCH /v1/queues/{id}
Update part of queue object.
Response
Status: 200
Returns updated queue object.
Delete a queue
Delete queue
8236
curl -X DELETE -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/queues/8236'
DELETE /v1/queues/{id}
Delete queue object.
Response
Status: 204
Assign annotation
POST /v1/queues/{id}/next
Assign calling user an available annotation from the queue.
This endpoint is INTERNAL and may change in the future.
Inbox
Example inbox object
{
"id": 1234,
"name": "Receipts",
"url": "https://api.elis.rossum.ai/v1/inboxes/1234",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"email": "east-west-trading-co-a34f3a@elis.rossum.ai",
"email_prefix": "east-west-trading-co",
"bounce_email_to": "bounces@east-west.com",
"bounce_unprocessable_attachments": false,
"bounce_deleted_annotations": false,
"metadata": {}
}
An inbox object enables email ingestion to a related queue. We
enforce email
domain to match Rossum domain (e.g. elis.rossum.ai).
email_prefix
may be used to construct unique email address.
Please note that due to security reasons, emails from Rossum do not contain processed files.
This feature can be be enabled upon request by customer support.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the inbox | true | |
name | string | Name of the inbox (not visible in UI) | ||
url | URL | URL of the inbox | true | |
queues | list[URL] | Queue that receives documents from inbox. Queue has to be passed in list due to backward compatibility. It is possible to have only one queue per inbox. | ||
Rossum email address (e.g. east-west-trading-co-a34f3a@elis.rossum.ai ) |
||||
email_prefix | string | Rossum email address prefix (e.g. east-west-trading-co ) |
||
bounce_email_to | Email address to send notifications to (e.g. about failed import). | |||
bounce_unprocessable_attachments | bool | false |
Whether return back unprocessable attachments (e.g. MS Word docx) or just silently ignore them. When true, minimum image size requirement does not apply. | |
bounce_postponed_annotations | bool | false |
Whether to send notification when annotation is postponed. | |
bounce_deleted_annotations | bool | false |
Whether to send notification when annotation is deleted. | |
metadata | object | {} |
Client data, see metadata. |
List all inboxes
List all inboxes
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/inboxes'
{
"pagination": {
"total": 2,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 1234,
"name": "Receipts",
"url": "https://api.elis.rossum.ai/v1/inboxes/1234",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"email": "east-west-trading-co-recepits@elis.rossum.ai",
"email_prefix": "east-west-trading-co-recepits",
"bounce_email_to": "bounces@east-west.com",
"bounce_unprocessable_attachments": false,
"bounce_deleted_annotations": false,
"metadata": {}
},
{
"id": 1244,
"name": "Beta Inbox",
"url": "https://api.elis.rossum.ai/v1/inboxes/1244",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8236"
],
"email": "east-west-trading-co-beta@elis.rossum.ai",
"email_prefix": "east-west-trading-co-beta",
"bounce_email_to": "bill@east-west.com",
"bounce_unprocessable_attachments": false,
"bounce_deleted_annotations": false,
"metadata": {}
}
]
}
GET /v1/inboxes
Retrieve all inbox objects.
Supported filters: id
, name
, email
, email_prefix
, bounce_email_to
, bounce_unprocessable_attachments
, bounce_postponed_annotations
, bounce_deleted_annotations
Supported ordering: id
, name
, email
, email_prefix
, bounce_email_to
Response
Status: 200
Returns paginated response with a list of inbox objects.
Create a new inbox
Create new inbox related to queue
8236
named Test Inbox
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "Test Inbox", "email_prefix": "east-west-trading-co-test", "bounce_email_to": "joe@east-west-trading.com", "queues": ["https://api.elis.rossum.ai/v1/queues/8236"]}' \
'https://api.elis.rossum.ai/v1/inboxes'
{
"id": 1244,
"name": "Test Inbox",
"url": "https://api.elis.rossum.ai/v1/inboxes/1244",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8236"
],
"email": "east-west-trading-co-test-b21e3a@elis.rossum.ai",
"email_prefix": "east-west-trading-co-test",
"bounce_email_to": "joe@east-west-trading.com",
"bounce_unprocessable_attachments": false,
"bounce_postponed_annotations": false,
"bounce_deleted_annotations": false,
"metadata": {}
}
POST /v1/inboxes
Create a new inbox object.
Response
Status: 201
Returns created inbox object.
Retrieve a inbox
Get inbox object
1244
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/inboxes/1244'
{
"id": 1244,
"name": "Test Inbox",
"url": "https://api.elis.rossum.ai/v1/inboxes/1244",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8236"
],
"email": "east-west-trading-co-beta@elis.rossum.ai",
...
}
GET /v1/inboxes/{id}
Get an inbox object.
Response
Status: 200
Returns inbox object.
Update a inbox
Update inbox object
1244
curl -X PUT -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "Shiny Inbox", "email": "east-west-trading-co-test@elis.rossum.ai", "bounce_email_to": "jack@east-west-trading.com", "queues": ["https://api.elis.rossum.ai/v1/queues/8236"]}' \
'https://api.elis.rossum.ai/v1/inboxes/1244'
{
"id": 1244,
"name": "Shiny Inbox",
"url": "https://api.elis.rossum.ai/v1/inboxes/1244",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8236"
],
"email": "east-west-trading-co-test@elis.rossum.ai",
"bounce_email_to": "jack@east-west-trading.com",
...
}
PUT /v1/inboxes/{id}
Update inbox object.
Response
Status: 200
Returns updated inbox object.
Update part of a inbox
Update email of inbox object
1244
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "Common Inbox"}' \
'https://api.elis.rossum.ai/v1/inboxes/1244'
{
"id": 1244,
"name": "Common Inbox",
...
}
PATCH /v1/inboxes/{id}
Update part of inbox object.
Response
Status: 200
Returns updated inbox object.
Delete a inbox
Delete inbox
1244
curl -X DELETE -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/inboxes/1244'
DELETE /v1/inboxes/{id}
Delete inbox object.
Response
Status: 204
Connector
Example connector object
{
"id": 1500,
"name": "MyQ Connector",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"url": "https://api.elis.rossum.ai/v1/connectors/1500",
"service_url": "https://myq.east-west-trading.com",
"params": "strict=true",
"client_ssl_certificate": "-----BEGIN CERTIFICATE-----\n...",
"authorization_token": "wuNg0OenyaeK4eenOovi7aiF",
"asynchronous": true,
"metadata": {}
}
A connector is an extension of Rossum that allows to validate and modify data during validation and also export data to an external system. A connector object is used to configure external or internal endpoint of such an extension service. For more information see Extensions.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the connector | true | |
name | string | Name of the connector (not visible in UI) | ||
url | URL | URL of the connector | true | |
queues | list[URL] | List of queues that use connector object. | ||
service_url | URL | URL of the connector endpoint | ||
params | string | Query params appended to the service_url | ||
client_ssl_certificate | string | Client SSL certificate used to authenticate requests. Must be PEM encoded. | ||
client_ssl_key | string | Client SSL key (write only). Must be PEM encoded. Key may not be encrypted. | ||
authorization_type | string | secret_key |
String sent in HTTP header Authorization could be set to secret_key or Basic . For details see Connector API. |
|
authorization_token | string | Token sent to connector in Authorization header to ensure connector was contacted by Rossum (displayed only to admin user). |
||
asynchronous | bool | true |
Affects exporting: when true , confirm endpoint returns immediately and connector's save endpoint is called asynchronously later on. |
|
metadata | object | {} |
Client data, see metadata. |
List all connectors
List all connectors
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/connectors'
{
"pagination": {
"total": 1,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 1500,
"name": "MyQ Connector",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"url": "https://api.elis.rossum.ai/v1/connectors/1500",
"service_url": "https://myq.east-west-trading.com",
"params": "strict=true",
"client_ssl_certificate": null,
"authorization_token": "wuNg0OenyaeK4eenOovi7aiF",
"asynchronous": true,
"metadata": {}
}
]
}
GET /v1/connectors
Retrieve all connector objects.
Supported filters: id
, name
, service_url
Supported ordering: id
, name
, service_url
Response
Status: 200
Returns paginated response with a list of connector objects.
Create a new connector
Create new connector related to queue
8199
with endpoint URLhttps://myq.east-west-trading.com
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "MyQ Connector", "queues": ["https://api.elis.rossum.ai/v1/queues/8199"], "service_url": "https://myq.east-west-trading.com", "authorization_token":"wuNg0OenyaeK4eenOovi7aiF"}' \
'https://api.elis.rossum.ai/v1/connectors'
{
"id": 1500,
"name": "MyQ Connector",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"url": "https://api.elis.rossum.ai/v1/connectors/1500",
"service_url": "https://myq.east-west-trading.com",
"params": null,
"client_ssl_certificate": null,
"authorization_token": "wuNg0OenyaeK4eenOovi7aiF",
"asynchronous": true,
"metadata": {}
}
POST /v1/connectors
Create a new connector object.
Response
Status: 201
Returns created connector object.
Retrieve a connector
Get connector object
1500
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/connectors/1500'
{
"id": 1500,
"name": "MyQ Connector",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"url": "https://api.elis.rossum.ai/v1/connectors/1500",
"service_url": "https://myq.east-west-trading.com",
"params": null,
"client_ssl_certificate": null,
"authorization_token": "wuNg0OenyaeK4eenOovi7aiF",
"asynchronous": true,
"metadata": {}
}
GET /v1/connectors/{id}
Get an connector object.
Response
Status: 200
Returns connector object.
Update a connector
Update connector object
1500
curl -X PUT -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "MyQ Connector (stg)", "queues": ["https://api.elis.rossum.ai/v1/queues/8199"], "service_url": "https://myq.stg.east-west-trading.com", "authorization_token":"wuNg0OenyaeK4eenOovi7aiF"} \
'https://api.elis.rossum.ai/v1/connectors/1500'
{
"id": 1500,
"name": "MyQ Connector (stg)",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"url": "https://api.elis.rossum.ai/v1/connectors/1500",
"service_url": "https://myq.stg.east-west-trading.com",
"params": null,
"client_ssl_certificate": null,
"authorization_token": "wuNg0OenyaeK4eenOovi7aiF",
"asynchronous": true,
"metadata": {}
}
PUT /v1/connectors/{id}
Update connector object.
Response
Status: 200
Returns updated connector object.
Update part of a connector
Update connector URL of connector object
1500
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"service_url": "https://myq.stg2.east-west-trading.com"}' \
'https://api.elis.rossum.ai/v1/connectors/1500'
{
"id": 1500,
"name": "MyQ Connector",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"url": "https://api.elis.rossum.ai/v1/connectors/1500",
"service_url": "https://myq.stg2.east-west-trading.com",
"params": null,
"client_ssl_certificate": null,
"authorization_token": "wuNg0OenyaeK4eenOovi7aiF",
"asynchronous": true,
"metadata": {}
}
PATCH /v1/connectors/{id}
Update part of connector object.
Response
Status: 200
Returns updated connector object.
Delete a connector
Delete connector
1500
curl -X DELETE -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/connectors/1500'
DELETE /v1/connectors/{id}
Delete connector object.
Response
Status: 204
Webhook
Hook
Example hook object of type webhook
{
"id": 1500,
"type": "webhook",
"url": "https://api.elis.rossum.ai/v1/hooks/1500",
"name": "Change of Status",
"metadata": {},
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199",
"https://api.elis.rossum.ai/v1/queues/8191"
],
"sideload": ["queues"],
"active": true,
"events": [
"annotation_status"
],
"config": {
"url": "https://myq.east-west-trading.com/api/hook1?strict=true",
"secret": "secret-token",
"insecure_ssl": false,
"client_ssl_certificate": "-----BEGIN CERTIFICATE-----\n..."
},
"test": {
"saved_input": {...}
}
}
Example hook object of type function
{
"id": 1500,
"type": "function",
"url": "https://api.elis.rossum.ai/v1/hooks/1500",
"name": "Empty function",
"metadata": {},
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199",
"https://api.elis.rossum.ai/v1/queues/8191"
],
"sideload": ["modifiers"],
"active": true,
"events": [
"annotation_content"
],
"config": {
"runtime": "nodejs12.x",
"code": "exports.rossum_hook_request_handler = () => {\nconst messages = [{\"type\": \"info\", \"content\": \"Yup!\"}];\nconst operations = [];\nreturn {\nmessages,\noperations\n};\n};"
},
"test": {
"saved_input": {...}
},
"status": "ready"
}
A hook is an extension of Rossum that is notified when specific event occurs. A hook object is used to configure what endpoint or function is executed and when. For an overview of other extension options see Extensions.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the hook | true | |
type | string | webhook | Hook type. Possible values: webhook , function |
|
name | string | Name of the hook | ||
url | URL | URL of the hook | true | |
queues | list[URL] | List of queues that use hook object. | ||
active | bool | If set to true the hook is notified. |
||
events | list[string] | List of events, when the hook should be notified. For the list of events see Webhook events. | ||
sideload | list[string] | [] |
List of related objects that should be included in hook request. For the list of possible sideloads see Webhook events. | |
metadata | object | {} |
Client data, see metadata. | |
config | object | Configuration of the hook. | ||
test | object | {} |
Input saved for hook testing purposes, see Test a hook |
Config attribute
Config attribute allows to specify per-type configuration.
Webhook config
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
url | URL | URL of the webhook endpoint to call | ||
secret | string | (optional) If set, it is used to create a hash signature with each payload. For more information see Validating payloads from Rossum | ||
insecure_ssl | bool | false |
Disable SSL certificate verification (only use for testing purposes). | |
client_ssl_certificate | string | Client SSL certificate used to authenticate requests. Must be PEM encoded. | ||
client_ssl_key | string | Client SSL key (write only). Must be PEM encoded. Key may not be encrypted. |
Function config
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
runtime | string | Runtime used to execute code. Allowed values: nodejs12.x |
||
code | string | String-serialized source code to be executed |
Function specific attributes
Attribute | Type | Description | Read-only |
---|---|---|---|
status | string | Status indicates whether the function is ready to be invoked or modified. Possible values are ready or pending . While the state is pending , invocations and other API actions that operate on the function return status 400. |
True |
List all hooks
List all hooks
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/hooks'
{
"pagination": {
"total": 1,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 1500,
"type": "webhook",
"url": "https://api.elis.rossum.ai/v1/hooks/1500",
"name": "Some Hook",
"metadata": {},
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199",
"https://api.elis.rossum.ai/v1/queues/8191"
],
"active": true,
"events": [
"annotation_status"
],
"config": {
"url": "https://myq.east-west-trading.com/api/hook1?strict=true"
},
"test": {
"saved_input": {...}
}
}
]
}
GET /v1/hooks
Retrieve all hook objects.
Supported filters: id
, name
, type
, queues
, active
, config_url
Supported ordering: id
, name
, type
, active
, config_url
, events
Response
Status: 200
Returns paginated response with a list of hook objects.
Create a new hook
Create new hook related to queue
8199
with endpoint URLhttps://myq.east-west-trading.com
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "MyQ Hook", "queues": ["https://api.elis.rossum.ai/v1/queues/8199"], "config": {"url": "https://myq.east-west-trading.com"}, "events": []}' \
'https://api.elis.rossum.ai/v1/hooks'
{
"id": 1501,
"type": "webhook",
"url": "https://api.elis.rossum.ai/v1/hooks/1501",
"name": "MyQ Hook",
"metadata": {},
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"active": true,
"events": [],
"config": {
"url": "https://myq.east-west-trading.com"
},
"test": {}
}
POST /v1/hooks
Create a new hook object.
Response
Status: 201
Returns created hook object.
Retrieve a hook
Get hook object
1500
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/hooks/1500'
{
"id": 1500,
"url": "https://api.elis.rossum.ai/v1/hooks/1500",
"name": "Some Hook",
"metadata": {},
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199",
"https://api.elis.rossum.ai/v1/queues/8191"
],
"active": true,
"events": [
"annotation_status"
],
"config": {
"url": "https://myq.east-west-trading.com/api/hook1?strict=true"
},
"test": {}
}
GET /v1/hooks/{id}
Get an hook object.
Response
Status: 200
Returns hook object.
Update a hook
Update hook object
1500
curl -X PUT -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "MyQ Hook (stg)", "queues": ["https://api.elis.rossum.ai/v1/queues/8199"], "config": {"url": "https://myq.stg.east-west-trading.com"}, "events": []} \
'https://api.elis.rossum.ai/v1/hooks/1500'
{
"id": 1500,
"url": "https://api.elis.rossum.ai/v1/hooks/1500",
"name": "MyQ Hook (stg)",
"metadata": {},
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199"
],
"active": true,
"events": [],
"config": {
"url": "https://myq.stg.east-west-trading.com"
},
"test": {}
}
PUT /v1/hooks/{id}
Update hook object.
Response
Status: 200
Returns updated hook object.
Update part of a hook
Update hook URL of hook object
1500
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"config": {"url": "https://myq.stg2.east-west-trading.com"}}' \
'https://api.elis.rossum.ai/v1/hooks/1500'
{
"id": 1500,
"url": "https://api.elis.rossum.ai/v1/hooks/1500",
"name": "Some Hook",
"metadata": {},
"queues": [
"https://api.elis.rossum.ai/v1/queues/8199",
"https://api.elis.rossum.ai/v1/queues/8191"
],
"active": true,
"events": [
"annotation_status"
],
"config": {
"url": "https://myq.stg2.east-west-trading.com"
},
"test": {}
}
PATCH /v1/hooks/{id}
Update part of hook object.
Response
Status: 200
Returns updated hook object.
Delete a hook
Delete hook
1500
curl -X DELETE -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/hooks/1500'
DELETE /v1/hooks/{id}
Delete hook object.
Response
Status: 204
Test a hook
Call webhook
1500
and display its result
curl 'https://api.elis.rossum.ai/v1/hooks/1500/test' -H 'Content-Type: application/json' -H 'Authorization: Token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-d '{
"config": {
"insecure_ssl": true
},
"payload": {
"action": "user_update",
"event": "annotation_content",
"annotation": {},
"document": {}
}
}'
{"response":{"messages":[],"operations":[]}}
Call serverless function (code may be specified in the request) and display its result
curl 'https://api.elis.rossum.ai/v1/hooks/1501/test' -H 'Content-Type: application/json' -H 'Authorization: Token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-d '{
"config": {
"code": "exports.rossum_hook_request_handler = ..."
},
"payload": {
"action": "user_update",
"event": "annotation_content",
"annotation": {},
"document": {}
}
}'
{"response":{"messages":[],"operations":[]}}
POST /v1/hooks/{id}/test
Test a hook with custom payload.
Attribute | Type | Required | Description |
---|---|---|---|
config | object | false | You can override default configuration of hook being executed. |
payload | object | true | Payload sent to the Hook, please note only supported combination of action and event can be passed. |
Test endpoint will return result generated by your Hook which would be normally processed by Elis.
Schema
Example schema object
{
"id": 31336,
"name": "Basic Schema",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8236"
],
"url": "https://api.elis.rossum.ai/v1/schemas/31336",
"content": [
{
"category": "section",
"id": "invoice_details_section",
"label": "Invoice details",
"children": [
{
"category": "datapoint",
"id": "document_id",
"label": "Invoice number",
"type": "string",
"rir_field_names": [
"document_id"
],
"constraints": {
"required": false
},
"default_value": null
}
...
]
},
...
],
"metadata": {}
}
A schema object specifies the set of datapoints that are extracted from the document. For more information see Document Schema.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the schema | true | |
name | string | Name of the schema (not visible in UI) | ||
url | URL | URL of the schema | true | |
queues | list[URL] | List of queues that use schema object. | true | |
content | list[object] | List of sections (top-level schema objects, see Document Schema for description of schema) | ||
metadata | object | {} |
Client data, see metadata. |
Validate a schema
Validate content of schema object
33725
curl -X PUT -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"content":[{"category":"section","id":"invoice_details_section","label":"Invoice details","icon": null,"children":[{"category":"datapoint","id":"document_id","label":"Invoice number","type":"string","rir_field_names":["document_id"]}]}]}' \
'https://api.elis.rossum.ai/v1/schemas/33725'
POST /v1/schemas/validate
Validate schema object, check for errors.
Response
Status: 200
or 400
Returns 400 and error description in case of validation failure.
List all schemas
List all schemas
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/schemas'
{
"pagination": {
"total": 2,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 31336,
"url": "https://api.elis.rossum.ai/v1/schemas/31336"
},
{
"id": 33725,
"url": "https://api.elis.rossum.ai/v1/schemas/33725"
}
]
}
GET /v1/schemas
Retrieve all schema objects.
Supported filters: id
, name
Supported ordering: id
Response
Status: 200
Returns paginated response with a list of schema objects.
Create a new schema
Create new empty schema
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "Test Schema", "content": []}' \
'https://api.elis.rossum.ai/v1/schemas'
{
"id": 33725,
"name": "Test Schema",
"queues": [],
"url": "https://api.elis.rossum.ai/v1/schemas/33725",
"content": [],
"metadata": {}
}
POST /v1/schemas
Create a new schema object.
Response
Status: 201
Returns created schema object.
Create schema from template organization
Create new schema object from template organization, see available templates in organization.
Create new schema object from template organization
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name": "Test Schema", "template_name": "EU Demo Template"}' \
'https://api.elis.rossum.ai/v1/schemas/from_template'
{
"name": "Test Schema",
"id": 33726,
"queues": [],
"url": "https://api.elis.rossum.ai/v1/schemas/33726",
"content": [
{
"id": "invoice_info_section",
"icon": null,
"label": "Basic information",
"category": "section",
"children": [
...
],
"metadata": {}
}
POST /v1/schemas/from_template
Create a new schema object.
Response
Status: 201
Returns created schema object.
Retrieve a schema
Get schema object
31336
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/schemas/31336'
{
"id": 31336,
"name": "Basic schema",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8236"
],
"url": "https://api.elis.rossum.ai/v1/schemas/31336",
"content": [
{
"category": "section",
"id": "invoice_details_section",
"label": "Invoice details",
"children": [
{
"category": "datapoint",
"id": "document_id",
"label": "Invoice number",
"type": "string",
"rir_field_names": [
"document_id"
],
"constraints": {
"required": false
},
"default_value": null
},
...
]
},
...
]
}
GET /v1/schemas/{id}
Get a schema object.
Response
Status: 200
Returns schema object.
Update a schema
Update content of schema object
33725
curl -X PUT -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"name":"Test Schema","content":[{"category":"section","id":"invoice_details_section","label":"Invoice details","icon": null,"children":[{"category":"datapoint","id":"document_id","label":"Invoice number","type":"string","rir_field_names":["document_id"]}]}]}' \
'https://api.elis.rossum.ai/v1/schemas/33725'
{
"id": 33725,
"name": "Test Schema",
"queues": [],
"url": "https://api.elis.rossum.ai/v1/schemas/33725",
"content": [
{
"category": "section",
"id": "invoice_details_section",
"label": "Invoice details",
"children": [
{
"category": "datapoint",
"id": "document_id",
"label": "Invoice number",
"type": "string",
"rir_field_names": [
"document_id"
],
"default_value": null
}
],
"icon": null
}
],
"metadata": {}
}
PUT /v1/schemas/{id}
Update schema object. See Updating schema for more details about consequences of schema update.
Response
Status: 200
Returns updated schema object.
Update part of a schema
Update schema object
31336
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"content":[{"category":"section","id":"invoice_details_section","label":"Invoice details","icon": null,"children":[{"category":"datapoint","id":"document_id","label":"Invoice number","type":"string","rir_field_names":["document_id"]}]}]}' \
'https://api.elis.rossum.ai/v1/schemas/31336'
{
"id": 31336,
"name": "New Schema",
"queues": [
"https://api.elis.rossum.ai/v1/queues/8236"
],
"url": "https://api.elis.rossum.ai/v1/schemas/31336",
"content": [],
"metadata": {}
}
PATCH /v1/schemas/{id}
Update part of schema object. See Updating schema for more details about consequences of schema update.
Response
Status: 200
Returns updated schema object.
Delete a schema
Delete schema
31336
curl -X DELETE -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/schemas/31336'
DELETE /v1/schemas/{id}
Delete schema object.
Response
Status: 204
Document
Example document object
{
"id": 314628,
"url": "https://api.elis.rossum.ai/v1/documents/314628",
"s3_name": "272c2f01ae84a4e19a421cb432e490bb",
"annotations": [
"https://api.elis.rossum.ai/v1/annotations/314528"
],
"mime_type": "application/pdf",
"arrived_at": "2019-10-13T23:04:00.933658Z",
"original_file_name": "test_invoice_1.pdf",
"content": "https://api.elis.rossum.ai/v1/documents/314628/content",
"metadata": {}
}
A document object contains information about one input file. It cannot be created through the API, you need to use queue upload endpoint.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the document | true | |
url | URL | URL of the document | true | |
s3_name | string | Internal | true | |
annotations | list[URL] | List of annotations related to the document. Usually there is only one annotation. | true | |
mime_type | string | MIME type of the document (e.g. application/pdf ) |
true | |
arrived_at | datetime | Timestamp of document upload or incoming email attachment extraction. | true | |
original_file_name | string | File name of the attachment or upload. | true | |
content | URL | Link to the document raw content (e.g. PDF file) | true | |
metadata | object | {} |
Client data, see metadata. |
List all documents
List all documents
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/documents'
{
"pagination": {
"total": 2,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 314628,
"url": "https://api.elis.rossum.ai/v1/documents/314628",
"s3_name": "272c2f01ae84a4e19a421cb432e490bb",
"annotations": [
"https://api.elis.rossum.ai/v1/annotations/314528"
],
"mime_type": "application/pdf",
"arrived_at": "2019-10-13T23:04:00.933658Z",
"original_file_name": "test_invoice_1.pdf",
"content": "https://api.elis.rossum.ai/v1/documents/314628/content",
"metadata": {}
},
{
"id": 315609,
"url": "https://api.elis.rossum.ai/v1/documents/315609",
"s3_name": "8e506763caa2bc03f09cba3bf4817f84",
"annotations": [
"https://api.elis.rossum.ai/v1/annotations/315509"
],
"mime_type": "image/png",
"arrived_at": "2019-10-13T16:16:30.726217Z",
"original_file_name": "test_invoice_2.png",
"content": "https://api.elis.rossum.ai/v1/documents/315609/content",
"metadata": {}
}
]
}
GET /v1/documents
Retrieve all document objects.
Supported filters: id
, arrived_at
, original_file_name
Supported ordering: id
, arrived_at
, original_file_name
, s3_name
, mime_type
Response
Status: 200
Returns paginated response with a list of document objects.
Retrieve a document
Get document object
314628
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/documents/314628'
{
"id": 314628,
"url": "https://api.elis.rossum.ai/v1/documents/314628",
"s3_name": "272c2f01ae84a4e19a421cb432e490bb",
"annotations": [
"https://api.elis.rossum.ai/v1/annotations/314528"
],
"mime_type": "application/pdf",
"arrived_at": "2019-10-13T23:04:00.933658Z",
"original_file_name": "test_invoice_1.pdf",
"content": "https://api.elis.rossum.ai/v1/documents/314628/content",
"metadata": {}
}
GET /v1/documents/{id}
Get a document object.
Response
Status: 200
Returns document object.
Permanent URL
Download document original from a permanent URL
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/original/272c2f01ae84a4e19a421cb432e490bb'
GET /v1/original/272c2f01ae84a4e19a421cb432e490bb
Get original document content (e.g. PDF file).
Response
Status: 200
Returns original document file.
Delete a document
Delete document
314628
curl -X DELETE -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/documents/314628'
DELETE /v1/documents/{id}
Delete a document object from the database. It also deletes the related annotation and page objects.
Never call this internal API, mark the annotation as deleted instead.
Response
Status: 204
Annotation
Example annotation object
{
"document": "https://api.elis.rossum.ai/v1/documents/314628",
"id": 314528,
"queue": "https://api.elis.rossum.ai/v1/queues/8199",
"schema": "https://api.elis.rossum.ai/v1/schemas/95",
"relations": [],
"pages": [
"https://api.elis.rossum.ai/v1/pages/558598"
],
"modifier": null,
"modified_at": null,
"confirmed_at": null,
"exported_at": null,
"assigned_at": null,
"status": "to_review",
"rir_poll_id": "54f6b9ecfa751789f71ddf12",
"messages": null,
"url": "https://api.elis.rossum.ai/v1/annotations/314528",
"content": "https://api.elis.rossum.ai/v1/annotations/314528/content",
"time_spent": 0,
"metadata": {}
}
An annotation object contains all extracted and verified data related to a document. Every document belongs to a queue and is related to the schema object, that defines datapoint types and overall shape of the extracted data.
It cannot be created through the API, you need to use queue upload endpoint.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the annotation | true | |
url | URL | URL of the annotation | true | |
status | enum | Status of the document, see Document Lifecycle for list of value. | ||
document | URL | Related document. | ||
queue | URL | Queues that annotation belongs to. | ||
schema | URL | Schema that defines content shape. | ||
relations | list[URL] | List of relations that annotation belongs to. | ||
pages | list[URL] | List of rendered pages. | true | |
modifier | URL | User that last modified the annotation. | ||
assigned_at | datetime | Timestamp of last assignment to a user. | true | |
modified_at | datetime | Timestamp of last modification. | true | |
confirmed_at | datetime | Timestamp of confirmation by the user. | true | |
exported_at | datetime | Timestamp of finished export. | true | |
rir_poll_id | string | Internal. | ||
messages | list[object] | [] |
List of messages from the connector (save). | |
content | URL | Link to annotation data (datapoint values), see Annotation data. | true | |
suggested_edit | URL | Link to Suggested edit object. | true | |
time_spent | float | 0 | Total time spent while validating the annotation. | |
metadata | object | {} |
Client data, see metadata. | |
automated | boolean | false | Whether annotation was automated |
Start annotation
Start annotation of object
319668
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/319668/start'
{
"annotation": "https://api.elis.rossum.ai/v1/annotations/319668",
"session_timeout": "01:00:00"
}
POST /v1/annotations/{id}/start
Assign the calling user the annotation.
Response
Status: 200
Returns object with annotation
and session_timeout
keys.
Start embedded annotation
Start embedded annotation of object
319668
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"return_url": "https://service.com/return", "cancel_url": "https://service.com/cancel"}' \
'https://api.elis.rossum.ai/v1/annotations/319668/start_embedded'
{
"url": "https://embedded.elis.rossum.ai/document/319668#authToken=1c50ae8552441a2cda3c360c1e8cb6f2d91b14a9"
}
POST /v1/annotations/{id}/start_embedded
Start embedded annotation. It requires two parameters: return_url
and cancel_url
.
Key | Description |
---|---|
return_url | URL browser is redirected to in case of successful user validation (max. length: 256 chars) |
cancel_url | URL browser is redirected to in case of user canceling the validation (max. length: 256 chars) |
max_token_lifetime_s | Duration (in seconds) for which the token will be valid (optional, default: queue's session_timeout , max: 162 hours) |
Response
Status: 200
Returns object with url
that specifies URL to be used in the browser
iframe/popup window. URL includes a token that is valid for this document only
for a limited period of time.
Confirm annotation
Confirm annotation of object
319668
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/319668/confirm'
POST /v1/annotations/{id}/confirm
Confirm annotation, switch status to exported
(or exporting
).
If the confirmed
state is enabled, this call moves the annotation
to the confirmed
status.
Response
Status: 204
Cancel annotation
Cancel annotation of object
319668
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/319668/cancel'
POST /v1/annotations/{id}/cancel
Cancel annotation, switch its status back to to_review
or postponed
.
Response
Status: 204
Switch to postponed
Postpone annotation status of object
319668
topostponed
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/319668/postpone'
POST /v1/annotations/{id}/postpone
Switch annotation status to postpone
.
Response
Status: 204
Switch to deleted
Switch annotation status of object
319668
todeleted
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/319668/delete'
POST /v1/annotations/{id}/delete
Switch annotation status to deleted
. Annotation with status deleted
is still available in Rossum UI.
Response
Status: 204
Rotate the annotation
Rotate the annotation
319668
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-H 'Content-Type:application/json' -d '{"rotation_deg": 270}' \
'https://api.elis.rossum.ai/v1/annotations/319668/rotate"
POST /v1/annotations/{id}/rotate
Rotate a document. It requires one parameter: rotation_deg
.
Status of the annotation is switched to importing
and the extraction phase begins over again.
After the new extraction, the value from rotation_deg
field is copied to pages rotation field rotation_deg
.
Key | Description |
---|---|
rotation_deg | States degrees by which the document shall be rotated. Possible values: 0, 90, 180, 270. |
Response
Status: 204
Edit the annotation
Edit the annotation
319668
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-H 'Content-Type:application/json' -d '{"documents": [{"pages": [{"page": "https://api.elis.rossum.ai/v1/pages/1", "rotation_deg": 90}, {"page": "https://api.elis.rossum.ai/v1/pages/2", "rotation_deg": 90}]}, {"pages": [{"page": "https://api.elis.rossum.ai/v1/pages/2", "rotation_deg": 180}]}]}' \
'https://api.elis.rossum.ai/v1/annotations/319668/edit"
POST /v1/annotations/{id}/edit
Edit a document. It requires parameter documents
that contains description of requested edits for annotations that should be
created from the original annotation. Description of each edit contains list of pages and rotation degree.
Status of the original annotation is switched to split
. Status of the created annotations is importing
and the
extraction phase begins over again.
Key | Description |
---|---|
documents | Documents that should be created from the original annotation. Each document contains list of pages and rotation degree. |
Response
Status: 204
Search for text
Search for text in annotation
319668
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/319668/search?phrase=some'
{
"results": [
{
"rectangle": [
67.15157010915198,
545.9286363906203,
87.99106633081445,
563.4617583852776
],
"page": 1
},
{
"rectangle": [
45.27717884130982,
1060.3084761056693,
66.11667506297229,
1077.8415981003266
],
"page": 1
}
],
"status": "ok"
}
GET /v1/annotations/{id}/search
Search for a phrase in the document.
Argument | Description |
---|---|
phrase | A phrase to search for |
tolerance | Allowed Edit distance from the search phrase. Only used for OCR invoices (images, such as png or PDF with scanned images). |
Response
Status: 200
Returns results
with a list of objects:
Key | Type | Description |
---|---|---|
rectangle | list[float] | Bounding box of an occurrence. |
page | integer | Page of occurrence. |
Convert grid to table data
Convert grid to tabular data in annotation
319623
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/319623/content/37507202/transform_grid_to_datapoints'
POST /v1/annotations/{id}/content/{id of the child node}/transform_grid_to_datapoints
Transform grid structure to tabular data of related multivalue object.
Response
Status: 200
Validate annotation content
Validate the content of annotation
319623
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-H 'Content-Type:application/json' -d '{"updated_datapoint_ids": [37507204]}' \
'https://api.elis.rossum.ai/v1/annotations/319623/content/validate'
{
"messages": [
{
"id": "1038654",
"type": "error",
"content": "required"
},
{
"id": "all",
"type": "error",
"content": "Whole document is invalid."
},
{
"id": "1038456",
"type": "aggregation",
"content": "246.456",
"aggregation_type": "sum",
"schema_id": "vat_detail_tax2",
}
],
"updated_datapoints": [
{
"id": 37507205,
"url": "http://api.elis.rossum.ai/v1/annotations/319623/content/37507205",
"content": {
"value": "new value",
"page": 1,
"position": [
0.0,
1.0,
2.0,
3.0
],
"rir_text": null,
"rir_page": null,
"rir_position": null,
"rir_confidence": null,
"connector_position": [
0.0,
1.0,
2.0,
3.0
],
"connector_text": "new value"
},
"category": "datapoint",
"schema_id": "vat_rate",
"validation_sources": [
"connector",
"history"
],
"time_spent": 0.0,
"options": [
{
"value": "value",
"label": "label"
}
],
"hidden": false
}
]
}
POST /v1/annotations/{id}/content/validate
Validate the content of an annotation.
At first, the content is sent to the validate hook of connected extension.
Then some standard validations (data type
, constraints
are checked) are carried out in Rossum.
Key | Type | Description |
---|---|---|
updated_datapoint_ids | list[int] | List of IDs of datapoints that were changed since last call of this endpoint. |
Response
Status: 200
Key | Type | Description |
---|---|---|
messages | list[object] | Bounding box of an occurrence. |
updated_datapoints | list[object] | Page of occurrence. |
Messages
The message object contains attributes:
Key | Type | Description |
---|---|---|
id | string | ID of the concerned datapoint; "all" for a document-wide issues |
type | enum | One of: error, warning, info or aggregation. |
content | string | A message shown in UI. |
aggregation_type (*) | enum | Type of aggregation (currently supported "sum" aggregation type). |
schema_id (*) | string | Identifier of schema datapoint for which is aggregation computed. |
(*) Attribute present only in message with type "aggregation"
.
Updated datapoints
The updated datapoint object contains the subtrees of datapoints updated from an extension.
List all annotations
List all annotations
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations'
{
"pagination": {
"total": 22,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"document": "https://api.elis.rossum.ai/v1/documents/315877",
"id": 315777,
"queue": "https://api.elis.rossum.ai/v1/queues/8236",
"schema": "https://api.elis.rossum.ai/v1/schemas/31336",
"pages": [
"https://api.elis.rossum.ai/v1/pages/561206"
],
"modifier": null,
"modified_at": null,
"confirmed_at": null,
"exported_at": null,
"assigned_at": null,
"status": "to_review",
"rir_poll_id": "54f6b9ecfa751789f71ddf12",
"messages": null,
"url": "https://api.elis.rossum.ai/v1/annotations/315777",
"content": "https://api.elis.rossum.ai/v1/annotations/315777/content",
"time_spent": 0,
"metadata": {}
},
{
...
}
]
}
GET /v1/annotations
Retrieve all annotation objects.
Supported ordering: document
, document__arrived_at
, document__original_file_name
, modifier
, modifier__username
, queue
, status
, assigned_at
, confirmed_at
, modified_at
, exported_at
Filters
Obtain only annotations with parent annotation 1500
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations?relations__parent=1500'
{
"pagination": {
"total": 2,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"document": "http://api.elis.rossum.ai/v1/documents/2",
"id": 2,
"queue": "http://api.elis.rossum.ai/v1/queues/1",
"schema": "http://api.elis.rossum.ai/v1/schemas/1",
"relations": [
"http://api.elis.rossum.ai/v1/relations/1"
],
...
"url": "http://api.elis.rossum.ai/v1/annotations/2",
...
},
{
"document": "http://api.elis.rossum.ai/v1/documents/3",
"id": 3,
"queue": "http://api.elis.rossum.ai/v1/queues/2",
"schema": "http://api.elis.rossum.ai/v1/schemas/2",
"relations": [
"http://api.elis.rossum.ai/v1/relations/1"
],
...
"url": "http://api.elis.rossum.ai/v1/annotations/3",
...
}
]
}
Filters may be specified to limit annotations to be listed.
Attribute | Description |
---|---|
status | Annotation status, multiple values may be separated using a comma |
id | List of ids separated by a comma |
modifier | User id |
document | Document id |
queue | Queue id |
relations__parent | ID of parent annotation defined in related Relation object |
relations__type | Type of Relation that annotation belongs to |
relations__key | Key of Relation that annotation belongs to |
arrived_at_before | ISO 8601 timestamp (e.g. arrived_at_before=2019-11-15 ) |
arrived_at_after | ISO 8601 timestamp (e.g. arrived_at_after=2019-11-14 ) |
assigned_at_before | ISO 8601 timestamp (e.g. assigned_at_before=2019-11-15 ) |
assigned_at_after | ISO 8601 timestamp (e.g. assigned_at_after=2019-11-14 ) |
confirmed_at_before | ISO 8601 timestamp (e.g. confirmed_at_before=2019-11-15 ) |
confirmed_at_after | ISO 8601 timestamp (e.g. confirmed_at_after=2019-11-14 ) |
modified_at_before | ISO 8601 timestamp (e.g. modified_at_before=2019-11-15 ) |
modified_at_after | ISO 8601 timestamp (e.g. modified_at_after=2019-11-14 ) |
exported_at_before | ISO 8601 timestamp (e.g. exported_at_before=2019-11-14 22:00:00 ) |
exported_at_after | ISO 8601 timestamp (e.g. exported_at_after=2019-11-14 12:00:00 ) |
automated | Boolean |
Query fields
Obtain only subset of annotation attributes
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations?fields=id,url'
{
"pagination": {
"total": 22,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 320332,
"url": "https://api.elis.rossum.ai/v1/annotations/320332"
},
{
"id": 319668,
"url": "https://api.elis.rossum.ai/v1/annotations/319668"
},
...
]
}
In order to obtain only subset of annotation object attributes, one can use query parameter fields
.
Argument | Description |
---|---|
fields | Comma-separated list of attributes to be included in the response. |
fields! | Comma-separated list of attributes to be excluded from the response. |
Sideloading
Sideload documents, modifiers and content
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations?sideload=modifiers,documents,content'
{
"pagination": {
"total": 22,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"document": "https://api.elis.rossum.ai/v1/documents/320432",
"id": 320332,
...,
"modifier": "https://api.elis.rossum.ai/v1/users/10775",
"status": "to_review",
"rir_poll_id": "a898b6bdc8964721b38e0160",
"messages": null,
"url": "https://api.elis.rossum.ai/v1/annotations/320332",
"content": "https://api.elis.rossum.ai/v1/annotations/320332/content",
"time_spent": 0,
"metadata": {}
},
...
],
"documents": [
{
"id": 320432,
"url": "https://api.elis.rossum.ai/v1/documents/320432",
...
},
...
],
"modifiers": [
{
"id": 10775,
"url": "https://api.elis.rossum.ai/v1/users/10775",
...
},
...
],
"content": [
{
"id": 15984,
"category": "section",
...
},
...
]
}
Sideload content filtered by schema_id
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations?sideload=content&content.schema_id=sender_id,vat_detail_tax'
{
"pagination": {
"total": 22,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"document": "https://api.elis.rossum.ai/v1/documents/320432",
"id": 320332,
...,
"modifier": "https://api.elis.rossum.ai/v1/users/10775",
"status": "to_review",
"rir_poll_id": "a898b6bdc8964721b38e0160",
"messages": null,
"url": "https://api.elis.rossum.ai/v1/annotations/320332",
"content": "https://api.elis.rossum.ai/v1/annotations/320332/content",
"time_spent": 0,
"metadata": {}
},
...
],
"content": [
{
"id": 15984,
"category": "datapoint",
"schema_id": "sender_id",
...
},
{
"id": 15985,
"category": "datapoint",
"schema_id": "vat_detail_tax",
...
},
...
]
}
In order to decrease the number of requests necessary for obtaining useful information about
annotations, modifiers and documents can be sideloaded using query parameter sideload
.
This parameter accepts comma-separated list of keywords: modifiers
, documents
, content
.
Then the response is enriched by the requested keys, which contain lists of the sideloaded objects.
Sideloaded content
can be filtered by schema_id
to obtain only a subset of datapoints in content
part of response. Filter on content
can be specified using query parameter content.schema_id
that accepts comma-separated list of required schema_id
s .
Response
Status: 200
Returns paginated response with a list of annotation objects.
Retrieve an annotation
Get annotation object
315777
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/315777'
{
"document": "https://api.elis.rossum.ai/v1/documents/315877",
"id": 315777,
"queue": "https://api.elis.rossum.ai/v1/queues/8236",
"schema": "https://api.elis.rossum.ai/v1/schemas/31336",
"pages": [
"https://api.elis.rossum.ai/v1/pages/561206"
],
"modifier": null,
"modified_at": null,
"confirmed_at": null,
"exported_at": null,
"assigned_at": null,
"status": "to_review",
"rir_poll_id": "54f6b9ecfa751789f71ddf12",
"messages": null,
"url": "https://api.elis.rossum.ai/v1/annotations/315777",
"content": "https://api.elis.rossum.ai/v1/annotations/315777/content",
"time_spent": 0,
"metadata": {}
}
GET /v1/annotations/{id}
Get an annotation object.
Response
Status: 200
Returns annotation object.
Update an annotation
Update annotation object
315777
curl -X PUT -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"document": "https://api.elis.rossum.ai/v1/documents/315877", "queue": "https://api.elis.rossum.ai/v1/queues/8236", "status": "postponed"}' \
'https://api.elis.rossum.ai/v1/annotations/315777'
{
"document": "https://api.elis.rossum.ai/v1/documents/315877",
"id": 315777,
"queue": "https://api.elis.rossum.ai/v1/queues/8236",
...
"status": "postponed",
"rir_poll_id": "a898b6bdc8964721b38e0160",
"messages": null,
"url": "https://api.elis.rossum.ai/v1/annotations/315777",
"content": "https://api.elis.rossum.ai/v1/annotations/315777/content",
"time_spent": 0,
"metadata": {}
}
PUT /v1/annotations/{id}
Update annotation object.
Response
Status: 200
Returns updated annotation object.
Update part of an annotation
Update status of annotation object
315777
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"status": "deleted"}' \
'https://api.elis.rossum.ai/v1/annotations/315777'
{
"document": "https://api.elis.rossum.ai/v1/documents/315877",
"id": 315777,
...
"status": "deleted",
"rir_poll_id": "a898b6bdc8964721b38e0160",
"messages": null,
"url": "https://api.elis.rossum.ai/v1/annotations/315777",
"content": "https://api.elis.rossum.ai/v1/annotations/315777/content",
"time_spent": 0,
"metadata": {}
}
PATCH /v1/annotations/{id}
Update part of annotation object.
Response
Status: 200
Returns updated annotation object.
Copy annotation
Copy annotation
315777
to a queue8236
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"target_queue": "https://api.elis.rossum.ai/v1/queues/8236", "target_status": "to_review"}' \
'https://api.elis.rossum.ai/v1/annotations/315777/copy'
{
"annotation": "https://api.elis.rossum.ai/v1/annotations/320332"
}
POST /v1/annotations/{id}/copy
Make a copy of annotation in another queue. All data and metadata are copied.
Key | Description |
---|---|
target_queue | URL of queue, where the copy should be placed. |
target_status | Status of copied annotation (if not set, it stays the same) |
Response
Status: 200
Returns URL of the new annotation object.
Delete annotation
Delete annotation
315777
curl -X DELETE -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/315777'
DELETE /v1/annotations/{id}
Delete an annotation object from the database. It also deletes the related page objects.
Never call this internal API, mark the annotation as deleted instead.
Response
Status: 204
Annotation Data
Example annotation data
{
"content": [
{
"id": 27801931,
"url": "https://api.elis.rossum.ai/v1/annotations/319668/content/27801931",
"children": [
{
"id": 27801932,
"url": "https://api.elis.rossum.ai/v1/annotations/319668/content/27801932",
"content": {
"value": "2183760194",
"normalized_value": "2183760194",
"page": 1,
"position": [
761,
48,
925,
84
],
"rir_text": "2183760194",
"rir_position": [
761,
48,
925,
84
],
"connector_text": null,
"rir_confidence": 0.99234
},
"category": "datapoint",
"schema_id": "document_id",
"validation_sources": [
"score"
],
"time_spent": 0,
"hidden": false
},
{
"id": 27801933,
"url": "https://api.elis.rossum.ai/v1/annotations/319668/content/27801933",
"content": {
"value": "6/8/2018",
"normalized_value": "2018-08-06",
"page": 1,
"position": [
283,
300,
375,
324
],
"rir_text": "6/8/2018",
"rir_position": [
283,
300,
375,
324
],
"connector_text": null,
"rir_confidence": 0.98279
},
"category": "datapoint",
"schema_id": "date_issue",
"validation_sources": [
"score"
],
"time_spent": 0,
"hidden": false
},
{
"id": 27801934,
"url": "https://api.elis.rossum.ai/v1/annotations/319668/content/27801934",
"content": null,
"category": "datapoint",
"schema_id": "email_button",
"validation_sources": [
"NA"
],
"time_spent": 0,
"hidden": false
},
...
}
]
}
Annotation data is used by the Rossum UI to display annotation data properly. Be
aware that values in attribute value
are not normalized (e.g. numbers, dates) and data structure
may be changed to accommodate UI requirements.
Top level content
contains a list of section objects. results
is currently
a copy of content
and is deprecated.
Section objects:
Attribute | Type | Description | Read-only |
---|---|---|---|
id | int | A unique ID of a given section. | true |
url | URL | URL of the section. | true |
schema_id | string | Reference mapping the object to the schema tree. | |
category | string | section |
|
children | list | Array specifying objects that belong to the section. |
Datapoint, multivalue and tuple objects:
Attribute | Type | Description | Read-only |
---|---|---|---|
id | int | A unique ID of a given object. | true |
url | URL | URL of a given object. | true |
schema_id | string | Reference mapping the object to the schema tree. | |
category | string | Type of the object (datapoint , multivalue or tuple ). |
true |
children | list | Array specifying child objects. Only available for multivalue and tuple categories. |
true |
content | object | (optional) A dictionary of the attributes of a given datapoint (only available for datapoint ) see below for details. |
true |
validation_sources | list[object] | Source of validation of the extracted data, see below. | |
time_spent | float | Total time spent while validating a given node. | true |
hidden | bool | If set to true, the datapoint is not visible in the user interface, but remains stored in the database. | |
grid | object | Specify grid structure, see below for details. Only allowed for multivalue object. |
Content object
Can be null for datapoints of type button
Attribute | Type | Description | Read-only |
---|---|---|---|
value | string | The extracted data of a given node. Maximum length: 1500 UTF characters. | |
normalized_value | string | Normalized value for date and number fields. | true |
page | int | Number of page where the data is situated (see position). | |
position | list | List of the coordinates of the label box of the given node. | |
rir_text | string | The extracted text, used as a reference for data extraction models. | true |
rir_page | int | The extracted page, used as a reference for data extraction models. | true |
rir_position | list | The extracted position, used as a reference for data extraction models. | true |
rir_confidence | float | Confidence (estimated probability) that this field was extracted correctly. | true |
connector_text | string | Text set by the connector. | true |
connector_position | list | Position set by the connector. | true |
Content could be extended with following internal attributes using query parameter reveal_stats_keys
set to true
.
All statistics are intended for internal purposes and may be changed in the future.
Attribute | Type | Description | Read-only |
---|---|---|---|
dejavu_text | string | The data of a given node predicted by dejavu module (only for internal purposes). | true |
dejavu_position | list | List of the coordinates of the label box of the given node predicted by dejavu module (only for internal purposes). | true |
dejavu_page | int | Number of page where the data is situated (see position) predicted by dejavu module (only for internal purposes). | true |
default_text | string | Default text (only for internal purposes). | true |
Validation sources
validation_sources
property is a list of sources that verified the extracted data. When the list is
non-empty, datapoint is considered to be validated (and no eye-icon is displayed next to it in the Rossum UI).
Currently, there are five sources of validation:
- score: confidence score coming from the AI Core Engine was higher than a preset score threshold (can be set on queue, or individually per datapoint in schema; default is 0.975),
- checks: data extractor does several checks like summing up tax_details, which can verify that the data were extracted correctly,
- history: several fields can be confirmed from historical data in exported documents (can be turned on/off on per queue basis using autopilot section in its settings), and
- connector: a connector verified the validity.
- human: an operator visited the field in validation interface (assumed just verifying the value, not necessarily making any corrections).
A sixth possible validation source value NA signs that validation sources are "Not Applicable" and may now occur only for button datapoints.
The list is subject to ongoing expansion.
Example multivalue datapoint object with a grid
{
"id": 122852,
"schema_id": "line_items",
"category": "multivalue",
"grid": {
"parts": [
{
"page": 1,
"columns": [
{
"left_position": 348,
"schema_id": "item_description",
"header_texts": ["Description"]
},
{
"left_position": 429,
"schema_id": "item_quantity",
"header_texts": ["Qty"]
}
],
"rows": [
{
"top_position": 618,
"type": "header"
},
{
"top_position": 649,
"type": "data"
}
],
"width": 876,
"height": 444
}
]
},
...
}
Grid object is used to store table vertical and horizontal separators and
related attributes. Every grid consists of one or more parts
.
Every part
object consists of several attributes:
Attribute | Type | Description |
---|---|---|
page | int | A unique ID of a given object. |
columns | list[object] | Description of grid columns. |
rows | list[object] | Description of grid rows. |
width | float | Total width of the grid. |
height | float | Total height of the grid. |
Every column contains attributes:
Attribute | Type | Description |
---|---|---|
left_position | float | Position of the column left edge. |
schema_id | string | Reference to datapoint schema id. Used in grid-to-table conversion. |
header_texts | list[string] | Extracted texts from column headers. |
Every row contains attributes:
Attribute | Type | Description |
---|---|---|
top_position | float | Position of the row top edge. |
type | string | Row type. Allowed values are specified in the schema, see grid. If null , the row is ignored during grid-to-table conversion. |
Currently, it is only allowed to have one part per page (for a particular grid).
Get the annotation data
Get annotation data of annotation
315777
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/315777/content'
GET /v1/annotations/{id}/content
Get annotation data.
Response
Status: 200
Returns annotation data.
Bulk update annotation data
Example of body for bulk update of annotation data
{
"operations": [
{
"op": "replace",
"id": "198143",
"value": {
"content": {
"value": "John",
"position": [103, 110, 121, 122],
"page": 1
},
"hidden": false,
"options": [],
"validation_sources": ["human"]
}
},
{
"op": "remove",
"id": "884061"
},
{
"op": "add",
"id": "884060",
"value": [
{
"schema_id": "item_description",
"content": {
"page": 1,
"position": [162, 852, 371, 875],
"value": "Bottle"
}
}
]
}
]
}
POST /v1/annotations/{id}/content/operations
Allows to specify a sequence of operations that should be performed on particular datapoint objects.
To replace a datapoint
value (or other supported attribute), use replace operation:
Key | Type | Description |
---|---|---|
op | string | Type of operation: replace |
id | integer | Datapoint id |
value | object | Updated data, format is the same as in Anotation Data. Only value , position , page , validation_sources , hidden and options attributes may be updated. Value could be also updated via normalized value by replacing value key with normalized_value (*) key with appropriate value. |
(*) value
and normalized_value
should match in case of passing both of them. If they do not match then datapoint won't be
modified.
Please note that section
, multivalue
and tuple
may not be updated.
To add a new row into a multivalue
, use add operation:
Key | Type | Description |
---|---|---|
op | string | Type of operation: add |
id | integer | Multivalue id (parent of new datapoint) |
value | list[object] | Added row data. List of objects, format of the object is the same as in Anotation Data. schema_id attribute is required, only value , position , page , validation_sources , hidden and options attributes may be set. |
The row will be appended to the current list of rows.
Please note that only multivalue
children datapoints may be added.
To remove a row from a multivalue, use remove operation:
Key | Type | Description |
---|---|---|
op | string | Type of operation: remove |
id | integer | Datapoint id |
Please note that only multivalue
children datapoints may be removed.
Send updated annotation data
Send feedback on annotation
315777
Start the annotation
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/315777/start'
{
"annotation": "https://api.elis.rossum.ai/v1/annotations/315777",
"session_timeout": "01:00:00"
}
Get the annotation data
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/315777/content'
{
"id": 37507206,
"url": "https://api.elis.rossum.ai/v1/annotations/315777/content/37507206",
"content": {
"value": "001",
"page": 1,
"position": [
302,
91,
554,
56
],
"rir_text": "000957537",
"rir_position": [
302,
91,
554,
56
],
"connector_text": null,
"rir_confidence": null
},
"category": "datapoint",
"schema_id": "document_id",
"validation_sources": [
"human"
],
"time_spent": 2.7,
"hidden": false
}
Patch the annotation
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
-H 'Content-Type:application/json' -d '{"content": {"value": "#INV00011", "position": [302, 91, 554, 56]}}' \
'https://api.elis.rossum.ai/v1/annotations/315777/content/37507206'
{
"id": 37507206,
"url": "https://api.elis.rossum.ai/v1/annotations/431694/content/39125535",
"content": {
"value": "#INV00011",
"page": 1,
"position": [
302,
91,
554,
56
],
"rir_text": "",
"rir_position": null,
"rir_confidence": null,
"connector_text": null
},
"category": "datapoint",
"schema_id": "document_id",
"validation_sources": [],
"time_spent": 0,
"hidden": false
}
Confirm the annotation
curl -X POST -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/annotations/315777/confirm'
PATCH /v1/annotations/{id}/content/{id of the child node}
Update a particular annotation content node.
It is enough to pass just the updated attributes in the PATCH payload. start
must
be called on the annotation first and confirm
after data is updated.
Response
Status: 200
Returns updated annotation data for the given node.
Relation
Example relation object
{
"id": 1,
"type": "edit",
"key": null,
"parent": "https://api.elis.rossum.ai/v1/annotations/123",
"annotations": [
"https://api.elis.rossum.ai/v1/annotations/124",
"https://api.elis.rossum.ai/v1/annotations/125"
],
"url": "http://api.elis.rossum.ai/v1/relations/1"
}
A relation object introduce common relations between annotations. An annotation could be related to one or more other annotations and it may belong to several relations at the same time.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the relation | true | |
type | string | edit |
Type of relationship. Possible values are edit or duplicate . See below |
|
key | string | Key used to distinguish several instances of the same type | ||
parent | URL | URL of the parent annotation in case of 1-M relationship | ||
annotations | list[URL] | List of related annotations | ||
url | URL | URL of the relation |
Relation types:
edit
relation is created after editing annotation in user interface (rotation or split of the document). The original annotation is set toparent
attribute and newly created annotations are set toannotations
attribute. To find all siblings of edited annotation see filters on annotationduplicate
relation is created after importing the same document that already exists in Rossum for current organization. Ifduplicate
relation already exists then corresponding annotation is added to existing relation.key
ofduplicate
relation is set to MD5 hash of document content. To find all duplicates of the annotation filter annotations with appropriate MD5 hash in relationkey
. See filters on annotation
List all relations
List all relations
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/relations'
{
"pagination": {
"total": 1,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 1500,
"type": "edit",
"key": null,
"parent": "https://api.elis.rossum.ai/v1/annotations/123",
"annotations": [
"https://api.elis.rossum.ai/v1/annotations/456",
"https://api.elis.rossum.ai/v1/annotations/457"
],
"url": "http://api.elis.rossum.ai/v1/relations/1500"
}
]
}
GET /v1/relations
Retrieve all relation objects.
Supported filters: type
, parent
, key
Supported ordering: type
, parent
, key
Response
Status: 200
Returns paginated response with a list of relation objects.
Create a new relation
Create new relation of type
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"type": "edit", "parent": "https://api.elis.rossum.ai/v1/annotations/123", "annotations": ["https://api.elis.rossum.ai/v1/annotations/124"]}' \
'https://api.elis.rossum.ai/v1/relations'
{
"id": 789,
"type": "edit",
"key": null,
"parent": "https://api.elis.rossum.ai/v1/annotations/123"
"annotations": ["https://api.elis.rossum.ai/v1/annotations/124"],
"url": "http://api.elis.rossum.ai/v1/relations/789"
}
POST /v1/relations
Create a new relation object.
Response
Status: 201
Returns created relation object.
Retrieve a relation
Get relation object
1500
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/relations/1500'
{
"id": 1500,
"type": "edit",
"key": null,
"parent": "https://api.elis.rossum.ai/v1/annotations/123",
"annotations": ["https://api.elis.rossum.ai/v1/annotations/124", "https://api.elis.rossum.ai/v1/annotations/125"],
"url": "http://api.elis.rossum.ai/v1/relations/1500"
}
GET /v1/relations/{id}
Get an relation object.
Response
Status: 200
Returns relation object.
Update a relation
Update relation object
1500
curl -X PUT -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"type": "edit", "key": None, "parent": "https://api.elis.rossum.ai/v1/annotations/123", "annotations": ["https://api.elis.rossum.ai/v1/annotations/124"} \
'https://api.elis.rossum.ai/v1/relations/1500'
{
"id": 1500,
"type": "edit",
"key": null,
"parent": "https://api.elis.rossum.ai/v1/annotations/123",
"annotations": ["https://api.elis.rossum.ai/v1/annotations/124"],
"url": "http://api.elis.rossum.ai/v1/relations/1500"
}
PUT /v1/relations/{id}
Update relation object.
Response
Status: 200
Returns updated relation object.
Update part of a relation
Update relation annotations on relation object
1500
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"annotations": ["https://api.elis.rossum.ai/v1/annotations/124", "https://api.elis.rossum.ai/v1/annotations/125"]}' \
'https://api.elis.rossum.ai/v1/relations/1500'
{
"id": 1500,
"type": "edit",
"key": null,
"parent": "https://api.elis.rossum.ai/v1/annotations/123",
"annotations": ["https://api.elis.rossum.ai/v1/annotations/124", "https://api.elis.rossum.ai/v1/annotations/125"],
"url": "http://api.elis.rossum.ai/v1/relations/1500"
}
PATCH /v1/relations/{id}
Update part of relation object.
Response
Status: 200
Returns updated relation object.
Delete a relation
Delete relation
1500
curl -X DELETE -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/relations/1500'
DELETE /v1/relations/{id}
Delete relation object.
Response
Status: 204
Page
Example page object
{
"id": 558598,
"annotation": "https://api.elis.rossum.ai/v1/annotations/314528",
"number": 1,
"rotation_deg": 0,
"mime_type": "image/png",
"s3_name": "4b66305775c029cb0cfa80fd0ebb2da6",
"url": "https://api.elis.rossum.ai/v1/pages/558598",
"content": "https://api.elis.rossum.ai/v1/pages/558598/content",
"metadata": {}
}
A page object contains information about one page of the annotation (we render pages separately for every annotation, but this will change in the future).
Page objects are created automatically during document import and cannot be created through the API, you need to use queue upload endpoint. Pages cannot be deleted directly -- they are deleted on parent annotation delete.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the page | true | |
url | URL | URL of the page. | true | |
annotation | URL | Annotation that page belongs to. | ||
number | integer | Page index, first page has index 1. | ||
rotation_deg | integer | Page rotation. | ||
mime_type | string | MIME type of the page (image/png ). |
true | |
s3_name | string | Internal | true | |
content | URL | Link to the page raw content (e.g. pdf file). | ||
metadata | object | {} |
Client data, see metadata. |
List all pages
List all pages
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/pages'
{
"pagination": {
"total": 1,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 558598,
"annotation": "https://api.elis.rossum.ai/v1/annotations/314528",
"number": 1,
"rotation_deg": 0,
"mime_type": "image/png",
"s3_name": "7eb0dcc0faa8868b55fb425d21cc60dd",
"url": "https://api.elis.rossum.ai/v1/pages/558598",
"content": "https://api.elis.rossum.ai/v1/pages/558598/content",
"metadata": {}
}
]
}
GET /v1/pages
Retrieve all page objects.
Supported filters: id
, annotation
, number
Supported ordering: id
, number
, s3_name
Response
Status: 200
Returns paginated response with a list of page objects.
Retrieve a page
Get page object
558598
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/pages/558598'
{
"id": 558598,
"annotation": "https://api.elis.rossum.ai/v1/annotations/314528",
"number": 1,
"rotation_deg": 0,
"mime_type": "image/png",
"s3_name": "7eb0dcc0faa8868b55fb425d21cc60dd",
"url": "https://api.elis.rossum.ai/v1/pages/558598",
"content": "https://api.elis.rossum.ai/v1/pages/558598/content",
"metadata": {}
}
GET /v1/pages/{id}
Get an page object.
Response
Status: 200
Returns page object.
Suggested edit
Example suggested edit object
{
"id": 314528,
"url": "https://api.elis.rossum.ai/v1/suggested_edits/314528",
"annotation": "https://api.elis.rossum.ai/v1/annotations/314528",
"documents": [
{
"pages": [
{
"page": "https://api.elis.rossum.ai/v1/pages/314554",
"rotation": 0
},
{
"page": "https://api.elis.rossum.ai/v1/pages/314593",
"rotation": 0
}
]
},
{
"pages": [
{
"page": "https://api.elis.rossum.ai/v1/pages/314556",
"rotation": 0
}
]
}
]
}
A suggested edit object contains splittings of incomming document suggested by the AI engine.
Suggested edit objects are created automatically during document import.
Attribute | Type | Default | Description | Read-only |
---|---|---|---|---|
id | integer | Id of the suggested edit. | True | |
url | URL | URL of the suggested edit. | True | |
annotation | URL | Annotation that suggested edit is related to. | ||
documents | list[object] | Contains suggested split of related document. |
List all suggested_edit objects
List all suggested_edit objects
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/suggested_edits'
{
"pagination": {
"total": 1,
"total_pages": 1,
"next": null,
"previous": null
},
"results": [
{
"id": 314528,
"url": "https://api.elis.rossum.ai/v1/suggested_edits/314528",
"annotation": "https://api.elis.rossum.ai/v1/annotations/314528",
"documents": [
{
"pages": [
{
"page": "https://api.elis.rossum.ai/v1/pages/314554",
"rotation": 0
},
{
"page": "https://api.elis.rossum.ai/v1/pages/314593",
"rotation": 0
}
]
},
{
"pages": [
{
"page": "https://api.elis.rossum.ai/v1/pages/314556",
"rotation": 0
}
]
}
]
}
]
}
GET /v1/suggested_edits
Retrieve all suggested edit objects.
Supported filters: annotation
Supported ordering: annotation
Response
Status: 200
Returns paginated response with a list of suggested edit objects.
Create a new suggested edit
Create new suggested_edit
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"annotation": "https://api.elis.rossum.ai/v1/annotations/123", "documents": [{"pages": [{"page": "https://api.elis.rossum.ai/v1/pages/123"}]}]}' \
'https://api.elis.rossum.ai/v1/suggested_edits'
{
"id": 123,
"url": "https://api.elis.rossum.ai/v1/suggested_edits/123",
"annotation": "https://api.elis.rossum.ai/v1/annotations/123",
"documents": [
{
"pages": [
{
"page": "https://api.elis.rossum.ai/v1/pages/123"
}
]
}
]
}
POST /v1/suggested_edits
Create a new suggested edit object.
Response
Status: 201
Returns created suggested edit object.
Retrieve a suggested edit
Get suggested edit object
558598
curl -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/suggested_edits/558598'
{
"id": 314528,
"url": "https://api.elis.rossum.ai/v1/suggested_edits/314528",
"annotation": "https://api.elis.rossum.ai/v1/annotations/314528",
"documents": [
{
"pages": [
{
"page": "https://api.elis.rossum.ai/v1/pages/314554",
"rotation": 0
},
{
"page": "https://api.elis.rossum.ai/v1/pages/314593",
"rotation": 0
}
]
},
{
"pages": [
{
"page": "https://api.elis.rossum.ai/v1/pages/314556",
"rotation": 0
}
]
}
]
}
GET /v1/suggested_edits/{id}
Get a suggested edit object.
Response
Status: 200
Returns suggested edit object.
Update a suggested edit
Update suggested edit object
1500
curl -X PUT -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"annotation": "https://api.elis.rossum.ai/v1/annotations/1500", "documents": [{"pages": [{"page": "https://api.elis.rossum.ai/v1/pages/123"}]}]}' \
'https://api.elis.rossum.ai/v1/suggested_edits/1500'
{
"id": 1500,
"url": "https://api.elis.rossum.ai/v1/suggested_edits/1500",
"annotation": "https://api.elis.rossum.ai/v1/annotations/1500",
"documents": [
{
"pages": [
{
"page": "https://api.elis.rossum.ai/v1/pages/123"
}
]
}
]
}
PUT /v1/suggested_edits/{id}
Update suggested edit object.
Response
Status: 200
Returns updated suggested edit object.
Update part of a suggested edit
Update documents on suggested edit object
1500
curl -X PATCH -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' -H 'Content-Type: application/json' \
-d '{"documents": [{"pages": [{"page": "https://api.elis.rossum.ai/v1/pages/123"}]}]}' \
'https://api.elis.rossum.ai/v1/suggested_edits/1500'
{
"id": 1500,
"url": "https://api.elis.rossum.ai/v1/suggested_edits/1500",
"annotation": "https://api.elis.rossum.ai/v1/annotations/1500",
"documents": [
{
"pages": [
{
"page": "https://api.elis.rossum.ai/v1/pages/123"
}
]
}
]
}
PATCH /v1/suggested_edits/{id}
Update part of suggested edit object.
Response
Status: 200
Returns updated suggested edit object.
Delete a suggested edit
Delete suggested edit
1500
curl -X DELETE -H 'Authorization: token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://api.elis.rossum.ai/v1/suggested_edits/1500'
DELETE /v1/suggested_edits/{id}
Delete suggested edit object.
Response
Status: 204
FAQ
POST fails with HTTP status 500
Please check that Content-Type header in the HTTP request is set correctly
(e.g. application/json
).
We will improve content type checking in the future , so that to return 400.
SSL connection errors
Rossum API only supports TLS 1.2 to ensure that up-to-date algorithms and ciphers are used.
Older SSL libraries may not work properly with TLS 1.2. If you encounter SSL/TLS compatibility issue, please make sure the library supports TLS 1.2 and the support is switched on.