Documents

Retrieving Documents

# Retrieve a Single Document

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

        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.

        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:

file.url field behavior summary:

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

# List 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.

        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:

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:

        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:

        const response = await fetch("/v1/documents?upload_status=requested", {
  headers: { "X-API-KEY": apiKey },
});

      

# Search

When filters are not enough and you want to find a document by a free-text query, use the search query param. This runs a fulltext search across the document name and metadata.

To search, simply provide a string to search by using the search query param.

Search Strategy

By default, search uses the match_some strategy, which returns documents matching any of the provided terms (OR). To require every term to match, set search_strategy=match_all (AND).

        const response = await fetch("/v1/documents?search=invoice", {
  headers: { "X-API-KEY": apiKey },
});
const { data, pagination } = await response.json();

      

To require all terms to match:

        const response = await fetch(
  "/v1/documents?search=april%20invoice&search_strategy=match_all",
  { headers: { "X-API-KEY": apiKey } }
);

      

Ordering Search Results

By default, search results are ordered by relevance. However, if you include an order_by parameter along with your search query, the results will be ordered by the specified property instead of by relevance.