OpenAPI SpecificationJSON
API Reference

Document Relation

A document relation object introduces additional relations between annotations and documents. An annotation can be related to one or more documents and it may belong to several such relations of different types at the same time. These are additional to the main relation between the annotation and the document from which it was created, see annotation

Document relation

Attribute
Type
Description
id*
read-only
integer

ID of the document relation

type*
"export" | "einvoice"

Type of relationship. Possible values:

  • export - Related documents are exports of the annotation data (e.g. in XML or JSON formats).
  • einvoice - Related documents were created during import of an einvoice (e.g. validation report, visualisation, ...)
Default: "export"
key*
string | null

Key used to distinguish several relationships of the same type. Note: The combination of type, key and annotation attribute values must be unique.

annotation*
URL

Annotation

documents*
list[URL]

List of related documents

url*
read-only
URL

URL of the relation

beta

List document relations

GET api / v1 / document_relations

Retrieve all document relation objects.

GET
/api/v1/document_relations
curl -X GET "https://example.rossum.app/api/v1/document_relations"
{
  "pagination": {
    "next": null,
    "previous": null
  },
  "results": [
    {
      "id": 1,
      "type": "export",
      "key": null,
      "annotation": "https://example.rossum.app/api/v1/annotations/314159",
      "documents": [
        "https://example.rossum.app/api/v1/documents/124",
        "https://example.rossum.app/api/v1/documents/125"
      ],
      "url": "https://example.rossum.app/api/v1/document_relations/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": "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

200OK

OK

Attribute
Type
Description
pagination*
pagination
next
URL

URL for the next page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the next page — do not attempt to construct or modify the cursor value.

previous
URL

URL for the previous page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the previous page — do not attempt to construct or modify the cursor value.

results*
list[document_relation_base]
id
read-only
integer

ID of the document relation

type
"export" | "einvoice"

Type of relationship. Possible values:

  • export - Related documents are exports of the annotation data (e.g. in XML or JSON formats).
  • einvoice - Related documents were created during import of an einvoice (e.g. validation report, visualisation, ...)
Default: "export"
key
string | null

Key used to distinguish several relationships of the same type. Note: The combination of type, key and annotation attribute values must be unique.

annotation
URL

Annotation

documents
list[URL]

List of related documents

url
read-only
URL

URL of the relation

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

beta

Create document relation

POST api / v1 / document_relations

Create a new document relation object.

POST
/api/v1/document_relations
curl -X POST "https://example.rossum.app/api/v1/document_relations" \  -H "Content-Type: application/json" \  -d '{    "type": "export",    "annotation": "https://example.rossum.app/api/v1/annotations/314159"  }'
{
  "id": 1,
  "type": "export",
  "key": null,
  "annotation": "https://example.rossum.app/api/v1/annotations/314159",
  "documents": [
    "https://example.rossum.app/api/v1/documents/124",
    "https://example.rossum.app/api/v1/documents/125"
  ],
  "url": "https://example.rossum.app/api/v1/document_relations/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

Attribute
Type
Description
type*
"export" | "einvoice"

Type of relationship. Possible values:

  • export - Related documents are exports of the annotation data (e.g. in XML or JSON formats).
  • einvoice - Related documents were created during import of an einvoice (e.g. validation report, visualisation, ...)
Default: "export"
key
string | null

Key used to distinguish several relationships of the same type. Note: The combination of type, key and annotation attribute values must be unique.

annotation*
URL

Annotation

documents
list[URL]

List of related documents

Response

201Created

Created

Attribute
Type
Description
id*
read-only
integer

ID of the document relation

type*
"export" | "einvoice"

Type of relationship. Possible values:

  • export - Related documents are exports of the annotation data (e.g. in XML or JSON formats).
  • einvoice - Related documents were created during import of an einvoice (e.g. validation report, visualisation, ...)
Default: "export"
key*
string | null

Key used to distinguish several relationships of the same type. Note: The combination of type, key and annotation attribute values must be unique.

annotation*
URL

Annotation

documents*
list[URL]

List of related documents

url*
read-only
URL

URL of the relation

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

beta

Retrieve document relation

GET api / v1 / document_relations / {documentRelationID}

Get a document relation object.

GET
/api/v1/document_relations/{documentRelationID}
curl -X GET "https://example.rossum.app/api/v1/document_relations/0"
{
  "id": 1,
  "type": "export",
  "key": null,
  "annotation": "https://example.rossum.app/api/v1/annotations/314159",
  "documents": [
    "https://example.rossum.app/api/v1/documents/124",
    "https://example.rossum.app/api/v1/documents/125"
  ],
  "url": "https://example.rossum.app/api/v1/document_relations/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": "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

200OK

OK

Attribute
Type
Description
id*
read-only
integer

ID of the document relation

type*
"export" | "einvoice"

Type of relationship. Possible values:

  • export - Related documents are exports of the annotation data (e.g. in XML or JSON formats).
  • einvoice - Related documents were created during import of an einvoice (e.g. validation report, visualisation, ...)
Default: "export"
key*
string | null

Key used to distinguish several relationships of the same type. Note: The combination of type, key and annotation attribute values must be unique.

annotation*
URL

Annotation

documents*
list[URL]

List of related documents

url*
read-only
URL

URL of the relation

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

beta

Partial update document relation

PATCH api / v1 / document_relations / {documentRelationID}

Update part of a document relation object.

PATCH
/api/v1/document_relations/{documentRelationID}
curl -X PATCH "https://example.rossum.app/api/v1/document_relations/0" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": 1,
  "type": "export",
  "key": null,
  "annotation": "https://example.rossum.app/api/v1/annotations/314159",
  "documents": [
    "https://example.rossum.app/api/v1/documents/124",
    "https://example.rossum.app/api/v1/documents/125"
  ],
  "url": "https://example.rossum.app/api/v1/document_relations/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

Attribute
Type
Description
type
"export" | "einvoice"

Type of relationship. Possible values:

  • export - Related documents are exports of the annotation data (e.g. in XML or JSON formats).
  • einvoice - Related documents were created during import of an einvoice (e.g. validation report, visualisation, ...)
Default: "export"
key
string | null

Key used to distinguish several relationships of the same type. Note: The combination of type, key and annotation attribute values must be unique.

annotation
URL

Annotation

documents
list[URL]

List of related documents

Response

200OK

OK

Attribute
Type
Description
id*
read-only
integer

ID of the document relation

type*
"export" | "einvoice"

Type of relationship. Possible values:

  • export - Related documents are exports of the annotation data (e.g. in XML or JSON formats).
  • einvoice - Related documents were created during import of an einvoice (e.g. validation report, visualisation, ...)
Default: "export"
key*
string | null

Key used to distinguish several relationships of the same type. Note: The combination of type, key and annotation attribute values must be unique.

annotation*
URL

Annotation

documents*
list[URL]

List of related documents

url*
read-only
URL

URL of the relation

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

beta

Delete document relation

DELETE api / v1 / document_relations / {documentRelationID}

Delete a document relation object with empty related documents. If some documents still participate in the relation, the caller must first delete those documents or update the document relation before deleting it.

DELETE
/api/v1/document_relations/{documentRelationID}
curl -X DELETE "https://example.rossum.app/api/v1/document_relations/0"
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": "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

204No Content

No Content

No response body.

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

beta

Update document relation

PUT api / v1 / document_relations / {documentRelationID}

Update document relation object.

PUT
/api/v1/document_relations/{documentRelationID}
curl -X PUT "https://example.rossum.app/api/v1/document_relations/0" \  -H "Content-Type: application/json" \  -d '{    "type": "export",    "annotation": "https://example.rossum.app/api/v1/annotations/314159"  }'
{
  "id": 1,
  "type": "export",
  "key": null,
  "annotation": "https://example.rossum.app/api/v1/annotations/314159",
  "documents": [
    "https://example.rossum.app/api/v1/documents/124",
    "https://example.rossum.app/api/v1/documents/125"
  ],
  "url": "https://example.rossum.app/api/v1/document_relations/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

Attribute
Type
Description
type*
"export" | "einvoice"

Type of relationship. Possible values:

  • export - Related documents are exports of the annotation data (e.g. in XML or JSON formats).
  • einvoice - Related documents were created during import of an einvoice (e.g. validation report, visualisation, ...)
Default: "export"
key
string | null

Key used to distinguish several relationships of the same type. Note: The combination of type, key and annotation attribute values must be unique.

annotation*
URL

Annotation

documents
list[URL]

List of related documents

Response

200OK

OK

Attribute
Type
Description
id*
read-only
integer

ID of the document relation

type*
"export" | "einvoice"

Type of relationship. Possible values:

  • export - Related documents are exports of the annotation data (e.g. in XML or JSON formats).
  • einvoice - Related documents were created during import of an einvoice (e.g. validation report, visualisation, ...)
Default: "export"
key*
string | null

Key used to distinguish several relationships of the same type. Note: The combination of type, key and annotation attribute values must be unique.

annotation*
URL

Annotation

documents*
list[URL]

List of related documents

url*
read-only
URL

URL of the relation

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

GETRetrieve original documentdepr

Previous Page

GETList document relationsbeta

Next Page