Quality Score
The data behind a document's Quality score: the issues it counts, their levels and costs, and the per-field ratings the AI gives.
What the Quality score is
A document’s Quality score starts at 100% and each problem found on it takes off its cost, down to 0%: 10% for a warning, 20% for a problem that needs fixing, nothing for a note. HS code problems count once per document, at their worst level. The score counts problems CargoLint found; it is not a probability that the values are right.
Every problem type has one level, the same wherever it appears. The list of problem types, with each one’s level, owner and kind, is served by GET /api/v1/config as problemTypes.
A document of a kind CargoLint recognizes but does not read has no fields, and so no score (qualityScore is null).
The issues behind the score
GET /api/v1/documents/{id}/issues returns the Quality score with every issue it counts:
{
"qualityScore": 70,
"qualityLevel": "serious",
"counts": { "serious": 1, "warning": 1, "note": 1 },
"reviewed": false,
"issues": [
{
"code": "missing_required_field",
"owner": "checks",
"kind": "document",
"level": "serious",
"countsInScore": true,
"costPercent": 20,
"message": "Required field 'Invoice Total' is missing or empty",
"fields": ["InvoiceTotal"]
},
{
"code": "UNCLEAR_READ",
"owner": "reading",
"kind": "unclearRead",
"level": "warning",
"countsInScore": true,
"costPercent": 10,
"message": "Line 2 ('Silicone spatula set') may have been misread",
"fields": ["Items[1]"],
"lineIndex": 1
},
{
"code": "HS_SIX_DIGITS_ONLY",
"owner": "hs",
"kind": "hs",
"level": "note",
"countsInScore": false,
"costPercent": 0,
"message": "HS code 7323.93.0045 for \"Stainless steel mixing bowls\" was checked at 6 digits",
"fields": ["Items[0].HsCode"],
"lineIndex": 0,
"hs": { "lineIndex": 0, "description": "Stainless steel mixing bowls", "currentCode": "7323.93.0045", "score": 0.95 }
}
]
}
| Field | Meaning |
|---|---|
qualityScore |
0 to 100; null when there is nothing to judge yet |
qualityLevel |
none, warning or serious (shown as Needs fixing): the worst counted problem, and the colour shown |
counts |
Counted problems per level, and the notes shown |
reviewed |
A person signed the document off; reading problems no longer apply and are left out |
checksPending |
The document checks have not run yet, so the issues hold only what the reading and the HS verdicts found; ask again once they have |
holdReason |
Why a document in Review is there: problems, reading, hs, ocr, blocking or shipment; null when it is not in Review |
route, coverage |
The destination it was checked against and what the checks covered, as /compliance returns them; null on a shared link |
issues[].owner |
Who raised it: reading (how the document was read), checks (what it says or lacks), hs (the HS verdicts) or app (CargoLint itself) |
issues[].kind |
When it is known and what it does beyond counting: reading and unclearRead problems are known when the document is read, document problems once its checks have run, blocking problems also hold the document on their own at level serious, hs problems count once and unconfirmed codes hold the document |
issues[].countsInScore, costPercent |
Whether and how much it takes off the score |
issues[].fields |
The stored field names (boxes) it is about; Items[n] names a whole line |
issues[].detail, issues[].hs |
A check’s expected and actual values, citations and tax hints; an HS verdict’s code, score and tariff-line detail |
The same shape is served for a shared link at GET /api/v1/public/shared-documents/issues, with the link’s token in the X-Link-Token header.
Per-field ratings
GET /api/v1/documents/{id}/extractions returns every field with the AI’s rating of how clearly it read it:
{
"detectedDocumentType": "Invoice",
"qualityScore": 90,
"qualityLevel": "warning",
"requiresReview": false,
"fields": [
{ "fieldName": "InvoiceId", "value": "INV-2026-001", "confidence": 0.95 },
{ "fieldName": "InvoiceDate", "value": "2026-03-02", "confidence": 0.95 },
{ "fieldName": "CustomerName", "value": "Northwind Imports Ltd", "confidence": 0.75 }
],
"confidenceReasons": [
{
"code": "UNCLEAR_READ",
"severity": "warning",
"message": "The consignee's name may have been misread",
"affectedFields": ["CustomerName"]
}
]
}
A field’s confidence is the AI’s rating: 0.95 when the value is clearly readable, 0.75 when it may have been garbled, 0.50 when the AI is guessing. A value that may be garbled is a warning on its box and a guessed value needs fixing; each rating counts once, so a line’s rating counts once however many fields the line has. A field the AI did not rate carries a neutral value and raises nothing. confidenceReasons lists the reading problems; Document Types & Fields lists every field name by kind, and fields also carry a boundingBox locating them on the page.
How problems affect routing
Review - any of these holds:
- Its counted problems add up to one problem that needs fixing, or two warnings, from any source: a Quality score below 90% (
holdReasonreadingwhen the reading found them,problemswhen the whole list does once the checks have run) - A line’s HS code waits for confirmation
- The scan is degraded
- A check found an exact sanctions match, a CITES Appendix I species, or could not complete
- A shipment consistency check found a conflict with another document
- CargoLint generated or cloned the document, which waits for its first review
Pending Approval - none of these holds, so the document scores 100% or 90% and is never red; it awaits a one-click approval by a reviewer.
The rule’s numbers are review in problemTypes from GET /config: one problem that needs fixing, or two warnings.
HS Code Suggestions
HS code suggestions have their own thresholds, separate from the Quality score:
- >= 0.70 - The top candidate is shown as a recommendation to confirm
- 0.25 - 0.70 - Suggestions are shown; the line is flagged as missing a code
- < 0.25 - Suggestions below this floor are dropped
Suggestions are always suggestions: CargoLint never applies an HS code automatically, and a document with an unconfirmed code always goes through review.
A declared code is validated at the 6-digit (WCO) level against the line’s description. A longer national code (HTS-10 for the United States, a Canadian 10-digit classification number, a UK 10-digit commodity code, TARIC-10 for the European Union) is also matched against the destination’s tariff schedule; national schedules are loaded for the United States, Canada, the United Kingdom and the European Union. For other destinations the check stops at six digits and the coverage line says so. See what each HS code state means for how each outcome is reported.
Improving Scores Over Time
User Corrections
When you correct an extracted value in the review queue, CargoLint logs the correction. HS code corrections build your organization’s classification history: within six hours, when a document declares a code your team has confirmed more than once for a near-identical description, that code is no longer flagged as doubtful. The history confirms declared codes; it does not rank or choose suggestions. Extraction corrections accumulate as training data used to evaluate and improve extraction models, unless you turn that off in your profile settings, which also keeps your corrections out of the classification history.
After a person completes review, the reading problems no longer apply and the document shows as Reviewed.
Using the Scores
- Sort the review queue by Quality score to see the documents with the most problems first
- Check the red and amber fields first when you review a document; hovering a field lists its problems
- Watch the Quality score on the dashboard over time to spot a new document layout or a drop in scan quality
- Read
GET /api/v1/documents/{id}/issuesto see exactly what lowered a document’s score