Batch Operations

Overview

CargoLint supports batch operations for uploading multiple documents and downloading them together, making it efficient to handle shipment-level document sets.

Batch Upload

Upload multiple documents as part of a batch by providing the same uploadBatchId across multiple upload requests:

# Generate a batch ID (any valid GUID)
BATCH_ID="550e8400-e29b-41d4-a716-446655440000"

# Upload documents with the same batch ID
curl -X POST "https://api.cargolint.com/api/v1/documents?uploadBatchId=$BATCH_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@invoice.pdf"

curl -X POST "https://api.cargolint.com/api/v1/documents?uploadBatchId=$BATCH_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@packing_list.pdf"

curl -X POST "https://api.cargolint.com/api/v1/documents?uploadBatchId=$BATCH_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@bill_of_lading.pdf"

File Limits

• Maximum file size: 20 MB per file
• Supported formats: PDF, PNG, JPG, TIFF

Each document in a batch is processed independently through the extraction pipeline.

Batch Document Retrieval

Retrieve all documents that belong to a batch:

curl -X GET "https://api.cargolint.com/api/v1/documents/{document_id}/batch" \
  -H "X-API-Key: YOUR_API_KEY"

This returns all sibling documents uploaded with the same batch ID.

Batch Download (ZIP)

Download all original documents from a batch as a single ZIP archive:

curl -X GET "https://api.cargolint.com/api/v1/documents/batch/{batch_id}/download" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o shipment_documents.zip

Shipment Labels (legacy)

Note: Labels predate first-class shipments. Documents uploaded as a batch are grouped into a shipment automatically - manage them with the Shipments API. Labels remain for backwards compatibility.

Apply a shipment label to organize batch documents:

curl -X PUT "https://api.cargolint.com/api/v1/documents/{document_id}/shipment-label" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shipmentLabel": "SHIPMENT-2026-042"}'

When applied to a document in a batch, the label is applied to all sibling documents in the same batch.

Best Practices

• Use batch IDs to group documents that belong to the same shipment - the batch becomes a shipment with cross-document checks
• Manage the resulting shipment (settle, re-evaluate, add documents) via the Shipments API
• Download batch ZIPs for archival and offline review