Documents

Upload a document for extraction

Use this to have Trackberry read a loading sheet, packing list, invoice or bill of lading and turn it into structured data, whether or not the shipment is tracked with Trackberry. Send the file as multipart/form-data. Give shipment_id to file it on a shipment you already have, or container_number to file it on the live shipment carrying that container; with neither, or with a container no live shipment carries, a new draft shipment is made for it and is not tracked. The answer is the document with parse_status: pending: the file is virus-scanned, then classified and extracted within a few minutes. Poll get_document until data_available is true, then read get_document_data, or subscribe to the document.processed webhook. Data goes to your ERP only after the same review as any other document. Needs the write scope. Send an Idempotency-Key header so a retry after a timeout returns the first document (200) instead of making a second one; uploading the same file to the same shipment again also returns the first document. A new shipment is refused with billing_blocked (403) when the organization's billing does not allow one. Recorded in the audit log as made through the API. Limited to 120 uploads an hour per token.

post/documents

Request

  • Base URL: https://trackberry.com/api/v1
  • URL: https://trackberry.com/api/v1/documents
  • Auth: HTTP bearer

Headers

Trackberry-Versionstring

The API version to build this response for, for example 2026-10-01. Optional: without it the organization's pinned version is used (and the organization is pinned to the latest version on its first request without the header). Applies to this request only. An unpublished version is a 400 with code invalid_version.

Idempotency-Keystring

A value you generate per upload, such as a UUID or your own line id, 1 to 255 printable ASCII characters. Repeating it within 24 hours with the same file and target returns the first document; with a different file or target it is a 400 with code idempotency_key_reused.

Response

A replay: the Idempotency-Key was already used for this request, or this file is already on this shipment. The first document is returned as it is now.

object'document' required

Always document.

idstring required

The document id.

shipment_idstring required

The shipment the document belongs to.

type'unknown' | 'packing_list' | 'transport_document' | 'invoice' | 'phytosanitary_cert' | 'merged_document' | 'certificate_of_origin' | 'warehouse_receipt' | 'inspection_report' | 'courier_document' | 'other_certificate' | 'arrival_notice' | 'booking' | 'pre_alert' required

What kind of document Trackberry decided it is. transport_document covers bills of lading, air waybills and road consignment notes; merged_document is a single file holding several kinds; unknown means it could not be classified.

filenamestring nullable required

The file's name. Null when no file is attached.

content_typestring nullable required

The file's MIME type. Null when no file is attached.

byte_sizeinteger nullable required

The file size in bytes. Null when no file is attached.

source'manual_upload' | 'email_upload' | 'api' | 'correction_link' required

How the document reached Trackberry. manual_upload was uploaded in the app; email_upload arrived by email; api came in through an integration; correction_link was sent in answer to a correction request.

parse_status'pending' | 'processing' | 'parsed' | 'failed' required

Whether Trackberry has read the document. pending and processing are in progress; parsed means data was extracted; failed means reading failed.

downloadableboolean required

True when a file is attached and passed the security scan, so GET /documents/{id}/file serves it.

page_rangestring nullable required

For a document split out of a larger multi-document PDF, the pages of the original file it covers, like 3-5 or 7. Null for documents that are whole files.

data_availableboolean required

True when get_document_data will return extracted fields for this document.

created_atstring date-time required

When the document was added to Trackberry.

updated_atstring date-time required

When the document record last changed.

Changes

No recorded changes to this operation across all 1 revision of this API.