Rossum API (v1)

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.

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

• Refer to the Rossum Developer Portal for guides, tutorials, news and a community Q&A section.
• For managing and configuring your account, 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.

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

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

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

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). A sample curl command to Rossum API would look like this:

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

Example response:

{"key": "db313f24f5738c8e04635e036ec8a45cdd6d6b03"}

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

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

Formatted JSON response:

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

Use the API on Windows

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

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

Example for Unix-based systems:

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

Equivalent commands for Windows:

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


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

Create an account

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

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.

Example login request:

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

Login response:

{"key": "db313f24f5738c8e04635e036ec8a45cdd6d6b03"}

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

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

Upload a document

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

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

Example response:

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

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

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

Example response with task URL:

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

Wait for document to be ready and review extracted data

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

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

Result:

"to_review"

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

Download reviewed data

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

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

Example response:

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

Logout

Finally you can dispose token safely using logout endpoint:

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

Logout response:

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

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).

Note: When making HTTP requests, be sure to use proper header 'Content-Type:application/json'.

Base API endpoint URL depends on the account type, deployment and location. Default URL is https://example.rossum.app/api where the example is the domain selected during the account creation. URLs of companies using a dedicated deployment may look like https://acme.rossum.app/api.

If you are not sure about the correct URL you can navigate to https://app.rossum.ai and use your email address to receive your account information via email.

Please note that we previously recommended using the https://api.elis.rossum.ai endpoint to interact with the Rossum API, but now it is deprecated. For new integrations use the new https://example.rossum.app/api endpoint. For accounts created before Nov 2022 use the https://elis.rossum.ai/api.

Most of the API endpoints require a user to be authenticated. To login to the Rossum API, post an object with username and password fields. Login returns an access key to be used for token authentication.

Our API also provide possibility to authenticate via One-Time token which is returned after registration. This tokens allows users to authenticate against our API, but after one call, this token will be invalidated. This token can be exchanged for regular access token limited only by the time of validity. For the purpose of token exchange, use the /auth/token endpoint.

Users may delete a token using the logout endpoint or automatically after a configured time (the default expiration time is 162 hours). The default expiration time can be lowered using max_token_lifetime_s field. When the token expires, 401 status is returned. Users are expected to re-login to obtain a new token.

Rossum's API also supports session authentication, where a user session is created inside cookies after login. If enabled, the session lasts 1 day until expired by itself or until logout While the session is valid there is no need to send the authentication token in every request, but the "unsafe" request (POST, PUT, PATCH, DELETE), whose MIME type is different from application/json must include X-CSRFToken header with valid CSRF token, which is returned inside Cookie while loging in. When a session expires, 401 status is returned as with token authentication, and users are expected to re-login to start a new session.

Note: For seamless integration with third-party systems, upload and export endpoints support also basic authentication. Other endpoints does not support basic auth for new organization group by default. If you need to change default behaviour, please contact support@rossum.ai.

Login

POST /v1/auth/login

Example login request:

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

Example login response:

{
  "key": "db313f24f5738c8e04635e036ec8a45cdd6d6b03",
  "domain": "acme-corp.app.rossum.ai"
}

Attribute	Type	Required	Description
username	string	true	Username of the user to be logged in.
password	string	true	Password of the user.
origin	string	false	For internal use only. Using this field may affect Rate Limiting of your API requests.
max_token_lifetime_s	integer	false	Duration (in seconds) for which the token will be valid. Default is 162 hours which is also the maximum.

Using the token with Bearer authentication:

curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/organizations/406'

Alternative token authentication format:

curl -H 'Authorization: Token db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/organizations/406'

Login request with custom token lifetime:

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

Response with custom token lifetime:

{
  "key": "ltcg2p2w7o9vxju313f04rq7lcc4xu2bwso423b3",
  "domain": null
}

Response

Status: 200

Returns object with "key", which is an access token. And the user's domain.

Attribute	Type	Description
key	string	Access token.
domain	string	The domain the token was issued for.

Logout

POST /v1/auth/logout

Logout user, discard auth token. Example request:

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

Example response:

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

Response

Status: 200

Token Exchange

POST /v1/auth/token

Example token exchange request:

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

Example token exchange response:

{
  "key": "ltcg2p2w7o9vxju313f04rq7lcc4xu2bwso423b3",
  "domain": "example.rossum.app",
  "scope": "default"
}

Attribute	Type	Required	Description
scope	string	false	Supported values are default, approval (for internal use only)
max_token_lifetime_s	float	false	Duration (in seconds) for which the token will be valid (default: lifetime of the current token or 162 hours if the current token is one-time). Can be set to a maximum of 583200 seconds (162 hours).
origin	string	false	For internal use only. Using this field may affect Rate Limiting of your API requests.

This endpoint enables the exchange of a one-time token for a longer lived access token.

It is able to receive either one-time tokens provided after registration, or JWT tokens if you have such a setup configured. The token must be provided in a the Bearer authorization header.

JWT authentication

Note: Talk with a Rossum representative if you are willing to use JWT authentication.

Short-lived JWT tokens can be exchanged for access tokens. A typical use case, for example, is logging in your users via SSO in your own application, and displaying the Rossum app to them embedded.

To enable JWT authentication, one needs to provide Rossum with the public key that shall be used to decode the tokens. Currently only tokens with EdDSA (signed using Ed25519 and Ed448 curves) and RS512 signatures are allowed, and token validity should be 60 seconds maximum.

The expected formats of the header and encoded payload of the JWT token are as follows:

Decoded JWT Header Format

Example JWT header:

{
   "alg":"EdDSA",
   "kid":"urn:rossum.ai:organizations:100",
   "typ":"JWT"
}

Attribute	Type	Required	Description
kid	string	true	Identifier. Must end with :{your Rossum org ID}, e.g. "urn:rossum.ai:organizations:123"
typ	string	false	Type of the token.
alg	string	true	Signature algorithm to be used for decoding the token. Only EdDSA or RS512 values are allowed.

Decoded JWT Payload Format

Example JWT payload:

{
   "ver":"1.0",
   "iss":"ACME Corporation",
   "aud":"https://example.rossum.app",
   "sub":"john.doe@rossum.ai",
   "exp":1514764800,
   "email":"john.doe@rossum.ai",
   "name":"John F. Doe",
   "rossum_org":"100",
   "roles": ["annotator"]
}

Attribute	Type	Required	Description
ver	string	true	Version of the payload format. Available versions: 1.0.
iss	string	true	Name of the issuer of the token (e.g. company name).
aud	string	true	Target domain used for API queries (e.g. https://example.rossum.app)
sub	string	true	User email that will be matched against username in Rossum.
exp	int	true	UNIX timestamp of the JWT token expiration. Must be set to 60 seconds after current UTC time at maximum.
email	string	true	User email.
name	string	true	User's first name and last name separated by space. Will be used for creation of new users if auto-provisioning is enabled.
rossum_org	string	true	Rossum organization id.
roles	list[string]	false	Name of the user roles that will be assigned to user created by auto-provisioning. Must be a subset of the roles stated in the auto-provisioning configuration for the organization.

Response

Status: 200

Attribute	Type	Description
key	string	Access token.
domain	string	The domain the token was issued for.
scope	string	Supported values are default, approval (for internal use only)

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.

Note: Talk with a Rossum representative about enabling this feature.

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. If auto-provisioning is enabled for the organization, user accounts in Rossum will be automatically created for users without accounts.

Required setup of the OIDC identity provider:

• Redirect URI (also known as Reply URL): https://example.rossum.app/api/v1/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.

Note: By default, oidc_id is matched case sensitive. In case email claim is used, case insensitive matching is used. In addition, if email claim is used and oidc_id is null, username is matched instead.

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

(*) Maximum page size differs for some endpoints:

• 1,000 for exporting data in CSV format via POST on /annotations
• 500 for searching in annotations via annotations/search (if sideload=content is not included)

To ensure optimal performance and fair usage across the platform, the API implements rate limiting features. If a client exceeds the allowed number of API requests Rossum API will respond with a 429 status code and a Retry-After header. The header specifies the number of seconds the client should wait before retrying the request. To avoid being rate limited, ensure your usage complies with our Acceptable Use Schedule as described in the Rossum Terms of Use.

When the client receives a 429 status code, the response header Retry-After will have the following format:

Retry-After: 10

This example means the client should wait for 10 seconds before attempting another request.

The recommended approach for handling rate limited requests is to manage 429 status codes gracefully and use exponential backoff for retries, respecting the Retry-After header.

Current Rate Limits

The current default rate limits for Rossum API are as follows:

Limit	Description
10 reqs / second	Overall API rate limit.
10 reqs / minute	Limit specific for the annotations/{id}/page_data/translate endpoint.

Example of filtering and ordering queues:

curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/v1/queues?workspace=7540&locale=en_US&ordering=name&pages=1,2'

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.

Multiple values within the same attribute can be used, resulting in OR condition. Use comma to separate values.

Note: All filter parameters that refer to object expect only id (instead of URL) of the object.

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.

Example document object with metadata:

{
  "id": 319768,
  "url": "https://example.rossum.app/api/v1/documents/319768",
  "s3_name": "05feca6b90d13e389c31c8fdeb7fea26",
  "annotations": [
    "https://example.rossum.app/api/v1/annotations/319668"
  ],
  "mime_type": "application/pdf",
  "arrived_at": "2019-02-11T19:22:33.993427Z",
  "original_file_name": "document.pdf",
  "content": "https://example.rossum.app/api/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, survey.

Total metadata size may be up to 4 kB per object.

API Version is part of the URL, e.g. https://example.rossum.app/api/v1/users.

To allow API progress, we consider addition of a field in a JSON object as well as addition of a new item in an enum object to be backward-compatible operations that may be introduced at any time. Clients are expected to deal with such changes.

Some endpoints and attributes in our API are marked with a Beta label. This indicates that the functionality is currently in beta and may be subject to changes in the future. While we encourage you to try out these features, please be aware that:

• The API contract may change in backward-incompatible ways
• Features might be modified or removed in future releases

We welcome your feedback on these beta features to help us improve them before they reach general availability.

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.

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 that was not started by the current user.
413	Payload Too Large	for too large payload (especially for files uploaded).
429	Too Many Requests	The allowed number of requests per minute has been exceeded. Please wait before sending more requests.
500	Internal Server Error	We had a problem with the server. Please try again later.
502	Bad Gateway	We had a problem with the server. Please try again later.
503	Service Unavailable	We're temporarily offline for maintenance. Please try again later.
504	Gateway Timeout	We had a problem with the server. Please try again later.

Documents may be imported into Rossum using the REST API and email gateway. Supported file formats are PDF, PNG, JPEG, TIFF, XLSX/XLS, DOCX/DOC and HTML. Maximum supported file size is 40 MB (this limit applies also to the uncompressed size of the files within a .zip archive).

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.

HTML File Sanitization: HTML files uploaded via upload endpoints, document creation API, or email import are automatically sanitized for security purposes. Some elements, attributes and styles are removed. The sanitization process can break HTML validity.

Support for additional MIME types may be added by handling upload.created webhook event. With this setup, user is able to pre-process uploaded files (e.g. XML or JSON formats) into a format that Rossum understands. Those usually need to be enabled on queue level first (by adding appropriate mimetype to accepted_mime_types in queue settings attributes).

List of enabled MIME types:

• application/EDI-X12
• application/EDIFACT
• application/json
• application/msword
• application/pdf
• application/pgp-encrypted
• application/vnd.ms-excel
• application/vnd.ms-outlook
• application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• application/vnd.openxmlformats-officedocument.wordprocessingml.document
• application/xml
• application/zip
• image/*
• message/rfc822
• text/csv
• text/html (automatically sanitized - see note above)
• text/plain
• text/xml

If you find your document MIME types not supported please contact Rossum support team for more information.

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.

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, images and zip files, stores them in the queue and starts data extraction process.

The size limit for incoming emails is 50 MB (the raw email message with base64 encoded attachments).

All the files from the root of the archive are extracted. In case the root only contains one directory (and no other files) the whole directory is extracted. The zip files and all extracted files must be allowed in accepted_mime_types (see queue settings) and must pass inbox filtering rules (see document rejection conditions) in order for annotations to be created.

Invalid characters in attachment file names (e.g. /) are replaced with underscores.

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.

Zip attachment limits:

• the uncompressed size of the files within a .zip archive may not exceed 40 MB
• only archives containing less than 1000 files are processed
• only files in the root of the archive are processed (or files inside a first level directory if it's the only one there)

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.

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.

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.

Note: See the introduction to Rossum customization for a high-level overview of configuring the captured fields and managing schemas.

The best visual guide to the schema JSON that will get you started tweaking it in the Rossum app is our tutorial on editing the extraction schema. Especially when maintaining long dropdown select boxes.

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 sections, which may either directly contain actual data fields (datapoints) or use nested multivalues and tuples 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 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. Maximum length is 50 characters.	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. Note that section is hidden if all its children are hidden.	no
disable_prediction	boolean	Can be set to true to disable field extraction, while still preserving the data shape. Ignored by aurora engines.	no

Section

Example section object:

{
  "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.
ui_configuration	object	A group of settings affecting behaviour of the field in the application. See UI configuration.
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.
formula	string[0;2000]	Formula definition, required only for fields of type formula, see Formula Fields. rir_field_names should also be empty for these fields.
prompt	string[0;2000]	Prompt definition, required only for fields of type reasoning.
context	list[string]	Context for the prompt, required only for fields of type reasoning see Logical Types.

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 document
• edit:id to identify a value specified in edit_pages endpoint
• email_header:<id> to use a value extracted from email headers. Supported email headers: from, to, reply-to, subject, message-id, date.
• email_body:<id> to select email body. Supported values are text_html for HTML body or text_plain for plain text body.
• email:<id> to identify a value specified in email.received hook response
• emails_import:<id> to identify a value specified in the values parameter when importing an email.

If more list items in rir_field_names are specified, the first available value will be used.

String type

Example string type datapoint with constraints:

{
  "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 type 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

Example date formats:

• D/M/YYYY: e.g. 23/1/2019
• MM/DD/YYYY: e.g. 01/23/2019
• YYYY-MM-DD: e.g. 2019-01-23 (ISO date format)

Number type

Example number type 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 below. 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 or 1234.5
#'##0.#	1'234.5 or 1234.5
#.##0,#	1.234,5 or 1234,5
# ##0	1 234 or 1234
#,##0	1,234 or 1234
#'##0	1'234 or 1234
#.##0	1.234 or 1234

Aggregations

Example number type datapoint with sum aggregation:

{
  "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 /v1/annotations/{id}/content/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 type 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": [],
  "enum_value_type": "number"
}

Attributes specific to Enum datapoint:

Attribute	Type	Description	Required
options	object	See object description below.	yes
enum_value_type	string	Data type of the option's value attribute. Must be one of the following: string, number, date	no

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 Beta

Specifies a button shown in Rossum UI. For more details please refer to custom UI extension.

Example button type datapoint:

{
  "id": "show_email",
  "type": "button",
  "category": "datapoint",
  "popup_url": "http://example.com/show_customer_data",
  "can_obtain_token": true
}

Buttons cannot be direct children of multivalues (simple multivalues with buttons are not allowed. In tables, buttons are children of tuples). 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.
can_obtain_token	boolean	If set to true the popup window is allowed to ask the main Rossum window for authorization token

Value constraints

Example datapoint with 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.

UI configuration

Example datapoint with UI configuration:

{
  "id": "document_id",
  "type": "string",
  "label": "Invoice ID",
  "category": "datapoint",
  "ui_configuration": {
    "type":  "captured",
    "edit": "disabled"
  },
  "default_value": null,
  "rir_field_names": [
    "document_id"
  ]
}

UI configuration provides a group of settings, which alter behaviour of the field in the application. This does not affect behaviour of the field via the API. For example, disabling edit prohibits changing a value of the datapoint in the application, but the value can still be modified through API.

Attribute	Type	Description	Required
type	string	Logical type of the datapoint. Possible values are: captured, data, manual, formula, reasoning or null. Default value is null.	false
edit	string	When set to disabled, value of the datapoint is not editable via UI. When set to enabled_without_warning, no warnings are displayed in the UI regarding this fields editing behaviour. Default value is enabled, this option enables field editing, but user receives dismissible warnings when doing so.	false

Logical types

• Captured field represents information retrieved by the OCR model. If combined with edit option disabled, user can't overwrite field's value, but is able to redraw field's bounding box and select another value from the document by such an action.
• Data field represents information filled by extensions. This field is not mapped to the AI model, so it does not have a bounding box, neither it's possible to create one. If combined with edit option disabled the field can't be modified from the UI.
• Manual field behaves exactly like Data field, without the mapping to extensions. This field should be used for sharing information between users or to transfer information to downstream systems.
• Formula field This field will be updated according to its formula definition, see Formula Fields. If the edit option is not disabled the field value can be overridden from the UI (see no_recalculation).
• Reasoning fields This field will be updated according to its prompt and context. context supports adding related schema fields in a format of TxScript strings (e.g. field.invoice_id, also self.attr.label and self.attr.description are supported). If the edit option is not disabled the field value can be overridden from the UI (see no_recalculation).
• null value is displayed in UI as Unset and behaves similar to the Captured field.

Multivalue

Example simple multivalue:

{
  "category": "multivalue",
  "id": "po_numbers",
  "label": "PO numbers",
  "children": {
    ...
  },
  "show_grid_by_default": false,
  "min_occurrences": null,
  "max_occurrences": null,
  "rir_field_names": null
}

Example multivalue with grid configuration:

{
  "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 datapoints or tuples 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 1000 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	list[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 no grid row types configuration is specified in the schema.

Note: Only rows marked as one of row_types_to_extract values are transfered to a table by pressing "Read data from table" button in the Rossum UI (calling grid-to-table conversion API endpoint).

Tuple

Example tuple object:

{
  "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 ids.

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.

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 and deleted 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.

Note: Formerly, we recommended to always create a new schema object when changing the set of extracted fields. This is no longer necessary since updating of the current schema object (PUT/PATCH) can be used instead. See use-cases below if not sure which approach is appropriate.

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 and postponed state that are linked to extracted fields types will be filled by AI Engine, if available. New fields for already exported or deleted annotations (also purged, exporting and failed_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.

Warning: When copying an annotation or moving it to a new queue by patching its queue attribute, the annotation in the new queue will still be associated with the old schema.

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)

Note: Schema can be updated also manually using the command-line tool rossum. See our guide on schema configuration for more information.

AI engine currently automatically extracts the following fields at the all endpoint, subject to ongoing expansion.

Identifiers

Attr. rir_field_names	Field label	Description
account_num	Bank Account	Bank account number. Whitespaces are stripped.
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	Variable symbol	In some countries used by the supplier to match the payment received against the invoice. Possible non-numeric characters are stripped.
terms	Terms	Payment terms as written on the document (e.g. "45 days", "upon receipt").
payment_method	Payment method	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. Whitespaces are stripped.
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. Whitespaces are stripped.
order_id	Order Number	Purchase order identification (Order Numbers not captured as "sender_order_id"). Whitespaces are stripped.
recipient_address	Recipient Address	Address of the customer.
recipient_dic	Recipient Tax Number	Tax identification number of the customer. Whitespaces are stripped.
recipient_ic	Recipient Company ID	Company identification number of the customer. Possible non-numeric characters are stripped.
recipient_name	Recipient Name	Name of the customer.
recipient_vat_id	Recipient VAT Number	Customer VAT Number
recipient_delivery_name	Recipient Delivery Name	Name of the recipient to whom the goods will be delivered.
recipient_delivery_address	Recipient Delivery Address	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. Whitespaces are stripped.
sender_ic	Supplier Company ID	Business/organization identification number of the supplier. Possible non-numeric characters are stripped.
sender_name	Supplier Name	Name of the supplier.
sender_vat_id	Supplier VAT Number	VAT identification number of the supplier.
sender_email	Supplier Email	Email of the sender.
sender_order_id	Supplier's Order ID	Internal order ID in the suppliers system.
delivery_note_id	Delivery Note ID	Delivery note ID defined on the invoice.
supply_place	Place of Supply	Place of supply (the name of the city or state where the goods will be supplied).

Note: Starting from July 2020 field invoice_id was renamed to document_id. However, the invoice_id name will still be supported for backwards compatibility. For future, we would recommend switching to document_id in your extraction schemas.

Document attributes

Attr. rir_field_names	Field label	Description
currency	Currency	The currency which the invoice is to be paid in. Possible values: AED, ARS, AUD, BGN, BRL, CAD, CHF, CLP, CNY, COP, CRC, CZK, DKK, EUR, GBP, GTQ, HKD, HUF, IDR, ILS, INR, ISK, JMD, JPY, KRW, MXN, MYR, NOK, NZD, PEN, PHP, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, USD, VES, VND, ZAR 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, order or other.
language	Language	The language which the document was written in. Values are ISO 639-3 language codes, e.g.: eng, fra, deu, zho. See Lanugages Supported By Rossum
payment_method_type	Payment Method Type	Payment method used for the transaction. Possible values: card, cash.

Note: Starting from May 2020 the invoice_type document attribute was renamed to document_type. However, the invoice_type name will still be supported for backwards compatibility. For future, we would recommend switching to document_type in your extraction schemas.

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

Note: For backwards compatibility, the rir_field_names on multivalue are by default set to line_items. However, if any of column schema rir_field_names contain a string starting with tax_detail_ then the table is assumed to be tax_details.

Tax details

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

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.

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
created	Annotation was created manually via POST to annotations endpoint. Annotation created this way may be switched to importing state only at the end of the upload.created event (this happens automatically).
importing	Document is being processed by the AI Engine for data extraction.
failed_import	Import failed e.g. due to a malformed document file.
split	Annotation was split in user interface or via API 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.
in_workflow	Annotation is being processed in a workflow. Annotation content cannot be modified while in this state. Please note that any manual interaction with this status may introduce confilicts with Rossum automated workflows. Read more about Rossum Workflows here.
confirmed	Annotation is validated and confirmed by the user. This status must be explicitly enabled on the queue to be present.
rejected	Annotation was rejected by user. This status must be explicitly enabled on the queue to be present. You can read about when a rejection is possible here.
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. This status is terminal and cannot be further changed. See purge deleted if you want to know how to purge an annotation.

This diagram shows exact flow between the annotation states whole working with the UI.

Note: See our article on the annotation lifecycle for more information.

Warning: We strongly discourage users from PATCHing the annotation statuses due to possible causes of unwanted behavior concerning working with the Rossum application. The diagram below shows how the annotation attributes change during the annotation's lifecycle, clearly showing why not to PATCH only the status. We strongly advise users to use predefined endpoints to manipulate the annotation statuses.

In order to obtain an overview of the Rossum usage, you can download Csv 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
• User url
• Queue url
• Workspace url
• Imported: count of all documents that were imported during the time period
• Confirmed: count of all documents that were confirmed during the time period
• Rejected: count of all documents that were rejected during the time period
• Rejected automatically: count of all documents that were automatically rejected during the time period
• Rejected manually: count of all documents that were manually rejected 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

Example usage report request:

curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
  'https://example.rossum.app/api/annotations/usage_report?from=2019-01-01&to=2019-01-31'

Csv file (csv) may be downloaded from https://example.rossum.app/api/v1/annotations/usage_report?format=csv.

You may specify date range using from and to parameters (inclusive). If not specified, a report for last 12 months is generated.

Note: Please note that direct access to the API may require you to login using Rossum credentials. User must have admin or manager role.

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; deleted_at for deleted_count; rejected_at for rejected_count; or exported_at for the rest) greater than specified.
filter.end_date	datetime	Filter documents that has date (arrived_at for imported_count; deleted_at for deleted_count; rejected_at for rejected_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 is to be grouped. Possible values: user, workspace, queue, month, week, day.

Example request body with filters:

{
  "filter": {
    "users": [
      "https://example.rossum.app/api/v1/users/173"
    ],
    "queues": [
      "https://example.rossum.app/api/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"
  ]
}

Note: Please note that direct access to the API may require you to login using Rossum credentials. User must have admin or manager role.

The response consists of two parts: totalsand series.

Status: 200

Example usage report response:

{
  "series": [
    {
      "begin_date": "2019-12-01",
      "end_date": "2020-01-01",
      "queue": "https://example.rossum.app/api/v1/queues/8199",
      "workspace": "https://example.rossum.app/api/v1/workspaces/7540",
      "values": {
        "imported_count": 2,
        "confirmed_count": 6,
        "rejected_count": 2,
        "rejected_automatically_count": 1,
        "rejected_manually_count": 1,
        "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_per_document_active_avg_s": null,
        "time_and_corrections_per_field": []
      }
    },
    {
      "begin_date": "2020-01-01",
      "end_date": "2020-02-01",
      "queue": "https://example.rossum.app/api/v1/queues/8199",
      "workspace": "https://example.rossum.app/api/v1/workspaces/7540",
      "user": "https://example.rossum.app/api/v1/users/173",
      "values": {
        "imported_count": null,
        "confirmed_count": 6,
        "rejected_count": 3,
        "rejected_automatically_count": 2,
        "rejected_manually_count": 1,
        "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_per_document_active_avg_s": 50.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,
    "confirmed_count": 6,
    "rejected_count": 5,
    "rejected_automatically_count": 3,
    "rejected_manually_count": 2,
    "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,
    "time_per_document_active_avg_s": 50.0
  }
}

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
confirmed_count	int	Count of documents that were confirmed
rejected_count	int	Count of documents that were rejected
rejected_automatically_count	int	Count of documents that were automatically rejected
rejected_manually_count	int	Count of documents that were manually rejected
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. Based on the time_spent_overall metric, see annotation processing duration
time_per_document_active_avg_s	float	Average active time (in seconds) that users spent validating documents. Based on the time_spent_active metric, see annotation processing duration

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 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

*Corrected ratio is calculated based on human corrections. If any kind of automation (Hook, Webhook, etc) is ran on the datapoints, even after a human correction took a place, the corrected_ration will not be calculated -> Is set to 0.

The Rossum platform may be extended via third-party, externally running services or custom serverless 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 an 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.

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.

Note: Webhooks are more recent and flexible alternative to connectors. For new implementations, consider using webhooks.

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.

Note: The Extension Howto on our Developer Hub is a good starting point when building your own extension. You can also find a high-level description of hooks in our here or investigate other examples of webhook implementations:

• Simple custom check example (JavaScript)
• Vendor matching example (Python)
• Schema change example (Python)

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
• If webhooks are connected via the run_after parameter, the results from the predecessor webhook are passed to its successor

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

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)

Example webhook request payload for annotation_status.changed event:

{
  "request_id": "ae7bc8dd-73bd-489b-a3d2-f5514b209591",
  "timestamp": "2020-01-01T00:00:00.000000Z",
  "base_url": "https://example.rossum.app",
  "rossum_authorization_token": "1024873d424a007d8eebff7b3684d283abdf7d0d",
  "hook": "https://example.rossum.app/api/v1/hooks/789",
  "settings": {
    "example_target_service_type": "SFTP",
    "example_target_hostname": "sftp.elis.rossum.ai"
  },
  "secrets": {
    "username": "my-rossum-importer",
    "password": "secret-importer-user-password"
  },
  "action": "changed",
  "event": "annotation_status",
  "annotation": {
    "document": "https://example.rossum.app/api/v1/documents/314621",
    "id": 314521,
    "queue": "https://example.rossum.app/api/v1/queues/8236",
    "schema": "https://example.rossum.app/api/v1/schemas/223",
    "pages": [
      "https://example.rossum.app/api/v1/pages/551518"
    ],
    "creator": "https://example.rossum.app/api/v1/users/1",
    "modifier": null,
    "assigned_at": null,
    "created_at": "2021-04-26T10:08:03.856648Z",
    "confirmed_at": null,
    "deleted_at": null,
    "exported_at": null,
    "export_failed_at": null,
    "modified_at": null,
    "purged_at": null,
    "rejected_at": null,
    "confirmed_by": null,
    "deleted_by": null,
    "exported_by": null,
    "purged_by": null,
    "rejected_by": null,
    "status": "to_review",
    "previous_status": "importing",
    "rir_poll_id": "54f6b91cfb751289e71ddf12",
    "messages": null,
    "url": "https://example.rossum.app/api/v1/annotations/314521",
    "content": "https://example.rossum.app/api/v1/annotations/314521/content",
    "time_spent": 0,
    "metadata": {},
    "organization": "https://example.rossum.app/api/v1/organizations/1"
  },
  "document": {
    "id": 314621,
    "url": "https://example.rossum.app/api/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://example.rossum.app/api/v1/documents/314621/content",
    "metadata": {}
  }
}

Example webhook request payload for annotation_content.updated event:

{
  "request_id": "ae7bc8dd-73bd-489b-a3d2-f5214b209591",
  "timestamp": "2020-01-01T00:00:00.000000Z",
  "base_url": "https://example.rossum.app",
  "rossum_authorization_token": "1024873d424a007d8eebff7b3684d283abdf7d0d",
  "hook": "https://example.rossum.app/api/v1/hooks/781",
  "settings": {
    "example_target_hostname": "sftp.elis.rossum.ai"
  },
  "secrets": {
    "password": "secret-importer-user-password"
  },
  "action": "updated",
  "event": "annotation_content",
  "annotation": {
    "document": "https://example.rossum.app/api/v1/documents/314621",
    "id": 314521,
    "queue": "https://example.rossum.app/api/v1/queues/8236",
    "schema": "https://example.rossum.app/api/v1/schemas/223",
    "pages": [
      "https://example.rossum.app/api/v1/pages/551518"
    ],
    "creator": "https://example.rossum.app/api/v1/users/1",
    "modifier": null,
    "assigned_at": null,
    "created_at": "2021-04-26T10:08:03.856648Z",
    "confirmed_at": null,
    "deleted_at": null,
    "exported_at": null,
    "export_failed_at": null,
    "modified_at": null,
    "purged_at": null,
    "rejected_at": null,
    "confirmed_by": null,
    "deleted_by": null,
    "exported_by": null,
    "purged_by": null,
    "rejected_by": null,
    "status": "to_review",
    "previous_status": "importing",
    "rir_poll_id": "54f6b91cfb751289e71ddf12",
    "messages": null,
    "url": "https://example.rossum.app/api/v1/annotations/314521",
    "organization": "https://example.rossum.app/api/v1/organizations/1",
    "content": [
      {
        "id": 1123123,
        "url": "https://example.rossum.app/api/v1/annotations/314521/content/1123123",
        "schema_id": "basic_info",
        "category": "section",
        "children": [
          {
            "id": 20456864,
            "url": "https://example.rossum.app/api/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://example.rossum.app/api/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://example.rossum.app/api/v1/documents/314621/content",
    "metadata": {}
  },
  "updated_datapoints": [11213211, 11213212]
}

Example webhook response with messages and operations:

{
  "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"
          }
        }
      ]
    }
  ]
}

Supported events and their actions

Event and Action	Payload (outside default attributes)	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	operations, messages	Annotation was initialized (data extracted)	yes
annotation_content.started	annotation + content, document, updated_datapoints (empty)	operations, messages	User entered validation screen	no (interactive)
annotation_content.user_update	annotation + content, document, updated_datapoints	operations, messages	(Deprecated in favor of annotation_content.updated) Annotation was updated by the user	no (interactive)
annotation_content.updated	annotation + content, document, updated_datapoints	operations, messages	Annotation data was updated by the user	no (interactive)
annotation_content.confirm	annotation + content, document, updated_datapoints (empty)	operations, messages	User confirmed validation screen	no (interactive)
annotation_content.export	annotation + content, document, updated_datapoints (empty)	operations, messages	Annotation is being moved to exported state	yes
upload.created	files, documents, metadata, email, upload	files	Upload object was created	yes
email.received	files, headers, body, email, queue	files (*)	Email with attachments was received	yes
invocation.scheduled	N/A	N/A	Hook was invoked at the scheduled time	yes

(*) May also contain other optional attributes - read more in this section.

Example webhook request payload for email.received event:

{
  "request_id": "ae7bc8dd-73bd-489b-a3d2-f5214b209591",
  "timestamp": "2020-01-01T00:00:00.000000Z",
  "base_url": "https://example.rossum.app",
  "rossum_authorization_token": "1024873d424a007d8eebff7b3684d283abdf7d0d",
  "hook": "https://example.rossum.app/api/v1/hooks/781",
  "settings": {
    "example_target_hostname": "sftp.elis.rossum.ai"
  },
  "secrets": {
    "password": "secret-importer-user-password"
  },
  "action": "received",
  "event": "email",
  "email": "https://example.rossum.app/api/v1/emails/987",
  "queue": "https://example.rossum.app/api/v1/queues/41",
  "files": [
    {
      "id": "1",
      "filename": "image.png",
      "mime_type": "image/png",
      "n_pages": 1,
      "height_px": 100.0,
      "width_px": 150.0,
      "document": "https://example.rossum.app/api/v1/documents/427"
    },
    {
      "id": "2",
      "filename": "MS word.docx",
      "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "n_pages": 1,
      "height_px": null,
      "width_px": null,
      "document": "https://example.rossum.app/api/v1/documents/428"
    },
    {
      "id": "3",
      "filename": "A4 pdf.pdf",
      "mime_type": "application/pdf",
      "n_pages": 3,
      "height_px": 3510.0,
      "width_px": 2480.0,
      "document": "https://example.rossum.app/api/v1/documents/429"
    },
    {
      "id": "4",
      "filename": "unknown_file",
      "mime_type": "text/xml",
      "n_pages": 1,
      "height_px": null,
      "width_px": null,
      "document": "https://example.rossum.app/api/v1/documents/430"
    }
  ],
  "headers": {
    "from": "test@example.com",
    "to": "east-west-trading-co-a34f3a@example.rossum.app",
    "reply-to": "support@example.com",
    "subject": "Some subject",
    "date": "Mon, 04 May 2020 11:01:32 +0200",
    "message-id": "15909e7e68e4b5f56fd78a3b4263c4765df6cc4d",
    "authentication-results": "example.com;\n    dmarc=pass d=example.com"
  },
  "body": {
    "body_text_plain": "Some body",
    "body_text_html": "<div dir=\"ltr\">Some body</div>"
  }
}

Example webhook response for email.received event:

{
  "files": [
    {
      "id": "3",
      "values": [
        {
          "id": "email:invoice_id",
          "value": "INV001234"
        },
        {
          "id": "email:customer_name",
          "value": "John Doe"
        }
      ]
    }
  ],
  "additional_files": [
    {
      "document": "https://example.rossum.app/api/v1/documents/987",
      "import_document": true,
      "values": [
        {
          "id": "email:internal_id",
          "value": "0045654"
        }
      ]
    }
  ]
}

Example webhook request payload for invocation.scheduled event:

{
  "request_id": "ae7bc8dd-73bd-489b-a3d2-f5514b209591",
  "timestamp": "2020-01-01T00:00:00.000000Z",
  "base_url": "https://example.rossum.app",
  "rossum_authorization_token": "1024873d424a007d8eebff7b3684d283abdf7d0d",
  "hook": "https://example.rossum.app/api/v1/hooks/789",
  "settings": {
    "example_target_service_type": "SFTP",
    "example_target_hostname": "sftp.elis.rossum.ai"
  },
  "secrets": {
    "username": "my-rossum-importer",
    "password": "secret-importer-user-password"
  },
  "action": "scheduled",
  "event": "invocation"
}

Example webhook request payload for upload.created event:

{
  "request_id": "ae7bc8dd-73bd-489b-a3d2-f5214b209591",
  "timestamp": "2020-01-01T00:00:00.000000Z",
  "base_url": "https://example.rossum.app",
  "rossum_authorization_token": "1024873d424a007d8eebff7b3684d283abdf7d0d",
  "hook": "https://example.rossum.app/api/v1/hooks/781",
  "settings": {},
  "secrets": {},
  "action": "created",
  "event": "upload",
  "email": "https://example.rossum.app/api/v1/emails/987",
  "upload": "https://example.rossum.app/api/v1/uploads/2046",
  "metadata": {},
  "files": [
    {
      "document": "https://example.rossum.app/api/v1/documents/427",
      "prevent_importing": false,
      "values": [],
      "queue": "https://example.rossum.app/api/v1/queues/41",
      "annotation": null
    },
    {
      "document": "https://example.rossum.app/api/v1/documents/428",
      "prevent_importing": true,
      "values": [],
      "queue": "https://example.rossum.app/api/v1/queues/41",
      "annotation": "https://example.rossum.app/api/v1/annotations/1638"
    }
  ],
  "documents": [
    {
      "id": 427,
      "url": "https://example.rossum.app/api/v1/documents/427",
      "mime_type": "application/pdf"
    },
    {
      "id": 428,
      "url": "https://example.rossum.app/api/v1/documents/428",
      "mime_type": "application/json"
    }
  ]
}

Example webhook response for upload.created event:

{
  "files": [
    {
      "document": "https://example.rossum.app/api/v1/documents/427",
      "prevent_importing": false,
      "messages": [
        {"type": "error", "content": "Some error message."}
      ]
    },
    {
      "document": "https://example.rossum.app/api/v1/documents/428",
      "prevent_importing": true
    },
    {
      "document": "https://example.rossum.app/api/v1/documents/429"
    },
    {
      "document": "https://example.rossum.app/api/v1/documents/430",
      "messages": [
        {"type": "info", "content": "Some info message."}
      ]
    }
  ]
}

Note: The annotation_content.started, annotation_content.updated and the deprecated annotation_content.user_update are triggered from the backend within the /validate resource call.

• When annotation_content.export action fails, annotation is switched to the failed_export state.
• When response from webhook on annotation_content.export contains a message of type error, the annotation is switched to the failed_export state.
• The updated_datapoints list is never empty for annotation_content.updated only triggered by interactive date changes actions.
• The updated_datapoints list is always empty for the annotation_content.export action.
• The updated_datapoints list is empty for the annotation_content.initialize action if run_after=[], but it can have data from its predecessor if chained via run_after.
• The updated_datapoints list may also be empty for annotation_content.user_update in case of an action triggered interactively by a user, but with no data changes (e.g. after opening validation screen or eventually at its confirmation issued by the Rossum UI).

Timeouts and retries

• For each webhook call there is a 30 seconds timeout by default (this applies to all events and actions). It can be modified in config with attribute timeout_s (min=0, max=60, only for non-interactive webhooks).
• In case a non-interactive webhook call fails (check the configuration of retry_on_any_non_2xx attribute of the webhook to see what statuses this includes), it is retried within 30 seconds by default. There are up to 5 attempts performed. This number can be modified in config with attribute retry_count (min=0, max=4, only for non-interactive webhooks).

Warning: In case of an interactive webhook call, the attribute timeout_s in config will be overwritten to default value 30 seconds.

Asynchronous webhooks

Non-interactive webhooks can use also asynchronous framework:

• Webhook returns an HTTP status 202 and url for polling in the response Location header.
• The provided polling url is polled every 30 seconds until a response with 201 status code is received. The response body is then taken as the hook call result.
• The polling continues until 201 response is received or until the maximum polling time is exceeded. See the max_polling_time_s attribute of the hook.config for more details.
• In case the polling request returns one of the following status codes: 408, 429, 500, 502, 503, 504, it is retried and the polling continues. (This is not considered a polling failure.)
• In case the polling request fails (returns any error status code other than 408, 429, 500, 502, 503, 504 or exceeds the maximum polling time), the original webhook call is retried (by default). The number of retry attempts is set by the retry_count attribute of the hook.config.
• Retries after polling can be enabled/disabled by the retry_after_polling_failure attribute of the hook.config.

Webhook Events Occurrence Diagram

To show an overview of the Hook events and when they are happening, this diagram was created.

Hooks common attributes

Key	Type	Description
request_id	UUID	Hook call request ID
timestamp	datetime	Timestamp when the hook was called
hook	URL	Hook's url
action	string	Hook's action
event	string	Hook's event
settings	object	Copy of hook.settings attribute

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
emails*	list[object]	list of related email objects (for annotations created after email ingestion)
related_emails*	list[object]	list of related emails objects (other related emails)
relations*	list[object]	list of related relation objects
child_relations*	list[object]	list of related child_relation objects
suggested_edits*	list[object]	list of related suggested_edits objects
assignees*	list[object]	list of related assignee objects
pages*	list[object]	list of related pages objects
notes*	list[object]	list of related notes objects
labels*	list[object]	list of related labels objects
automation_blockers*	list[object]	list of related automation_blockers objects

^* Attribute is only included in the request when specified in hook.sideload. Please note that sideloading of modifier object from different organization is not supported and that sideloading can decrease performance. See also annotation sideloading section.

Example webhook request payload with sideloaded queues:

{
  "request_id": "ae7bc8dd-73bd-489b-a3d2-f5214b209591",
  "timestamp": "2020-01-01T00:00:00.000000Z",
  "base_url": "https://example.rossum.app",
  "hook": "https://example.rossum.app/api/v1/hooks/781",
  "action": "changed",
  "event": "annotation_status",
  "queues": [
    {
      "id": 8198,
      "name": "Received invoices",
      "url": "https://example.rossum.app/api/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 or all predecessor events.
queues*	list[object]	list of related queue objects
modifiers*	list[object]	list of related modifier objects
schemas*	list[object]	list of related schema objects
emails*	list[object]	list of related email objects (for annotations created after email ingestion)
related_emails*	list[object]	list of related emails objects (other related emails)
relations*	list[object]	list of related relation objects
child_relations*	list[object]	list of related child_relation objects
suggested_edits*	list[object]	list of related suggested_edits objects
assignees*	list[object]	list of related assignee objects
pages*	list[object]	list of related pages objects
notes*	list[object]	list of related notes objects
labels*	list[object]	list of related labels objects
automation_blockers*	list[object]	list of related automation_blockers objects

^* Attribute is only included in the request when specified in hook.sideload. Please note that sideloading of modifier object from different organization is not supported and that sideloading can decrease performance. See also annotation sideloading section.

^** If the run_after attribute chains the hooks, the updated_datapoints will contain a list of all datapoint ids that were updated by any of the predecessive hooks. Moreover, in case of add operation on a multivalue table, the updated_datapoints will contain the id of the multivalue, the id of the new tuple datapoints and the id of all the newly created cell datapoints.

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 relevant 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
detail	object	Detail object that enhances the response from a hook. (For more info refer to message detail)

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 supplier's 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.

Note: User visible messages that are returned from the hooks can contain the following list of HTML markup elements: b, strong, a, ul, ol, li, i, br. This markup enables better readability of the message to the user.

Parsable error response format

It's possible to use the same format even with non-2XX response codes. In this type of response, operations are not considered.

Example payload for parsable error response:

{
  "messages": [
    {
      "id": "all",
      "type": "error",
      "content": "custom error message to be displayed in the UI"
    }
  ]
}

initialize event of annotation_content action additionally accepts list of automation_blockers objects. This allows for manual creation of automation blockers of type extension and therefore stops the automation without the need to create an error message.

The automation_blockers object contains attributes

Key	Type	Description
id	integer	Optional unique id of the relevant datapoint; omit for a document-wide issues
content	str	A descriptive message to be stored as an automation blocker

Example response payload with automation blockers:

{
  "messages": [],
  "operations": [],
  "automation_blockers": [
    {
      "id": 1357,
      "content": "Unregistered vendor"
    },
    {
      "content": "PO not found in the master data!"
    }
  ]
}

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.
body	object	Body extracted from the arriving email.
email	URL	URL of the arriving email.
queue	URL	URL of the arriving email's queue.

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).
document	URL	URL of related document object.

The headers object contains the same values as are available for initialization of values in email_header:<id> (namely: from, to, reply-to, subject, message-id, date).

The body object contains the body_text_plain and body_text_html.

Email received event response format

All of the email events expect a JSON object with the following lists in the response: files, additional_files, extracted_original_sender

The files object contains attributes:

Key	Type	Description
id	int	id of file that will be used for creating an annotation
values	list[object]	This is used to initialize datapoint values. See values object description below

The values object consists of the following:

Key	Type	Description
id	string	Id of value - must start with email: prefix (to use this value refer to it in rir_field_names field in the schema similarly as described here).
value	string	String value to be used when annotation content is being constructed

This is useful for filtering out unwanted files by some measures that are not available in Rossum by default.

Note: When all files are to be used for creating annotations (ie no filtering should occur), all have to appear in the files list.

Note: If there are multiple hooks configured for the event, annotations are created only for files mentioned in all the responses (their values are merged together with the latest called hooks having the highest priority).

The additional_files object contains attributes:

Key	Type	Default	Required	Description
document	URL		yes	URL of the document object that should be included. If document belongs to an annotation it must also belong to the same queue as email inbox.
values	list[object]	[]	no	This is used to initialize datapoint values. See values object description above
import_document	bool	false	no	Set to true if Rossum should import document and create an annotation for it, otherwise it will be just linked as an email attachment. Only applicable if document hasn't already an annotation attached.

The extracted_original_sender object looks as follows:

Key	Type	Description
extracted_original_sender	email_address_object	Information about sender containing keys email and name.

This is useful for updating the email address field on email object with a new sender name and email address.

Note: If there are multiple hooks configured for the event, the extracted_original_sender results are merged together (with the latest called hooks having the highest priority).

Upload created event data format

upload event contains following additional event specific attributes.

Key	Type	Description
files	list[object]	List of objects with metadata of each uploaded document.
documents	list[object]	List of document objects corresponding with the files object.
upload	object	Object representing the upload.
metadata	object	Client data passed in through the upload resource to create annotations with.
email	URL	URL of the arriving email or null if the document was uploaded via API.

The files object contains attributes:

Key	Type	Description
document	URL	URL of the uploaded document object.
prevent_importing	bool	If set no annotation is going to be created for the document or if already existing it is not going to be switched to importing status.
values	list[object]	This is used to initialize datapoint values. See values object description below
queue	URL	URL of the queue the document is being uploaded to.
annotation	URL	URL of the documents annotation or null if it doesn't exist.

The values object consists of the following:

Key	Type	Description
id	string	Id of value (to use this value refer to it in rir_field_names field in the schema similarly as described here).
value	string	String value to be used when annotation content is being constructed

Upload created event response format

All of the upload events expect a JSON object with the files object list in the response.

The files object contains attributes:

Key	Type	Description	Required
document	URL	URL of the uploaded document object.	true
prevent_importing	bool	If set no annotation is going to be created for the document or if already exists it is not going to be switched to importing status. Optional, default false.	false
messages	list[object]	List of messages that will be appended to the related annotation.	false

Validating payloads from Rossum

Example of a webhook payload validator written in Python:

import hashlib
import hmac

from flask import Flask, request, abort

app = Flask(__name__)

SECRET_KEY = "<Your secret key stored in hook.config.secret>"

@app.route("/test_hook", methods=["POST"])
def test_hook():
    digest = hmac.new(SECRET_KEY.encode(), request.data, hashlib.sha256).hexdigest()
    try:
        prefix, signature = request.headers["X-Rossum-Signature-SHA256"].split("=")
    except ValueError:
        abort(401, "Incorrect header format")

    if not (prefix == "sha256" 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-Rossum-Signature-SHA256.

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 SHA256 signature by default.

Previously, Rossum was using SHA1 algorithm to sign the payload. This option is still available as a legacy X-Elis-Signature header. Please contact Rossum support to enable this header in case it is missing.

Note: The algorithm used is the same as the one of Github.

Webhook requests may also be authenticated using a client SSL certificate, see Hook API for reference.

Access to Rossum API

You can access Rossum API from the Webhook. Each execution gets unique API key. The key is valid for 10 minutes or until Rossum receives a response from the Webhook. You can set token_lifetime_s up to 2 hours to keep the token valid longer. The API key and the environment's base URL are passed to webhooks as a first-level attributes rossum_authorization_token and base_url within the webhook payload.

Serverless functions allow 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 set up 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 and Python to execute serverless functions. See the table below for a full list of supported runtimes. 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.

Name	Identifier	Deprecation date	Block function creation date	Removal date	Note
Python 3.12	python3.12	not scheduled	not scheduled	not scheduled
NodeJS 22	nodejs22.x	not scheduled	not scheduled	not scheduled

Runtime deprecations

We schedule runtime deprecation when it is being phased out by the serverless vendors. The recommended action is to upgrade to one of the up-to-date runtimes.

See the table above for specific deprecation dates of individual runtimes.

• Deprecation date - Date when the deprecation is announced.
• Block function creation date - From this date, it will not be possible to create new extensions with the deprecated runtime. Existing extensions can be used as they are and their code can be updated until the removal date.
• Removal date - All extensions will be automatically switched to the up-to-date runtime on this date. We recommend making the switch earlier to test and update the code if needed, to avoid any issues.

Python Runtime and Rossum Transaction Scripts

The python3.12 runtime includes a txscript module that provides convenience functionality for working with Rossum objects, in particular in the context of the annotation_content event.

Implementation

'''
This custom serverless function example demonstrates showing messages to the
user on the validation screen, updating values of specific fields, and
executing actions on the annotation.

See https://elis.rossum.ai/api/docs/#rossum-transaction-scripts for more examples.
'''

from txscript import TxScript, default_to, substitute

def rossum_hook_request_handler(payload: dict) -> dict:
    t = TxScript.from_payload(payload)

    for row in t.field.line_items:
        if default_to(row.item_amount_base, 0) >= 1000000:
            t.show_warning('Value is too big', row.item_amount_base)

    t.field.document_id = substitute(r'-', '', t.field.document_id)

    if default_to(t.field.amount_total, 0) > 1000000:
        print("postponing")
        t.annotation.action("postpone")
        return t.hook_response()

    return t.hook_response()

// This serverless function example can be used for annotation_content events
// (e.g. updated 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.

exports.rossum_hook_request_handler = async (payload) => {
  const content = payload.annotation.content;

  try {
    const TOO_BIG_THRESHOLD = 1000000;

    const amountBaseColumnDatapoints = findBySchemaId(
      content,
      'item_amount_base',
    );

    const messages = [];
    for (var i = 0; i < amountBaseColumnDatapoints.length; i++) {

      if (amountBaseColumnDatapoints[i].content.normalized_value >= TOO_BIG_THRESHOLD) {
        messages.push(
          createMessage(
            'warning',
            'Value is too big',
            amountBaseColumnDatapoints[i].id,
          ),
        );
      }
    }

    const [invoiceIdDatapoint] = findBySchemaId(content, 'invoice_id');

    const operations = [
      createReplaceOperation(
        invoiceIdDatapoint,
        invoiceIdDatapoint.content.value.replace(/-/g, ''),
      ),
    ];

    return {
      messages,
      operations,
    };
  } catch (e) {
    const messages = [
      createMessage('error', 'Serverless Function: ' + e.message)
    ];
    return {
      messages,
    };
  }
};

const findBySchemaId = (content, schemaId) =>
  content.reduce(
    (results, dp) =>
    dp.schema_id === schemaId ? [...results, dp] :
    dp.children ? [...results, ...findBySchemaId(dp.children, schemaId)] :
    results,
    [],
  );

const createMessage = (type, content, datapointId = null) => ({
  content: content,
  type: type,
  id: datapointId,
});

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. You can use a code editor built-in to the Rossum UI, which also allows to test and debug the function before updating the code of the function itself.

See Python and NodeJS examples of a serverless function implementation next to this section or check out this article (and others in the relevant section).

Warning: Please note that users are responsible for their code that is being executed. Be sure not to expose any sensitive data or trigger excessive usage of the function API. In case of violation of the Rossum terms of use, the organization account may be suspended.

If there is an issue with an extension code itself, it will be displayed as CallFunctionException in the annotation view. Raising this exception usually means issues such as:

• undefined variables are called in the code
• the code is raising an exception as a response rather than returning a proper response

Testing

To write, test and debug a serverless function, you can refer to this guide.

Limitations

By default, no internet access is allowed from a serverless function, except the Rossum API. 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.

Access Rossum API

The Rossum API can be accessed directly from serverless functions. See examples below for how to access the Rossum API from a serverless function.

import json
import urllib.request

def rossum_hook_request_handler(payload):
    request = urllib.request.Request(
      "https://example.rossum.app/api/v1/queues",
      headers={"Authorization": "Bearer " + payload["rossum_authorization_token"]}
    )
    with urllib.request.urlopen(request) as response:
        queues = json.loads(response.read())
    queue_names = (q["name"] for q in queues["results"])
    return {"messages": [{"type": "info", "content": ", ".join(queue_names)}]}

const https = require('https');

exports.rossum_hook_request_handler = async (payload) => {
  const token = payload.rossum_authorization_token;

  queues = JSON.parse(await getFromRossumApi("https://example.rossum.app/api/v1/queues", token));
  queue_names = queues.results.map(q => q.name).join(", ")
  return { "messages": [{"type": "info", "content": queue_names}] };
}

const getFromRossumApi = async (url, token) => {
  const parsedUrl = new URL(url);
  const options = {
    hostname: parsedUrl.hostname,
    path: parsedUrl.pathname + parsedUrl.search,
    method: 'GET',
    headers: {
      'Authorization': 'Bearer ' + token,
    },
  };
  const response = await new Promise((resolve, reject) => {
    let dataString = '';
    const req = https.request(options, function(res) {
      res.on('data', chunk => {
        dataString += chunk;
      });
      res.on('end', () => {
        resolve({
          statusCode: 200,
          body: dataString
        });
      });
    });
    req.on('error', (e) => {
      reject({
        statusCode: 500,
        body: 'Something went wrong!'
      });
    });
    req.end()
  });
  return response.body
}