1. Documents
  2. Retrieving Documents

Documents

Retrieving Documents

Retrieve a Single Document

`/v1/documents/:id`

Returns the full document object. The retrieve response always includes a linkages object showing the count of active links per resource type.

js 
        const response = await fetch(`/v1/documents/${docId}`, {
  headers: { "X-API-KEY": apiKey },
});
const { data: doc } = await response.json();
// doc.linkages === { shipment: 2, asset: 1, item: 0, manifest: 0, fulfillment: 0 }

Path param: id — document ID, must start with dcmt_.

Getting a Signed Download URL

For private documents, the file.url field on the document object is the raw GCS URL, which returns 403 without GCS credentials. Use ?include_document_url=true to replace it with a 15-minute signed URL.

js 
        const response = await fetch(
  `/v1/documents/${docId}?include_document_url=true`,
  { headers: { "X-API-KEY": apiKey } }
);
const { data: doc } = await response.json();
// doc.file.url is now a signed URL valid for 15 minutes

Query params:

Param Type Notes
include_document_url "true" | "false" Default "false". Generates a signed URL for private documents.

file.url field behavior summary:

Visibility include_document_url file.url value
public either Permanent CDN URL - no additional call needed
private false (default) Raw GCS URL (403 without GCS auth)
private true 15-minute signed URL

Do not store signed URLs server-side — they expire after 15 minutes. Generate them on demand just before returning to the client.

List Documents

`/v1/documents`

List all documents for the authenticated organization with optional filters. Only active (non-deleted) documents are returned. The list response does not include linkages.

js 
        const response = await fetch(
  "/v1/documents?resource_type=shipment&resource_id=ship_abc123&page=1&limit=25",
  { headers: { "X-API-KEY": apiKey } }
);
const { data, pagination } = await response.json();

Query parameters:

Param Type Notes
resource_type string Filter by linked resource type. Comma-separated. One of: asset, shipment, manifest, fulfillment, item
resource_id string Filter by linked resource ID. Comma-separated typed IDs. Best used with resource_type.
type DocumentLinkType Filter by link type (e.g. only proof_of_delivery docs)
category DocumentCategory Filter by document category. Comma-separated.
mime_type string Exact match on MIME type. Comma-separated.
visibility "public" | "private" Filter by visibility. Comma-separated.
upload_status DocumentStatus Filter by upload state: requested, completed, failed, or expired
page integer Pagination page. Default: 1.
limit integer Results per page.

Response:

        {
  "data": [
    {
      "id": "dcmt_01j9abc123",
      "object": "document",
      "file": {
        "name": "Invoice April 2026",
        "url": "https://storage.googleapis.com/...",
        "checksum": null,
        "size": "204800",
        "mime_type": "application/pdf"
      },
      "visibility": "private",
      "upload_status": "completed",
      "category": "invoice",
      "metadata": { "po_number": "PO-12345" },
      "created_by": "usr_01j8abc",
      "created_by_details": { "id": "usr_01j8abc", "name": "Jane Smith" },
      "linkages": { "asset": 0, "shipment": 0, "item": 0, "manifest": 0, "fulfillment": 0 },
      "_upload_url": null,
      "created_at": "2026-05-13T00:00:00.000Z",
      "updated_at": "2026-05-13T00:00:00.000Z",
      "deleted_at": null,
      "checksum": "sha256:abcdef..."
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1 },
  "message": "1 document retrieved"
}

Filtering by resource

To fetch all documents attached to a specific shipment:

js 
        const url = new URL("/v1/documents", apiBase);
url.searchParams.set("resource_type", "shipment");
url.searchParams.set("resource_id", "ship_abc123");

const response = await fetch(url, { headers: { "X-API-KEY": apiKey } });

Filtering by upload status

To find documents awaiting async upload verification:

js 
        const response = await fetch("/v1/documents?upload_status=requested", {
  headers: { "X-API-KEY": apiKey },
});
Previous <- Resource Links
Next Content Overview ->