Document Statuses
What each document status means and how documents move through the processing pipeline.
Every document in CargoLint has a status that tells you exactly where it is in the processing pipeline. Statuses update automatically as the document moves from upload through extraction, review, and completion.
Status reference
● Uploaded
The document has been received and is queued for processing. This is the initial state immediately after upload. No extraction has started yet - the document is waiting to be sent to the AI service.
You don’t need to do anything. Processing begins automatically within a few seconds.
● Processing
The AI extraction service is actively working on the document - classifying the document type and extracting every field with a confidence score. This typically takes less than 5 seconds.
You’ll see this status after every upload. It also covers short upstream holds - every fresh upload passes a brief safety scan before extraction begins - so a document can display as Processing for a few minutes. If a document is still parked after 5 minutes, its status changes to Waiting for AI - check the troubleshooting guide if that happens often.
● Pending Approval
Extraction is complete, the overall confidence score is 78% or higher, and nothing needs explicit confirmation (no HS codes waiting to be confirmed, no scan-quality concerns). The document is ready for you to review and approve, but it doesn’t require urgent attention - the AI is reasonably confident in its extractions.
These documents appear in your review queue. You can approve them as-is, make corrections to specific fields, or skip them to review later.
● Review
The document needs your attention before it can be finalized. A document lands here when its overall confidence score is below 78%, or - regardless of how high it scores - when something needs explicit human confirmation:
- HS codes to confirm - suggested codes are never applied automatically; a line item without a confirmed code holds the document here
- Degraded scan - the scan quality was too low for reliable reading
- Shipment finding - a shipment consistency check found conflicting information between this document and another in the same shipment
Because of those holds, a document with a high (green) confidence score can sit in Review while a lower-scoring document sits in Pending Approval. The score measures how cleanly the document was read; the status reflects what still needs a human. The compliance panel shows exactly which fields were flagged and why the document is held.
Tip: Documents in this status are highlighted in your review queue so they’re easy to spot and prioritize.
● Waiting for AI
The document has been parked for more than 5 minutes waiting on an upstream service - usually a transient AI service outage, a rate limit, or a delayed scan verdict. The document is safe and a background retry worker will requeue it automatically as soon as the service recovers. No action is required from you.
Brief holds are a normal part of processing and display as Processing; a document only shows Waiting for AI once it has been parked past the 5 minute mark.
If many documents are sitting in this state, you’ll also see a system-wide banner at the top of the app and on the status page. When the AI service recovers, documents transition back to Processing and continue through the normal pipeline.
● Completed
A reviewer has approved this document. All fields have been validated (either by the AI with high confidence or by a human reviewer), compliance rules have passed, and the data is ready for export.
Completed documents can be exported as a corrected PDF or a downloadable audit packet (a ZIP containing the extracted fields as JSON, your corrections, and the compliance report), used to generate related documents (like a packing list from an invoice), or sent to your customs system via the API or webhooks.
● Skipped
A reviewer chose to defer this document for later. It’s been set aside but not finalized - you can come back to it at any time from the review queue.
Skipping is useful when you need more information before you can review (waiting for a corrected scan, confirming an HS code with a colleague, etc.) or when you’re triaging a batch and want to focus on higher-priority documents first.
● Failed
The extraction service was unable to process this document. This could happen if the file is corrupted, the format is unsupported, the image quality is too poor for any text recognition, or an unexpected error occurred during processing.
To resolve a failed document: check that the file is a valid PDF, PNG, JPG, or TIFF under 20 MB, ensure the scan is legible, and try re-uploading. If the problem persists, check the troubleshooting guide or contact support.
How documents flow through statuses
The typical lifecycle follows a linear path:
Uploaded → Processing → Pending Approval or Review → Completed
The branch after Processing depends on the AI’s confidence and on what needs explicit confirmation. Documents scoring 78% or higher with nothing to confirm go to Pending Approval; documents scoring below 78%, or with HS codes to confirm, or with a degraded scan go to Review. Both paths lead to Completed once a reviewer approves - a high score never skips the human sign-off.
Two alternative paths exist: a reviewer can Skip a document to defer it, and a document can be reprocessed (which sends a Completed document back to Processing for a fresh extraction).
Status transitions at a glance
| From | To | Trigger |
|---|---|---|
| Uploaded | Processing | Automatic - begins within seconds of upload |
| Processing | Pending Approval | Extraction completes with confidence ≥ 78% and nothing to confirm |
| Processing | Review | Extraction completes with confidence < 78%, HS codes need confirmation, or the scan is degraded |
| Pending Approval | Review | A shipment consistency check finds conflicting information |
| Completed | Review | A shipment consistency check finds an error-level conflict in an approved document |
| Processing | Waiting for AI | An upstream outage or scan delay keeps the document parked for more than 5 minutes - retry worker takes over |
| Waiting for AI | Processing | AI service recovers and the document is requeued |
| Processing | Failed | Extraction encounters an unrecoverable error |
| Pending Approval | Completed | Reviewer approves (with or without corrections) |
| Review | Completed | Reviewer approves (with or without corrections) |
| Pending Approval | Skipped | Reviewer defers the document |
| Review | Skipped | Reviewer defers the document |
| Completed | Processing | Document is reprocessed (re-extraction triggered) |
Filtering by status
On the Documents page, you can filter the list by status to focus on what needs attention. The filter bar shows counts for each status so you can see at a glance how many documents are waiting for review, how many have been completed, and whether any have failed.
The review queue automatically surfaces Pending Approval and Review documents, with Review items highlighted for priority handling.
Webhooks and status changes
If you’ve configured webhooks, CargoLint fires events on key status transitions - including document.pending_approval and document.requires_review after extraction, document.failed when extraction cannot complete, document.reviewed and document.completed once a reviewer finishes, and document.skipped when a document is deferred. See the webhook setup guide for the full event list and payloads.
What’s next
- Reviewing documents - the full review workflow for Pending Approval and Review documents
- How confidence scoring works - the 78% threshold and the holds that determine review routing
- Uploading documents - best practices for uploads that lead to higher confidence scores