Document
A document object contains information about one input file. To create it, one can:
- Use upload endpoint
- import document by email
- create document via API
Document
ID of the document
URL of the document
Storage key of the document file. Internal use only.
URL of the parent document (e.g. the zip file it was extracted from)
URL of the email object that document was imported by (only for document imported by email).
List of annotations related to the document. Usually there is only one annotation.
MIME type of the document (e.g. application/pdf)
User that created the annotation.
Timestamp of document upload or incoming email attachment extraction.
See created_at
File name of the attachment or upload.
Link to the document's raw content (e.g. PDF file). May be null if there is no file associated.
Reason why the Document got filtered out on Email ingestion.
Client data. May be used to store e.g. external system object IDs. See Metadata for more details.
Default:{}List documents
GET api / v1 / documents
Returns paginated response with a list of document objects.
curl -X GET "https://example.rossum.app/api/v1/documents"{
"results": [
{
"id": 314628,
"url": "https://example.rossum.app/api/v1/documents/314628",
"s3_name": "272c2f01ae84a4e19a421cb432e490bb",
"parent": "https://example.rossum.app/api/v1/documents/203517",
"email": "https://example.rossum.app/api/v1/emails/1234",
"annotations": [
"https://example.rossum.app/api/v1/annotations/314528"
],
"mime_type": "application/pdf",
"creator": "https://example.rossum.app/api/v1/users/1",
"created_at": "2020-05-21T12:34:56.789Z",
"arrived_at": "2020-05-21T12:34:56.789Z",
"original_file_name": "invoice.pdf",
"content": "https://example.rossum.app/api/v1/documents/314628/content",
"attachment_status": "processed",
"metadata": {
"some_key": "some_value"
}
}
],
"pagination": {
"next": null,
"previous": null
}
}{
"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
Create document
POST api / v1 / documents
Create a new document object.
Use this API call to create a document without an annotation. Suitable for creating documents for mime types that cannot be extracted by Rossum. Only one document can be created per request.
The supported mime types are the same as for document import.
curl -X POST "https://example.rossum.app/api/v1/documents" \ -F content="string"{
"id": 314628,
"url": "https://example.rossum.app/api/v1/documents/314628",
"s3_name": "272c2f01ae84a4e19a421cb432e490bb",
"parent": "https://example.rossum.app/api/v1/documents/203517",
"email": "https://example.rossum.app/api/v1/emails/1234",
"annotations": [
"https://example.rossum.app/api/v1/annotations/314528"
],
"mime_type": "application/pdf",
"creator": "https://example.rossum.app/api/v1/users/1",
"created_at": "2020-05-21T12:34:56.789Z",
"arrived_at": "2020-05-21T12:34:56.789Z",
"original_file_name": "invoice.pdf",
"content": "https://example.rossum.app/api/v1/documents/314628/content",
"attachment_status": "processed",
"metadata": {
"some_key": "some_value"
}
}{
"detail": "Missing filename. Request should include a Content-Disposition header with a filename parameter.",
"code": "parse_error"
}{
"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"
}The file to be uploaded.
Client data. May be used to store e.g. external system object IDs. See Metadata for more details.
Default:{}URL of the parent document (e.g. the original file based on which the uploaded content was created)
Response
Created
ID of the document
URL of the document
Storage key of the document file. Internal use only.
URL of the parent document (e.g. the zip file it was extracted from)
URL of the email object that document was imported by (only for document imported by email).
List of annotations related to the document. Usually there is only one annotation.
MIME type of the document (e.g. application/pdf)
User that created the annotation.
Timestamp of document upload or incoming email attachment extraction.
See created_at
File name of the attachment or upload.
Link to the document's raw content (e.g. PDF file). May be null if there is no file associated.
Reason why the Document got filtered out on Email ingestion.
Client data. May be used to store e.g. external system object IDs. See Metadata for more details.
Default:{}Bad Request
responseobjectThis error object can have any number of properties, and their names and types are not predefined.
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
Retrieve document
GET api / v1 / documents / {documentID}
Get a document object.
curl -X GET "https://example.rossum.app/api/v1/documents/0"{
"id": 314628,
"url": "https://example.rossum.app/api/v1/documents/314628",
"s3_name": "272c2f01ae84a4e19a421cb432e490bb",
"parent": "https://example.rossum.app/api/v1/documents/203517",
"email": "https://example.rossum.app/api/v1/emails/1234",
"annotations": [
"https://example.rossum.app/api/v1/annotations/314528"
],
"mime_type": "application/pdf",
"creator": "https://example.rossum.app/api/v1/users/1",
"created_at": "2020-05-21T12:34:56.789Z",
"arrived_at": "2020-05-21T12:34:56.789Z",
"original_file_name": "invoice.pdf",
"content": "https://example.rossum.app/api/v1/documents/314628/content",
"attachment_status": "processed",
"metadata": {
"some_key": "some_value"
}
}{
"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
ID of the document
URL of the document
Storage key of the document file. Internal use only.
URL of the parent document (e.g. the zip file it was extracted from)
URL of the email object that document was imported by (only for document imported by email).
List of annotations related to the document. Usually there is only one annotation.
MIME type of the document (e.g. application/pdf)
User that created the annotation.
Timestamp of document upload or incoming email attachment extraction.
See created_at
File name of the attachment or upload.
Link to the document's raw content (e.g. PDF file). May be null if there is no file associated.
Reason why the Document got filtered out on Email ingestion.
Client data. May be used to store e.g. external system object IDs. See Metadata for more details.
Default:{}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
Partial update document
PATCH api / v1 / documents / {documentID}
Update part of a document object.
curl -X PATCH "https://example.rossum.app/api/v1/documents/0" \ -H "Content-Type: application/json" \ -d '{}'{
"id": 314628,
"url": "https://example.rossum.app/api/v1/documents/314628",
"s3_name": "272c2f01ae84a4e19a421cb432e490bb",
"parent": "https://example.rossum.app/api/v1/documents/203517",
"email": "https://example.rossum.app/api/v1/emails/1234",
"annotations": [
"https://example.rossum.app/api/v1/annotations/314528"
],
"mime_type": "application/pdf",
"creator": "https://example.rossum.app/api/v1/users/1",
"created_at": "2020-05-21T12:34:56.789Z",
"arrived_at": "2020-05-21T12:34:56.789Z",
"original_file_name": "invoice.pdf",
"content": "https://example.rossum.app/api/v1/documents/314628/content",
"attachment_status": "processed",
"metadata": {
"some_key": "some_value"
}
}{
"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
URL of the email object that document was imported by (only for document imported by email).
Client data. May be used to store e.g. external system object IDs. See Metadata for more details.
Default:{}Response
OK
ID of the document
URL of the document
Storage key of the document file. Internal use only.
URL of the parent document (e.g. the zip file it was extracted from)
URL of the email object that document was imported by (only for document imported by email).
List of annotations related to the document. Usually there is only one annotation.
MIME type of the document (e.g. application/pdf)
User that created the annotation.
Timestamp of document upload or incoming email attachment extraction.
See created_at
File name of the attachment or upload.
Link to the document's raw content (e.g. PDF file). May be null if there is no file associated.
Reason why the Document got filtered out on Email ingestion.
Client data. May be used to store e.g. external system object IDs. See Metadata for more details.
Default:{}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
Delete document
DELETE api / v1 / documents / {documentID}
Delete document object.
curl -X DELETE "https://example.rossum.app/api/v1/documents/0"{
"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": "Document is still referenced."
}{
"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
Document successfully deleted.
No response body.
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
Document cannot be deleted due to existing annotation reference.
Detail 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
Retrieve document content
GET api / v1 / documents / {documentID} / content
Get original document content (e.g. PDF file).
To download multiple documents in one archive, refer to documents download object.
curl -X GET "https://example.rossum.app/api/v1/documents/0/content""string"{
"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
responsestring (binary)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
Retrieve original document
GET api / v1 / original / {DocumentS3Name}
Get original document content (e.g. PDF file).
Note that this endpoint was intended to access document content, but is now deprecated. Use content endpoint instead.
curl -X GET "https://example.rossum.app/api/v1/original/272c2f01ae84a4e19a421cb432e490bb""string"{
"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
responsestring (binary)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