Your First Upload

Uploading Your First Document

This guide walks you through uploading a trade document to CargoLint and understanding the extraction results. Whether you’re processing invoices, packing lists, bills of lading, or certificates of origin, the process is straightforward.

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: 5 MB per document.

Upload a Document via API

Use the POST /documents endpoint to submit a document for processing:

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

Request Parameters:

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

CargoLint automatically detects the document type (invoice, packing list, bill of lading, or certificate of origin) - you don’t need to specify it.

Understanding the Response

CargoLint processes your document and returns structured data with confidence scores:

{
  "documentId": "doc_abc123xyz",
  "documentType": "invoice",
  "status": "processed",
  "processedAt": "2026-03-02T10:15:30Z",
  "fields": {
    "invoiceNumber": {
      "value": "INV-2026-001",
      "confidence": 0.98
    },
    "invoiceDate": {
      "value": "2026-03-01",
      "confidence": 0.96
    },
    "supplier": {
      "value": "ABC Manufacturing Ltd.",
      "confidence": 0.94
    },
    "totalAmount": {
      "value": "5000.00",
      "confidence": 0.99
    }
  }
}

Confidence Scores Explained

Each extracted field includes a confidence score between 0 and 1, indicating how certain CargoLint is about the extraction:

• 0.95 - 1.0: Excellent confidence. Value is likely accurate.
• 0.85 - 0.94: Good confidence. Value is probably accurate.
• 0.70 - 0.84: Moderate confidence. Review recommended.
• Below 0.70: Low confidence. Document flagged for manual review.

What Happens with Low Confidence?

When the overall document confidence falls below 0.70, the document enters the Review Queue for manual verification:

1. CargoLint flags uncertain fields
2. The document appears in your Review Queue
3. A team member reviews and corrects the data
4. Corrections are saved and help improve future accuracy

This ensures data accuracy even for challenging documents with poor image quality or unusual formats.

Response Status Values

Status	Meaning	Action Required
processing	Document is being analyzed	Wait and poll the endpoint
processed	Extraction finished successfully	Review results
requires_review	Low confidence fields detected	Manual review in dashboard
failed	Processing error occurred	Check file format and try again

Polling for Results

For async processing, poll the /documents/{documentId} endpoint:

curl -X GET https://api.cargolint.com/api/v1/documents/doc_abc123xyz \
  -H "X-API-Key: cl_test_YOUR_API_KEY_HERE"

Most documents process within 10-30 seconds. For scanned or low-quality images, allow up to 2 minutes.

Common Issues and Solutions

Q: My PDF upload fails

• Ensure the file is valid and not corrupted
• Check that file size is under 5 MB
• Try converting to PNG or JPG if PDF is image-based

Q: Confidence scores are very low

• 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 contain HS codes
• Only invoices and packing lists typically include product classifications
• You can manually add HS codes in the dashboard

Next Steps

• Learn about HS code classification
• Review the API reference documentation