---
title: "Get one document"
method: GET
path: "/documents/{id}"
tags: ["Documents"]
---

# Get one document

`GET /documents/{id}`

## Request

- Base URL: `https://trackberry.com/api/v1`
- URL: `https://trackberry.com/api/v1/documents/{id}`
- Auth: HTTP bearer

Use this to describe a document you found through `list_shipment_documents`: its type, file name, size, source, processing status, and whether extracted data is available. `download_document_file` returns the file itself. Only current documents are found; a replaced or reference-only document is a 404.

## Path parameters

- `id` string, required

## Headers

- `Trackberry-Version` string

## Response `200`

The document.

- Document: A file attached to a shipment, such as a bill of lading, packing list, invoice or certificate, with its processing state. The file itself is not part of this object; `GET /documents/{id}/file` serves it when `downloadable` is true.
  - `object` 'document', required: Always `document`.
  - `id` string, required: The document id.
  - `shipment_id` string, 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.
  - `filename` string, nullable, required: The file's name. Null when no file is attached.
  - `content_type` string, nullable, required: The file's MIME type. Null when no file is attached.
  - `byte_size` integer, 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.
  - `downloadable` boolean, required: True when a file is attached and passed the security scan, so `GET /documents/{id}/file` serves it.
  - `page_range` string, 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_available` boolean, required: True when `get_document_data` will return extracted fields for this document.
  - `created_at` string, date-time, required: When the document was added to Trackberry.
  - `updated_at` string, date-time, required: When the document record last changed.

## Other responses

- `400`: A parameter or header is invalid (`invalid_parameter`, with `param` naming it), a customer link cannot be made for this shipment (`not_shareable`), an uploaded file is empty, over 50 MB or of a type Trackberry does not read (`file_empty`, `file_too_large`, `unsupported_file_type`), an upload's container number is on more than one live shipment (`ambiguous_container`), an `Idempotency-Key` was already used for a different request (`idempotency_key_reused`) or `Trackberry-Version` names an unpublished version (`invalid_version`, with `param` set to `Trackberry-Version`). A parameter that must be a single value but was sent as an array or hash (`status[]=x`, `q[a]=1`) is also a 400.
- `401`: No token was sent (`missing_token`) or the token is wrong, expired, revoked, or its user left the organization (`invalid_token`). The response has a `WWW-Authenticate` header.
- `403`: The token may not do this. `insufficient_scope`: a write endpoint was called with a read-only token. `read_only_member`: a write endpoint was called by a token whose owner is now a read-only member of the organization. `revoke_not_allowed`: the link can only be revoked by an admin or by the member who made it. `billing_blocked`: an upload needed a new shipment and the organization's billing does not allow one.
- `404`: No such object in this organization (`resource_missing`). This is also the answer for an id of another organization, an id with the wrong prefix, or a malformed id, so the API never confirms that an object exists elsewhere.
- `429`: A rate limit was hit (`rate_limited`). Wait the number of seconds in `Retry-After`. A BI feed answers the same way (`feed_in_progress`) when another feed for the organization is still being produced.

---

[API](https://skmtc.dev/trackberry/apis/trackberry-api.md) · [All operations](https://skmtc.dev/trackberry/apis/trackberry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackberry/apis/trackberry-api/revisions/be06ee7c17f3?raw)