Annotation Content
Annotation content is used by the Rossum UI to display annotation content. Be aware that values in attribute value are not normalized (e.g. numbers, dates) and data structure may be changed to accommodate UI requirements.
Use export endpoint to download extracted data using a stable interface with normalized values. It supports various data formats (JSON, XML, CSV).
Time Spent
Time spent on datapoint are in seconds and are stored on datapoint object, for category multivalue or datapoint. For time spent on the annotation level, see annotation processing duration.
Active time spent is stored in time_spent. Overall time spent is stored in time_spent_overall. Active time spent with an active magic grid is stored in time_spent_grid. Overall time spent with an active magic grid is stored in time_spent_grid_overall.
Measuring starts when an annotation is not in a read-only mode after selecting a datapoint.
Measuring ends when:
- Another datapoint is selected. Selecting of datapoints when showing automation blockers doesn’t end or affect the measuring.
- The user leaves an annotation (for the same reasons as measuring ends on an annotation)
- The user goes to edit mode
When a measuring ends time_spent of the previously selected datapoint is incremented by measured time_spent and the result is patched together with adding a human validation source to validation sources.
Formula Datapoints
For datapoint category fields which have their schema UI configuration's type
property set to formula the datapoint content and attributes are being updated
automatically based on the provided formula code.
For editable formula fields (i.e. the corresponding UI configuration's edit
property is not set to disabled option) the automatic recalculation can be
disabled by setting the datapoint no_recalculation flag to true. To re-enable
the formula automatic recalculation set the no_recalculation flag to false.
Updates of formula datapoints properties and values via API are only available for invocations done from the UI.
Validation Source
The validation_sources property is a list of sources that verified the extracted data. When the list is non-empty, datapoint is considered to be validated (and no eye-icon is displayed next to it in the Rossum UI).
Currently, these are the sources of validation:
- score: confidence score coming from the AI Core Engine was equal or higher than a preset score threshold (can be set on queue, or individually per datapoint in schema; default is 0.8).
- checks: Data extractor does several checks like summing up tax_details, which can verify that the data were extracted correctly.
- not_found: Value was not found by the AI engine. As we do not report confidence in such cases yet, we add a validation source instead. It will be removed as soon as we have confidence present for field that were not found.
- data_matching: Set by a hook when, for example, the datapoint matches some other database.
- history: Several fields can be confirmed from historical data in exported documents (can be turned on/off on per queue basis using autopilot section in its settings).
- connector: A connector verified the validity.
- table_suggester: Used internally for the complex line items user interface.
- rules: Added from rules and actions on a queue.
- einvoicing: Used when the value is verified against e-invoicing data sources or external e-invoicing systems.
- human: An operator visited the field in validation interface (assumed just verifying the value, not necessarily making any corrections).
- non_required: Value was not found, is non-required and has no rir_field_name set.
- NA: Validation sources are "Not Applicable" and may now occur only for button datapoints.
The list is subject to ongoing expansion.
Grid
Grid object (for internal use only) is used to store table vertical and horizontal separators and related attributes. Every grid consists of
zero or more parts.
Currently, it is only allowed to have one part per page (for a particular grid).
If two or more tables that should be extracted are present on one page, the grid
object should be placed over the area of all of them. The parts that do not
include the needed data should be marked as a row with "type": null value of
the grid object.
Annotation content section
A unique ID of a given section.
URL of the section.
Reference mapping the object to the schema tree.
The category of the object, which is 'section'.
Retrieve annotation content
GET api / v1 / annotations / {annotationID} / content
Returns annotation content in a form of datapoint tree.
curl -X GET "https://example.rossum.app/api/v1/annotations/0/content"{
"content": [
{
"id": 197466,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/197466",
"schema_id": "invoice_info_section",
"category": "section",
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "multivalue",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "tuple",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "datapoint",
"hidden": true,
"content": {
"value": "8/12/24",
"normalized_value": "12-08-2024",
"page": 1,
"position": [
202.3,
100.1,
110.442,
110
],
"rir_text": "8/12/24",
"rir_raw_text": "8/I2/24",
"rir_page": 1,
"rir_position": [
202.3,
100.1,
110.442,
110
],
"rir_confidence": 0.954233451,
"connector_text": "8/I2/24",
"connector_position": [
200,
100,
110,
110
],
"ocr_text": null,
"ocr_raw_text": null,
"ocr_position": null
},
"validation_sources": [
"score"
],
"time_spent": 0.1,
"time_spent_overall": 0.1,
"no_recalculation": false
}
]
}
],
"grid": {
"parts": [
{
"page": 1,
"columns": [
{
"left_position": 12.1,
"schema_id": "item_description",
"header_texts": [
"Item description"
]
}
],
"rows": [
{
"top_position": 112.29,
"tuple_id": 1,
"type": "data"
}
],
"width": 123.2,
"height": 513.2
}
]
},
"time_spent": 0.1,
"time_spent_overall": 0.1,
"time_spent_grid": 0.1,
"time_spent_grid_overall": 0.1
}
]
}
],
"results": []
}{
"detail": "Bad Request.",
"code": "bad_request"
}{
"detail": "Invalid token.",
"code": "authentication_failed"
}{
"detail": "Access to the requested resource is forbidden.",
"code": "access_forbidden"
}{
"detail": "Not found.",
"code": "not_found"
}{
"detail": "Conflict.",
"code": "conflict_status"
}{
"detail": "Request was rate limited.",
"code": "rate_limited",
"url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}{
"detail": "Server error.",
"code": "error"
}{
"detail": "Bad Gateway.",
"code": "bad_gateway"
}{
"detail": "Service Unavailable.",
"code": "service_unavailable"
}{
"detail": "Gateway timeout.",
"code": "gateway_timeout"
}Response
OK
Invalid input data.
Detail of the error
Code of the error
The username/password is invalid or token is invalid (e.g. expired).
Detail of the error
Code of the error
Insufficient permission, missing authentication, invalid CSRF token and similar issue.
Detail of the error
Code of the error
The specified resource was not found.
Detail of the error
Code of the error
Conflict
Detail of the error
Code of the error
Request rate is too high, wait before sending more requests. See Rate Limiting for more details.
Detail of the error
Code of the error
Link to the rate limiting documentation
Server failure while processing the request.
Detail of the error
Code of the error
Invalid response from the upstream server.
Detail of the error
Code of the error
We're temporarily offline for maintenance. Please try again later.
Detail of the error
Code of the error
Upstream server could not complete the request in time.
Detail of the error
Code of the error
Update annotation content
PATCH api / v1 / annotations / {annotationID} / content
Update annotation content. The format is the same as for GET. Datapoints missing from the payload keep their previous values.
For multivalue (table) datapoints, rows in the payload are matched to existing rows by position: extra rows in the payload are appended, and existing rows beyond the end of the payload are removed. Within a row:
- For an existing row, columns missing from the payload keep their previous values.
- For a newly appended row, columns missing from the payload are filled from the
schema's
default_value(and remain empty if the schema declares no default).
curl -X PATCH "https://example.rossum.app/api/v1/annotations/0/content" \ -H "Content-Type: application/json" \ -d '{}'{
"content": [
{
"id": 197466,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/197466",
"schema_id": "invoice_info_section",
"category": "section",
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "multivalue",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "tuple",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "datapoint",
"hidden": true,
"content": {
"value": "8/12/24",
"normalized_value": "12-08-2024",
"page": 1,
"position": [
202.3,
100.1,
110.442,
110
],
"rir_text": "8/12/24",
"rir_raw_text": "8/I2/24",
"rir_page": 1,
"rir_position": [
202.3,
100.1,
110.442,
110
],
"rir_confidence": 0.954233451,
"connector_text": "8/I2/24",
"connector_position": [
200,
100,
110,
110
],
"ocr_text": null,
"ocr_raw_text": null,
"ocr_position": null
},
"validation_sources": [
"score"
],
"time_spent": 0.1,
"time_spent_overall": 0.1,
"no_recalculation": false
}
]
}
],
"grid": {
"parts": [
{
"page": 1,
"columns": [
{
"left_position": 12.1,
"schema_id": "item_description",
"header_texts": [
"Item description"
]
}
],
"rows": [
{
"top_position": 112.29,
"tuple_id": 1,
"type": "data"
}
],
"width": 123.2,
"height": 513.2
}
]
},
"time_spent": 0.1,
"time_spent_overall": 0.1,
"time_spent_grid": 0.1,
"time_spent_grid_overall": 0.1
}
]
}
]
}{
"detail": "Bad Request.",
"code": "bad_request"
}{
"detail": "Invalid token.",
"code": "authentication_failed"
}{
"detail": "Access to the requested resource is forbidden.",
"code": "access_forbidden"
}{
"detail": "Not found.",
"code": "not_found"
}{
"detail": "Conflict.",
"code": "conflict_status"
}{
"detail": "Payload Too Large.",
"code": "payload_too_large"
}{
"detail": "Request was rate limited.",
"code": "rate_limited",
"url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}{
"detail": "Server error.",
"code": "error"
}{
"detail": "Bad Gateway.",
"code": "bad_gateway"
}{
"detail": "Service Unavailable.",
"code": "service_unavailable"
}{
"detail": "Gateway timeout.",
"code": "gateway_timeout"
}Request Body
application/json
Response
OK
Invalid input data.
Detail of the error
Code of the error
The username/password is invalid or token is invalid (e.g. expired).
Detail of the error
Code of the error
Insufficient permission, missing authentication, invalid CSRF token and similar issue.
Detail of the error
Code of the error
The specified resource was not found.
Detail of the error
Code of the error
Conflict
Detail of the error
Code of the error
Payload too large (especially for files uploaded).
Detail of the error
Code of the error
Request rate is too high, wait before sending more requests. See Rate Limiting for more details.
Detail of the error
Code of the error
Link to the rate limiting documentation
Server failure while processing the request.
Detail of the error
Code of the error
Invalid response from the upstream server.
Detail of the error
Code of the error
We're temporarily offline for maintenance. Please try again later.
Detail of the error
Code of the error
Upstream server could not complete the request in time.
Detail of the error
Code of the error
Add row to multivalue datapoint
POST api / v1 / annotations / {annotationID} / content / {nodeID} / add_empty
Adds a row to a multivalue table. This row will not be connected to the grid and modifications of the grid will not trigger any OCR on the cells of this row.
curl -X POST "https://example.rossum.app/api/v1/annotations/0/content/0/add_empty"{}{
"detail": "Bad Request.",
"code": "bad_request"
}{
"detail": "Invalid token.",
"code": "authentication_failed"
}{
"detail": "Access to the requested resource is forbidden.",
"code": "access_forbidden"
}{
"detail": "Not found.",
"code": "not_found"
}{
"detail": "Conflict.",
"code": "conflict_status"
}{
"detail": "Payload Too Large.",
"code": "payload_too_large"
}{
"detail": "Request was rate limited.",
"code": "rate_limited",
"url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}{
"detail": "Server error.",
"code": "error"
}{
"detail": "Bad Gateway.",
"code": "bad_gateway"
}{
"detail": "Service Unavailable.",
"code": "service_unavailable"
}{
"detail": "Gateway timeout.",
"code": "gateway_timeout"
}Response
Row added successfully.
responseobjectInvalid input data.
Detail of the error
Code of the error
The username/password is invalid or token is invalid (e.g. expired).
Detail of the error
Code of the error
Insufficient permission, missing authentication, invalid CSRF token and similar issue.
Detail of the error
Code of the error
The specified resource was not found.
Detail of the error
Code of the error
Conflict
Detail of the error
Code of the error
Payload too large (especially for files uploaded).
Detail of the error
Code of the error
Request rate is too high, wait before sending more requests. See Rate Limiting for more details.
Detail of the error
Code of the error
Link to the rate limiting documentation
Server failure while processing the request.
Detail of the error
Code of the error
Invalid response from the upstream server.
Detail of the error
Code of the error
We're temporarily offline for maintenance. Please try again later.
Detail of the error
Code of the error
Upstream server could not complete the request in time.
Detail of the error
Code of the error
Bulk update annotation content
POST api / v1 / annotations / {annotationID} / content / operations
Allows to specify a sequence of operations that should be performed on particular datapoint objects.
To replace a datapoint value (or other supported attribute), use replace operation.
To add a new row into a table multivalue, use add operation.
To remove a row from a multivalue, use remove operation.
Please note that only multivalue children datapoints may be removed.
Please note that section, multivalue and tuple should not be updated.
curl -X POST "https://example.rossum.app/api/v1/annotations/0/content/operations" \ -H "Content-Type: application/json" \ -d '{ "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": [ 100, 100, 200, 200 ], "value": "Some description" } } ] } ] }'{
"content": [
{
"id": 197466,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/197466",
"schema_id": "invoice_info_section",
"category": "section",
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "multivalue",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "tuple",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "datapoint",
"hidden": true,
"content": {
"value": "8/12/24",
"normalized_value": "12-08-2024",
"page": 1,
"position": [
202.3,
100.1,
110.442,
110
],
"rir_text": "8/12/24",
"rir_raw_text": "8/I2/24",
"rir_page": 1,
"rir_position": [
202.3,
100.1,
110.442,
110
],
"rir_confidence": 0.954233451,
"connector_text": "8/I2/24",
"connector_position": [
200,
100,
110,
110
],
"ocr_text": null,
"ocr_raw_text": null,
"ocr_position": null
},
"validation_sources": [
"score"
],
"time_spent": 0.1,
"time_spent_overall": 0.1,
"no_recalculation": false
}
]
}
],
"grid": {
"parts": [
{
"page": 1,
"columns": [
{
"left_position": 12.1,
"schema_id": "item_description",
"header_texts": [
"Item description"
]
}
],
"rows": [
{
"top_position": 112.29,
"tuple_id": 1,
"type": "data"
}
],
"width": 123.2,
"height": 513.2
}
]
},
"time_spent": 0.1,
"time_spent_overall": 0.1,
"time_spent_grid": 0.1,
"time_spent_grid_overall": 0.1
}
]
}
]
}{
"detail": "Bad Request.",
"code": "bad_request"
}{
"detail": "Invalid token.",
"code": "authentication_failed"
}{
"detail": "Access to the requested resource is forbidden.",
"code": "access_forbidden"
}{
"detail": "Not found.",
"code": "not_found"
}{
"detail": "Conflict.",
"code": "conflict_status"
}{
"detail": "Payload Too Large.",
"code": "payload_too_large"
}{
"detail": "Request was rate limited.",
"code": "rate_limited",
"url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}{
"detail": "Server error.",
"code": "error"
}{
"detail": "Bad Gateway.",
"code": "bad_gateway"
}{
"detail": "Service Unavailable.",
"code": "service_unavailable"
}{
"detail": "Gateway timeout.",
"code": "gateway_timeout"
}Request Body
application/json
Response
OK
Invalid input data.
Detail of the error
Code of the error
The username/password is invalid or token is invalid (e.g. expired).
Detail of the error
Code of the error
Insufficient permission, missing authentication, invalid CSRF token and similar issue.
Detail of the error
Code of the error
The specified resource was not found.
Detail of the error
Code of the error
Conflict
Detail of the error
Code of the error
Payload too large (especially for files uploaded).
Detail of the error
Code of the error
Request rate is too high, wait before sending more requests. See Rate Limiting for more details.
Detail of the error
Code of the error
Link to the rate limiting documentation
Server failure while processing the request.
Detail of the error
Code of the error
Invalid response from the upstream server.
Detail of the error
Code of the error
We're temporarily offline for maintenance. Please try again later.
Detail of the error
Code of the error
Upstream server could not complete the request in time.
Detail of the error
Code of the error
Convert grid to table data
POST api / v1 / annotations / {annotationID} / content / {nodeID} / transform_grid_to_datapoints
Transform grid structure to tabular data of related multivalue object.
This endpoint will be deprecated in the near future. It will be fully removed in the future. Please use the grid operations and partial grid operations endpoints.
curl -X POST "https://example.rossum.app/api/v1/annotations/0/content/0/transform_grid_to_datapoints"{}{
"detail": "Bad Request.",
"code": "bad_request"
}{
"detail": "Invalid token.",
"code": "authentication_failed"
}{
"detail": "Access to the requested resource is forbidden.",
"code": "access_forbidden"
}{
"detail": "Not found.",
"code": "not_found"
}{
"detail": "Conflict.",
"code": "conflict_status"
}{
"detail": "Payload Too Large.",
"code": "payload_too_large"
}{
"detail": "Request was rate limited.",
"code": "rate_limited",
"url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}{
"detail": "Server error.",
"code": "error"
}{
"detail": "Bad Gateway.",
"code": "bad_gateway"
}{
"detail": "Service Unavailable.",
"code": "service_unavailable"
}{
"detail": "Gateway timeout.",
"code": "gateway_timeout"
}Response
All tuple datapoints and their children are returned.
responseobjectInvalid input data.
Detail of the error
Code of the error
The username/password is invalid or token is invalid (e.g. expired).
Detail of the error
Code of the error
Insufficient permission, missing authentication, invalid CSRF token and similar issue.
Detail of the error
Code of the error
The specified resource was not found.
Detail of the error
Code of the error
Conflict
Detail of the error
Code of the error
Payload too large (especially for files uploaded).
Detail of the error
Code of the error
Request rate is too high, wait before sending more requests. See Rate Limiting for more details.
Detail of the error
Code of the error
Link to the rate limiting documentation
Server failure while processing the request.
Detail of the error
Code of the error
Invalid response from the upstream server.
Detail of the error
Code of the error
We're temporarily offline for maintenance. Please try again later.
Detail of the error
Code of the error
Upstream server could not complete the request in time.
Detail of the error
Code of the error
Grid operations
POST api / v1 / annotations / {annotationID} / content / {multivalueID} / grid_operations
This endpoint applies multiple operations on multiple grids for one multivalue and performs OCR if required, and updates the multivalue with the resulting grid.
For update operation the position of the grid and its rows and columns can be changed, the column layout
can be changed, but the row structure must be unchanged.
The operations are applied sequentially. The grid_index corresponds to the index of the grid parts when
the operation is applied. Combining different types of operations is not supported.
curl -X POST "https://example.rossum.app/api/v1/annotations/0/content/0/grid_operations" \ -H "Content-Type: application/json" \ -d '{ "operations": [ { "op": "update", "grid_index": 0, "grid": { "page": 1, "columns": [ { "left_position": 50.5, "schema_id": "item_description", "header_texts": [ "Description" ] }, { "left_position": 250, "schema_id": "item_quantity", "header_texts": [ "Qty" ] }, { "left_position": 350, "schema_id": "item_amount", "header_texts": [ "Amount" ] } ], "rows": [ { "top_position": 150.5, "tuple_id": 27801932, "type": "data", "tuple_index": 0 }, { "top_position": 180.5, "tuple_id": 27801940, "type": "data", "tuple_index": 1 } ], "width": 500, "height": 200 } } ] }'{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "multivalue",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "tuple",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "datapoint",
"hidden": true,
"content": {
"value": "8/12/24",
"normalized_value": "12-08-2024",
"page": 1,
"position": [
202.3,
100.1,
110.442,
110
],
"rir_text": "8/12/24",
"rir_raw_text": "8/I2/24",
"rir_page": 1,
"rir_position": [
202.3,
100.1,
110.442,
110
],
"rir_confidence": 0.954233451,
"connector_text": "8/I2/24",
"connector_position": [
200,
100,
110,
110
],
"ocr_text": null,
"ocr_raw_text": null,
"ocr_position": null
},
"validation_sources": [
"score"
],
"time_spent": 0.1,
"time_spent_overall": 0.1,
"no_recalculation": false
}
]
}
],
"grid": {
"parts": [
{
"page": 1,
"columns": [
{
"left_position": 12.1,
"schema_id": "item_description",
"header_texts": [
"Item description"
]
}
],
"rows": [
{
"top_position": 112.29,
"tuple_id": 1,
"type": "data"
}
],
"width": 123.2,
"height": 513.2
}
]
},
"time_spent": 0.1,
"time_spent_overall": 0.1,
"time_spent_grid": 0.1,
"time_spent_grid_overall": 0.1
}{
"detail": "Bad Request.",
"code": "bad_request"
}{
"detail": "Invalid token.",
"code": "authentication_failed"
}{
"detail": "Access to the requested resource is forbidden.",
"code": "access_forbidden"
}{
"detail": "Not found.",
"code": "not_found"
}{
"detail": "Conflict.",
"code": "conflict_status"
}{
"detail": "Payload Too Large.",
"code": "payload_too_large"
}{
"detail": "Request was rate limited.",
"code": "rate_limited",
"url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}{
"detail": "Server error.",
"code": "error"
}{
"detail": "Bad Gateway.",
"code": "bad_gateway"
}{
"detail": "Service Unavailable.",
"code": "service_unavailable"
}{
"detail": "Gateway timeout.",
"code": "gateway_timeout"
}Request Body
application/json
Response
OK - Returns updated multivalue content as a tree, with only updated datapoints
A unique ID of a given object.
URL of a given object.
Reference mapping the object to the schema tree.
If set to true, the datapoint is not visible in the user interface, but remains stored in the database.
Time spent while actively working on a given node, in seconds.
Total time spent while validating a given node, in seconds. Only for internal purposes.
Total time spent while actively working on a grid, in seconds. Only for internal purposes.
Total time spent while validating a given grid, in seconds. Only for internal purposes.
Invalid input data.
Detail of the error
Code of the error
The username/password is invalid or token is invalid (e.g. expired).
Detail of the error
Code of the error
Insufficient permission, missing authentication, invalid CSRF token and similar issue.
Detail of the error
Code of the error
The specified resource was not found.
Detail of the error
Code of the error
Conflict
Detail of the error
Code of the error
Payload too large (especially for files uploaded).
Detail of the error
Code of the error
Request rate is too high, wait before sending more requests. See Rate Limiting for more details.
Detail of the error
Code of the error
Link to the rate limiting documentation
Server failure while processing the request.
Detail of the error
Code of the error
Invalid response from the upstream server.
Detail of the error
Code of the error
We're temporarily offline for maintenance. Please try again later.
Detail of the error
Code of the error
Upstream server could not complete the request in time.
Detail of the error
Code of the error
Partial update grid
POST api / v1 / annotations / {annotationID} / content / {multivalueID} / grid_parts_operations
Apply multiple operations on a grid and perform OCR on modified cell datapoints. Update the multivalue with the new grid.
Operations are grouped in rows operations and columns operations.
Possible operations:
| axis | op | required parameters | OCR | Result |
|---|---|---|---|---|
| columns | update | schema_id | Yes | Update column datapoints |
| columns | delete | schema_id | No | Set content to empty for column datapoints |
| rows | create | row_index | Yes | Insert a new row, create datapoints and perform OCR |
| rows | update | row_index, tuple_id | Yes | Update datapoints via OCR |
| rows | delete | tuple_id | No | Delete the tuple associated to this row |
OCR is performed only for rows of extractable type as defined in the multivalue schema by row_types_to_extract,
or by default for rows of type data only.
curl -X POST "https://example.rossum.app/api/v1/annotations/0/content/0/grid_parts_operations" \ -H "Content-Type: application/json" \ -d '{ "grid_index": 0, "grid": { "page": 1, "columns": [ { "left_position": 50.5, "schema_id": "item_description", "header_texts": [ "Description" ] }, { "left_position": 250, "schema_id": "item_quantity", "header_texts": [ "Qty" ] }, { "left_position": 350, "schema_id": "item_amount", "header_texts": [ "Amount" ] } ], "rows": [ { "top_position": 150.5, "tuple_id": 27801932, "type": "data", "tuple_index": 0 }, { "top_position": 180.5, "tuple_id": 27801940, "type": "data", "tuple_index": 1 } ], "width": 500, "height": 200 }, "operations": { "rows": [ { "op": "update", "row_index": 0, "tuple_id": 27801932, "schema_id": "item_description" } ], "columns": [ { "op": "update", "schema_id": "item_amount" } ] } }'{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "multivalue",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "tuple",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "datapoint",
"hidden": true,
"content": {
"value": "8/12/24",
"normalized_value": "12-08-2024",
"page": 1,
"position": [
202.3,
100.1,
110.442,
110
],
"rir_text": "8/12/24",
"rir_raw_text": "8/I2/24",
"rir_page": 1,
"rir_position": [
202.3,
100.1,
110.442,
110
],
"rir_confidence": 0.954233451,
"connector_text": "8/I2/24",
"connector_position": [
200,
100,
110,
110
],
"ocr_text": null,
"ocr_raw_text": null,
"ocr_position": null
},
"validation_sources": [
"score"
],
"time_spent": 0.1,
"time_spent_overall": 0.1,
"no_recalculation": false
}
]
}
],
"grid": {
"parts": [
{
"page": 1,
"columns": [
{
"left_position": 12.1,
"schema_id": "item_description",
"header_texts": [
"Item description"
]
}
],
"rows": [
{
"top_position": 112.29,
"tuple_id": 1,
"type": "data"
}
],
"width": 123.2,
"height": 513.2
}
]
},
"time_spent": 0.1,
"time_spent_overall": 0.1,
"time_spent_grid": 0.1,
"time_spent_grid_overall": 0.1
}{
"detail": "Bad Request.",
"code": "bad_request"
}{
"detail": "Invalid token.",
"code": "authentication_failed"
}{
"detail": "Access to the requested resource is forbidden.",
"code": "access_forbidden"
}{
"detail": "Not found.",
"code": "not_found"
}{
"detail": "Conflict.",
"code": "conflict_status"
}{
"detail": "Payload Too Large.",
"code": "payload_too_large"
}{
"detail": "Request was rate limited.",
"code": "rate_limited",
"url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}{
"detail": "Server error.",
"code": "error"
}{
"detail": "Bad Gateway.",
"code": "bad_gateway"
}{
"detail": "Service Unavailable.",
"code": "service_unavailable"
}{
"detail": "Gateway timeout.",
"code": "gateway_timeout"
}Request Body
application/json
Index of the grid part
Response
OK - Returns updated multivalue content as a tree. By default, only updated datapoints and updated grid
are returned. Add ?full_response=true to get all the datapoints in this grid.
A unique ID of a given object.
URL of a given object.
Reference mapping the object to the schema tree.
If set to true, the datapoint is not visible in the user interface, but remains stored in the database.
Time spent while actively working on a given node, in seconds.
Total time spent while validating a given node, in seconds. Only for internal purposes.
Total time spent while actively working on a grid, in seconds. Only for internal purposes.
Total time spent while validating a given grid, in seconds. Only for internal purposes.
Invalid input data.
Detail of the error
Code of the error
The username/password is invalid or token is invalid (e.g. expired).
Detail of the error
Code of the error
Insufficient permission, missing authentication, invalid CSRF token and similar issue.
Detail of the error
Code of the error
The specified resource was not found.
Detail of the error
Code of the error
Conflict
Detail of the error
Code of the error
Payload too large (especially for files uploaded).
Detail of the error
Code of the error
Request rate is too high, wait before sending more requests. See Rate Limiting for more details.
Detail of the error
Code of the error
Link to the rate limiting documentation
Server failure while processing the request.
Detail of the error
Code of the error
Invalid response from the upstream server.
Detail of the error
Code of the error
We're temporarily offline for maintenance. Please try again later.
Detail of the error
Code of the error
Upstream server could not complete the request in time.
Detail of the error
Code of the error
Replace annotation content by OCR
POST api / v1 / annotations / {annotationID} / content / {nodeID} / select
Replace annotation content by OCR extracted from the rectangle of the document page.
When the rectangle size is unsuitable for OCR (any rectangle side is smaller than 4 px), rectangle is extended to cover the text that overlaps with the rectangle.
curl -X POST "https://example.rossum.app/api/v1/annotations/0/content/0/select" \ -H "Content-Type: application/json" \ -d '{ "rectangle": [ 150, 300, 450, 325 ], "page": "https://example.rossum.app/api/v1/pages/32340" }'{
"content": [
{
"id": 197466,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/197466",
"schema_id": "invoice_info_section",
"category": "section",
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "multivalue",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "tuple",
"hidden": true,
"children": [
{
"id": 27801933,
"url": "https://example.rossum.app/api/v1/annotations/319668/content/27801933",
"schema_id": "some_id",
"category": "datapoint",
"hidden": true,
"content": {
"value": "8/12/24",
"normalized_value": "12-08-2024",
"page": 1,
"position": [
202.3,
100.1,
110.442,
110
],
"rir_text": "8/12/24",
"rir_raw_text": "8/I2/24",
"rir_page": 1,
"rir_position": [
202.3,
100.1,
110.442,
110
],
"rir_confidence": 0.954233451,
"connector_text": "8/I2/24",
"connector_position": [
200,
100,
110,
110
],
"ocr_text": null,
"ocr_raw_text": null,
"ocr_position": null
},
"validation_sources": [
"score"
],
"time_spent": 0.1,
"time_spent_overall": 0.1,
"no_recalculation": false
}
]
}
],
"grid": {
"parts": [
{
"page": 1,
"columns": [
{
"left_position": 12.1,
"schema_id": "item_description",
"header_texts": [
"Item description"
]
}
],
"rows": [
{
"top_position": 112.29,
"tuple_id": 1,
"type": "data"
}
],
"width": 123.2,
"height": 513.2
}
]
},
"time_spent": 0.1,
"time_spent_overall": 0.1,
"time_spent_grid": 0.1,
"time_spent_grid_overall": 0.1
}
]
}
]
}{
"detail": "Bad Request.",
"code": "bad_request"
}{
"detail": "Invalid token.",
"code": "authentication_failed"
}{
"detail": "Access to the requested resource is forbidden.",
"code": "access_forbidden"
}{
"detail": "Not found.",
"code": "not_found"
}{
"detail": "Conflict.",
"code": "conflict_status"
}{
"detail": "Payload Too Large.",
"code": "payload_too_large"
}{
"detail": "Request was rate limited.",
"code": "rate_limited",
"url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}{
"detail": "Server error.",
"code": "error"
}{
"detail": "Bad Gateway.",
"code": "bad_gateway"
}{
"detail": "Service Unavailable.",
"code": "service_unavailable"
}{
"detail": "Gateway timeout.",
"code": "gateway_timeout"
}Request Body
application/json
Bounding box of an occurrence (left, top, right, bottom)
URL of the page of the occurrence
Response
OK
Invalid input data.
Detail of the error
Code of the error
The username/password is invalid or token is invalid (e.g. expired).
Detail of the error
Code of the error
Insufficient permission, missing authentication, invalid CSRF token and similar issue.
Detail of the error
Code of the error
The specified resource was not found.
Detail of the error
Code of the error
Conflict
Detail of the error
Code of the error
Payload too large (especially for files uploaded).
Detail of the error
Code of the error
Request rate is too high, wait before sending more requests. See Rate Limiting for more details.
Detail of the error
Code of the error
Link to the rate limiting documentation
Server failure while processing the request.
Detail of the error
Code of the error
Invalid response from the upstream server.
Detail of the error
Code of the error
We're temporarily offline for maintenance. Please try again later.
Detail of the error
Code of the error
Upstream server could not complete the request in time.
Detail of the error
Code of the error
Validate annotation content
POST api / v1 / annotations / {annotationID} / content / validate
Validate the content of an annotation.
At first, the content is sent to the validate hook of connected extension.
Then some standard validations (data type, constraints are checked) are carried out in Rossum.
Additionally, if the annotation's respective queue has enabled delete recommendation conditions,
they are evaluated as well.
By default, messages for hidden datapoints are omitted. The behavior could be changed using the messages_for_hidden_datapoints=true query parameter.
curl -X POST "https://example.rossum.app/api/v1/annotations/0/content/validate" \ -H "Content-Type: application/json" \ -d '{ "actions": [ "user_update" ], "updated_datapoint_ids": [ 37507206, 37507215 ] }'Example response showing a validation warning from a hook about a potential issue with the total amount.
{
"messages": [
{
"id": "37507215",
"type": "warning",
"content": "Total amount seems unusually high for this vendor",
"detail": {
"hook_id": 12345,
"hook_name": "Amount Validation Hook",
"request_id": "0378f1b1-1e6e-4751-884e-c9df6d0777bc",
"timestamp": "2024-12-17T14:20:00Z",
"is_exception": false,
"source_id": 37507215,
"source_schema_id": "amount_total"
}
}
],
"updated_datapoints": [],
"suggested_operations": [],
"matched_trigger_rules": []
}{
"detail": "Bad Request.",
"code": "bad_request"
}{
"detail": "Invalid token.",
"code": "authentication_failed"
}{
"detail": "Access to the requested resource is forbidden.",
"code": "access_forbidden"
}{
"detail": "Not found.",
"code": "not_found"
}{
"detail": "Conflict.",
"code": "conflict_status"
}{
"detail": "Payload Too Large.",
"code": "payload_too_large"
}{
"detail": "Request was rate limited.",
"code": "rate_limited",
"url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}{
"detail": "Server error.",
"code": "error"
}{
"detail": "Bad Gateway.",
"code": "bad_gateway"
}{
"detail": "Service Unavailable.",
"code": "service_unavailable"
}{
"detail": "Gateway timeout.",
"code": "gateway_timeout"
}Request Body
application/json
Validation actions. Possible values: ["user_update"], ["user_update", "updated"] or ["user_update", "started"]
["user_update"]List of IDs of datapoints that were changed since last call of this endpoint.
Response
Validation results
The subtrees of datapoints updated from an extension
Datapoint operations suggested as a result of validation
Delete Recommendation rules that matched
Invalid input data.
Detail of the error
Code of the error
The username/password is invalid or token is invalid (e.g. expired).
Detail of the error
Code of the error
Insufficient permission, missing authentication, invalid CSRF token and similar issue.
Detail of the error
Code of the error
The specified resource was not found.
Detail of the error
Code of the error
Conflict
Detail of the error
Code of the error
Payload too large (especially for files uploaded).
Detail of the error
Code of the error
Request rate is too high, wait before sending more requests. See Rate Limiting for more details.
Detail of the error
Code of the error
Link to the rate limiting documentation
Server failure while processing the request.
Detail of the error
Code of the error
Invalid response from the upstream server.
Detail of the error
Code of the error
We're temporarily offline for maintenance. Please try again later.
Detail of the error
Code of the error
Upstream server could not complete the request in time.
Detail of the error
Code of the error