Document Upload Endpoints

Document Upload Endpoints

CargoLint provides endpoints for uploading documents individually or as part of a batch. All uploaded documents are processed through our AI extraction engine for data extraction and customs compliance checking.

Single Document Upload

Upload a single document for processing.

Endpoint

POST /documents

Request

Headers:

Content-Type: multipart/form-data
Authorization: Bearer YOUR_JWT_TOKEN

Form Fields:

Field	Type	Required	Description
file	File	Yes	The document file to upload
uploadBatchId	GUID	No	Optional batch ID to group documents together

Example Request

curl -X POST "https://api.cargolint.com/api/v1/documents" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE" \
  -F "file=@invoice.pdf"

Response Schema

{
  "id": "doc_abc123xyz789",
  "fileName": "invoice.pdf",
  "documentType": "invoice",
  "status": "processing",
  "fileSize": 245600,
  "mimeType": "application/pdf",
  "createdAt": "2026-03-02T10:30:00Z",
  "updatedAt": "2026-03-02T10:30:00Z"
}

Batch Upload

Upload multiple documents by providing the same uploadBatchId query parameter across multiple upload requests. Documents with the same batch ID are grouped together.

Example

# Upload first document with batch ID
curl -X POST "https://api.cargolint.com/api/v1/documents?uploadBatchId=550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE" \
  -F "file=@invoice.pdf"

# Upload second document with same batch ID
curl -X POST "https://api.cargolint.com/api/v1/documents?uploadBatchId=550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE" \
  -F "file=@packing_list.pdf"

You can then download the entire batch as a ZIP:

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

Supported File Types

The following file types are accepted:

application/pdf      PDF documents
image/png            PNG images
image/jpeg           JPEG images
image/tiff           TIFF images

File Size Limits

• Maximum file size: 20 MB per file

Document Status

After upload, documents progress through the following statuses:

Status	Description
processing	Document is being processed
processed	AI extraction completed successfully
requires_review	Low confidence; document flagged for human review
reviewed	Document has been manually reviewed
failed	Processing failed

Response Fields

Field	Type	Description
id	String	Unique document identifier
fileName	String	Original file name
documentType	String	Classified document type
status	String	Current processing status
fileSize	Number	File size in bytes
mimeType	String	MIME type of file
createdAt	ISO 8601	Document creation timestamp
updatedAt	ISO 8601	Last update timestamp

Error Handling

Common Upload Errors

400 Bad Request - File not provided or validation failed:

{
  "error": "No file provided"
}

400 Bad Request - File exceeds size limit:

{
  "error": "File size exceeds 20MB limit"
}

400 Bad Request - File type not supported:

{
  "error": "File type not supported. Allowed types: PDF, PNG, JPG, TIFF"
}

Uploading into a Shipment

Documents uploaded together with the same uploadBatchId are grouped as one shipment, which enables cross-document consistency checks. To add documents to an existing shipment, use POST /shipments/{id}/documents instead of the plain upload endpoint.

Best Practices

• Use batch IDs to group related documents - documents uploaded together form a shipment
• Specify documentType when known for faster processing
• Check document status via the extraction endpoints before retrieving results
• Implement retry logic for failed uploads with exponential backoff