ROrossum
Upload

Create upload

Changed on

Uploads a document to the queue specified as query parameter (starting in the importing state).

Multiple files upload is supported, the total size of the data uploaded may not exceed 40 MB. UTF-8 filenames are supported, see examples.

The file can be sent as a part of multipart/form-data or, alternatively, in the request body.

The {filename} parameter in the URL path only works when sending the file in the request body using --data-binary. When uploading via multipart/form-data, the filename is automatically extracted from the form field and the {filename} parameter in the URL is ignored. Use the Content-Disposition header or specify the filename in the form field instead.

You can also specify additional properties using form field:

  • Metadata could be passed using metadata form field. Metadata will be set to newly created annotation object.
  • Document metadata could be passed using document_metadata form field. Metadata will be set to newly created document objects (including documents extracted from uploaded archives) before the upload.created event is triggered.
  • Values could be passed using values form field. It may be used to initialize datapoint values by setting the value of rir_field_names in the schema.

For example upload:organization_unit field may be referenced in a schema like this:

{
  "category": "datapoint",
  "id": "organization_unit", 
  "label": "Org unit",
  "type": "string",
  "rir_field_names": ["upload:organization_unit"]
}

The endpoint is asynchronous and response contains created task url. Further information about the import status may be acquired by retrieving the upload object or the task (for more information, please refer to task).

post/api/v1/uploads

Request

Query parameters

queueinteger required

ID of the target queue for the upload.

reject_identicalboolean

When enabled, upload checks for identical documents within a given organization. If such document is found, upload fails with status 409. The check is performed based on file name and file content. Only one file is allowed when reject_identical is set to true.

Request body multipart/form-data

contentstring binary required

The file(s) to upload. Multiple files are supported.

metadatastring

JSON string containing metadata to be set on the newly created annotation object.

document_metadatastring

JSON string containing metadata to be set on the newly created document objects, including documents extracted from uploaded archives. The metadata is set before the upload.created event is triggered.

valuesstring

JSON string containing values to initialize datapoint values.

Example request

{
  "metadata": "{\"project\":\"Market ABC\"}",
  "document_metadata": "{\"external_id\":\"INV-2026-001\"}",
  "values": "{\"upload:organization_unit\":\"Sales\"}"
}

Response

Accepted

urlstring url

URL of the created task for tracking upload progress.

Example response

{
  "url": "https://example.rossum.app/api/v1/tasks/315509"
}

Changes