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:
- CargoLint colours the fields with problems
- A team member compares them with the original and corrects them
- The document is approved and marked
Completed - 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
- Learn about HS code classification
- Review the API reference documentation
- See Troubleshooting for failed documents and other statuses