Shipment Endpoints

Create, inspect, settle, and re-evaluate shipments - the document bundles behind cross-document consistency checks.

Shipment Endpoints

A shipment groups the documents that travel together through customs (invoice, packing list, bill of lading, certificate of origin) and carries the results of cross-document consistency checks. Shipments are created implicitly when documents are uploaded together, or you can attach documents to an existing shipment.

All endpoints require authentication and are scoped to your organization.

List Shipments

GET /shipments

Query parameters: status (optional filter - the same buckets as the Shipment Inbox tabs), search (matches references), page (default 1), pageSize (default 25, max 100).

curl "https://api.cargolint.com/api/v1/shipments?status=critical&page=1" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE"

Each item includes the reference, document count, settled flag, the latest evaluation’s overall status with finding counts, and timestamps.

Get Shipment Detail

GET /shipments/{id}

Returns the shipment with its attached documents (including superseded ones) and the latest consistency report: one entry per rule result with severity, message, the per-document observations behind the finding, and the contributing document IDs.

Status Summary

GET /shipments/status-summary

Counts per status bucket - what the dashboard’s Shipments panel is built on.

Reference Helpers

GET /shipments/next-reference     - preview the next auto-generated reference
GET /shipments/check-reference    - check whether a reference is taken (?reference=)
GET /shipments/autocomplete       - live reference suggestions for pickers (?q=)
PATCH /shipments/{id}/reference   - rename a shipment's reference

Add Documents to a Shipment

POST /shipments/{id}/documents

Multipart form upload (files); optional uploadBatchId query parameter groups files uploaded together. A shipment evaluates one document per type - uploading another document of an existing type supersedes the previous one for checks (it stays attached and billed). Returns 409 Conflict if the shipment is settled.

curl -X POST "https://api.cargolint.com/api/v1/shipments/{id}/documents" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE" \
  -F "files=@packing-list.pdf"

Re-evaluate

POST /shipments/{id}/reevaluate

Queues a fresh consistency evaluation. Checks also run automatically whenever an attached document finishes processing (once at least two documents are processed).

Settle and Re-open

POST /shipments/{id}/settle
POST /shipments/{id}/unsettle

Settling finalizes the shipment: it stops accepting documents and approves any documents still pending approval (documents that require review keep their review state). Unsettle re-opens it.

Findings from the Document’s Perspective

GET /documents/{id}/shipment-findings

Returns the cross-document findings that involve a specific document, phrased from that document’s point of view - the same data the Document Issues panel shows under “Across shipment”.

What’s next

Shipment Consistency Checks - What the rule results mean
Document Upload Endpoints - Uploading the documents themselves
Webhooks API - Get notified when processing and evaluations complete