2026 customs changesWhat it means

Your First Upload

Walk through uploading a customs document through the API and reading the extraction results.

Uploading Your First Document

This guide walks you through uploading a trade document to CargoLint through the API and reading what comes back. CargoLint identifies the kind of document on its own, whether it is an invoice, a packing list, a bill of lading, an air waybill or a certificate.

Supported File Types

CargoLint accepts the following document formats:

  • PDF (.pdf) - Most common for customs documents
  • PNG (.png) - Digital images and scanned documents
  • JPG (.jpg, .jpeg) - Photographs of documents
  • TIFF (.tiff, .tif) - High-resolution scanned documents

File size limit: 20 MB per document. A password-protected PDF is rejected. Documents must be in English; road and rail consignment notes, phytosanitary certificates and health certificates printed in several languages are read when the content filled in is English.

Upload a Document via API

Use the POST /documents endpoint to submit one file per request:

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

Request Parameters:

Parameter In Required Description
file Form Yes The document file to upload
uploadBatchId Query No A GUID shared by documents uploaded together; they are grouped as one shipment
shipmentLabel Query No A reference for the shipment, up to 64 characters

You don’t specify the document’s kind - CargoLint detects it.

Response:

{
  "id": "3f6c1e2a-8b4d-4c7e-9a1f-2d5e8b7c4a10",
  "fileName": "invoice.pdf",
  "status": "Processing",
  "documentType": "application/pdf",
  "createdAt": "2026-10-22T10:15:30Z",
  "shipmentId": "a1b2c3d4-0000-4000-8000-000000000001",
  "reference": "SHP-2026-0042"
}

documentType is the file’s media type. The document’s kind arrives later, as detectedDocumentType.

Polling for Results

Processing runs in the background. Poll the document until its status settles:

curl https://api.cargolint.com/api/v1/documents/3f6c1e2a-8b4d-4c7e-9a1f-2d5e8b7c4a10 \
  -H "X-API-Key: cl_YOUR_API_KEY"

The response carries status and, once the document is classified, detectedDocumentType: the kind’s id from CargoLint’s document kinds, such as Invoice, BillOfLading or AirWaybill.

Status Values

Status Meaning What to do
Uploaded Stored, not yet queued Wait
Processing Being read Keep polling
WaitingForAiService The AI service was unavailable; CargoLint retries on its own Keep polling, less often
PendingApproval Read with no reading problem for a reviewer and nothing to confirm Fetch the results; a person approves it in the app or through the review API
RequiresReview Reading problems, or something needs a person’s confirmation Fetch the results; correct and approve in the review queue
Completed A person approved it Fetch the final results
Skipped A reviewer set it aside Fetch the results, or wait for review
Recognized A kind CargoLint recognizes but does not read yet; no fields Nothing to fetch; it counts as present in its shipment
Split The file held several documents, each now its own document Read splitDocuments and follow each one
Failed The document could not be read Check the file and the language, then upload it again

Processing stops at 5 minutes: a document that has not finished by then is marked Failed.

Reading the Extracted Fields

Once the document is past processing, fetch its fields:

curl "https://api.cargolint.com/api/v1/documents/3f6c1e2a-8b4d-4c7e-9a1f-2d5e8b7c4a10/extractions" \
  -H "X-API-Key: cl_YOUR_API_KEY"

An abridged response:

{
  "documentId": "3f6c1e2a-8b4d-4c7e-9a1f-2d5e8b7c4a10",
  "detectedDocumentType": "Invoice",
  "qualityScore": 90,
  "qualityLevel": "warning",
  "requiresReview": false,
  "fields": [
    { "fieldName": "InvoiceId", "value": "INV-2026-001", "confidence": 0.95 },
    { "fieldName": "InvoiceDate", "value": "2026-10-01", "confidence": 0.95 },
    { "fieldName": "VendorName", "value": "ABC Manufacturing Ltd.", "confidence": 0.75 },
    { "fieldName": "InvoiceTotal", "value": "5000.00", "confidence": 0.95 }
  ]
}

The full response also carries lineItems, confidenceReasons (the problems found in the reading) and the raw text. GET /documents/{id}/issues lists every problem behind the score.

The Quality Score Explained

The document’s Quality score starts at 100% and each problem found takes off its cost: 10% for a warning, 20% for a problem that needs fixing, down to 0%. qualityLevel is the worst problem: none (shown green), warning (amber) or serious (red, shown as Needs fixing). Each field’s confidence is the AI’s rating of how clearly it read the value: 0.95 clearly readable, 0.75 may be garbled (a warning on the field), 0.50 a guess (a problem that needs fixing). See How the Quality Score Works.

What Sends a Document to Review?

When the reading found problems (one that needs fixing, or two warnings), HS codes await confirmation, the scan is degraded, or a check found something that needs a person, the document goes to Review in the Review Queue:

  1. CargoLint colours the fields with problems
  2. A team member compares them with the original and corrects them
  3. The document is approved and marked Completed
  4. Unless a user opts out, corrections help improve future accuracy

Common Issues and Solutions

Q: My upload is rejected

  • Check that the file is a PDF, PNG, JPG or TIFF under 20 MB, and that its extension matches its content
  • Remove any password from the PDF

Q: Many fields show as unclear reads

  • Document image quality may be poor; try re-scanning at 300 DPI
  • Ensure text is clearly visible and not rotated
  • Check for unusual fonts or handwritten content

Q: HS code is missing

  • Not all documents carry HS codes. CargoLint reads them from the lines of invoices, bills of lading and certificates of origin
  • You can add or correct HS codes in the review editor with Find HS Code

Next Steps