Checklist and Shipment Facts Endpoints

For each shipment, CargoLint works out the route it is checked against, which checks that route allows, and which documents, filings, identifiers and markings the file should carry for its destination, goods and mode. These come back on GET /shipments/{id} as route, coverage, checklist and declaredFacts. The endpoints below let you correct what the documents do not say.

The checklist is advice. It is never counted in the shipment’s status: a missing expected document does not make a shipment Warning or Error, and nothing you set here changes a document’s status. CargoLint notes filings; it does not file them.

Route

"route": {
  "destination": { "code": "US", "source": "document", "documentId": "6b0f7c1e-...", "field": "CustomerAddressCountry", "setByUserId": null, "setByOrganizationApiKey": false },
  "export": { "code": "CN", "source": "document", "documentId": "6b0f7c1e-...", "field": "VendorAddressCountry", "setByUserId": null, "setByOrganizationApiKey": false },
  "firstPortOfArrival": { "code": "US", "place": "Los Angeles", "source": "document", "documentId": "1a2b3c4d-...", "field": "PortOfDischarge" },
  "legs": [
    { "documentId": "1a2b3c4d-...", "documentType": "BillOfLading", "mode": "sea", "from": "Shanghai", "fromCode": "CN", "to": "Los Angeles", "toCode": "US" }
  ]
}

source is document (read from a document’s field), override (set on the shipment) or unknown.
firstPortOfArrival is the port, airport or station the transport document names in the destination country, resolved to its country.
legs lists each transport document’s origin and destination with its mode.
The countries the goods transit are a fact of the checklist (transit), not part of the route.

Coverage

"coverage": {
  "profileId": "US",
  "profileVersion": "2026.10.22.3+...",
  "reason": "destination_profile",
  "profileLastVerified": "2026-10-22",
  "destination": "US",
  "checksNotRun": [
    { "id": "transit.mx", "label": "Transit through Mexico", "status": "not_run", "reason": "CargoLint has no transit profile for Mexico; what it asks of goods crossing it is not checked.", "needs": null }
  ],
  "staleNotice": null,
  "hsScope": null,
  "requirements": [
    { "id": "shipper_address", "label": "Seller address", "fields": ["VendorAddress"], "match": "any", "perLine": false, "tier": "required", "source": "US" },
    { "id": "hs_code", "label": "HS code", "fields": ["Items[].HsCode"], "match": "any", "perLine": true, "tier": "required", "source": "general", "check": "full" }
  ]
}

Field	Description
`reason`	`destination_profile` (the destination has a profile and it ran), `default_no_profile` (the destination is known and has no profile, so only the baseline ran) or `default_destination_unknown`. A document of a kind CargoLint does not read has `kind_not_read`
`checksNotRun`	Each check that could not run and why; `needs` names the missing part of the route (`destination`, `export` or `both`) when that is what stopped it. Checklist rows that cannot be told are listed here too
`staleNotice`	Set when the profile’s sources were last checked too long ago
`hsScope`	Why declared HS codes were checked at six digits only: `destination_unknown` or `no_schedule_loaded`
`requirements`	On a document’s coverage: each document requirement as it held for the document, after its form, its country packages and their conditions: the `tier` that applied and the `source` that set it (`general`, or the package’s id)

Coverage is never a finding and never counted.

Destinations with a profile: the United States (US), Canada (CA), the European Union (EU, one profile read by every member state), the United Kingdom (GB), Australia (AU), Japan (JP) and Mexico (MX). Goods transiting the United States also get the US transit profile, and goods leaving the United States or Canada get that country’s export rows. Any other destination gets the baseline only, and the coverage says so. See Configuration and Destination Profiles for what each profile checks.

Checklist

"checklist": {
  "profileId": "US",
  "profileVersion": "2026.10.22.3+...",
  "judgingDate": "2026-10-20",
  "judgingDateSource": "ExportDate",
  "facts": [ ... ],
  "rows": [ ... ],
  "datasets": [ { "id": "regulated-fda", "version": "2026-10-16" } ]
}

judgingDate is the date the rows are judged in force on: the export date, else the invoice date, else the evaluation date. judgingDateSource is ExportDate, InvoiceDate or evaluation date.
datasets lists the regulated-goods lists the checklist read, each with the review date it was loaded under, so a result can be traced after a list is refreshed.

Facts

Each fact the rows’ conditions read, with where it came from:

{ "id": "mode", "label": "Transport mode", "value": "sea", "source": "Bill of Lading bl-4471.pdf", "known": true, "unknownReason": null, "declared": false, "documentsSaid": null }

`id`	Label	Read from the documents as
`mode`	Transport mode	The modes of the transport documents
`goods`	Regulated goods	The agencies whose regulated-goods lists the declared HS codes match for the route
`dangerous-goods`	Dangerous goods	Dangerous-goods wording in the documents
`origin`	Origin of the goods	The origins the documents state
`preference`	Preference claimed	The agreement a certificate of origin or an origin statement claims
`transit`	Transit countries	The countries the transport document’s routing crosses

A fact the documents do not give is known: false with an unknownReason, and a row whose condition reads it cannot be told. When a user declared the fact, declared is true, source names who declared it and when, and documentsSaid keeps what the documents said.

Rows

{
  "requirementId": "us.dangerous-goods-declaration",
  "kind": "Document",
  "label": "Dangerous goods declaration",
  "documentKind": "DangerousGoodsDeclaration",
  "documentFamily": null,
  "status": "missing",
  "severity": "Warning",
  "matchedDocumentIds": [],
  "note": "...",
  "citations": [ { "text": "49 CFR 172.202", "link": "https://www.ecfr.gov/current/title-49/section-172.202" } ],
  "reason": null,
  "condition": "the documents mention dangerous goods",
  "gradeNote": null,
  "disposition": null,
  "lines": null,
  "linesConfirmedBy": null,
  "elements": null
}

Field	Description
`requirementId`	The row’s id: `us.importer-security-filing` for a destination row, `expected-documents.invoice` for a baseline row, `list.<agency>.<kind>` for a row added from a regulated-goods list
`kind`	`Document`, `Filing`, `Identifier` or `Marking`
`documentKind`, `documentFamily`	The kind or family that satisfies a document row
`status`	See the table below
`severity`	For a `missing` document: `Warning` or `Info`, never `Error`
`matchedDocumentIds`	The shipment’s documents that satisfy the row
`note`, `citations`	What the row is for and the regulatory sources behind it
`reason`	Why a row is `not_needed` or `cannot_tell`
`condition`	The row’s condition in words
`gradeNote`	For a missing row graded by a value threshold, why it has its severity
`disposition`	What a user said about the row, if anything
`lines`, `linesConfirmedBy`	For a goods row read line by line, see Invoice line links
`elements`	For a filing, see Filing elements

`status`	Meaning
`present`	A document of the kind or family is in the shipment
`not_read`	A document of the kind is present, of a kind CargoLint recognizes but does not read
`missing`	The row applies and no document satisfies it
`note`	A filing, identifier or marking: it is not a document in the file, so it is noted, never graded
`not_needed`	The row’s condition does not hold for this shipment
`cannot_tell`	The condition reads a fact the documents do not give; the row is also listed among the checks not run

The baseline asks for a transport document, a commercial invoice and a packing list, at Info, wherever a destination profile does not ask for them itself. A row from a regulated-goods list is always Info, because an HS code alone does not establish the requirement; it is added only when no profile row already asks about that agency.

Filing elements

A filing row, such as the US Importer Security Filing, ISF-5, Air Cargo Advance Screening, FDA prior notice, the Canadian eManifest house bill or the EU ICS2 entry summary declaration, can list the elements the filing asks for and what the documents give of each:

{ "id": "seller", "label": "Seller name and address", "status": "found", "detail": null, "value": "Global Logistics Ltd, ...", "documentIds": ["6b0f7c1e-..."], "source": "19 CFR 149.3(a)(1)" }

status is found (with the value when it was read once), missing (detail says what is missing and where, or that its document is not in the file) or not_read (detail says why, for example an element the filer supplies, such as the importer’s tax number). The row itself stays a note.

Invoice line links

A certificate or declaration for particular goods, such as a phytosanitary or health certificate, often covers only some of the invoice’s lines. For a goods row, CargoLint proposes which invoice lines each such document covers from the words their lines share (the product, its botanical name or species, a UN number), and a user confirms or corrects them.

"lines": [
  { "lineIndex": 1, "description": "Fresh mangoes", "coveredBy": [ { "documentId": "7c8d9e0f-...", "confirmed": false } ] },
  { "lineIndex": 2, "description": "Fresh chillies", "coveredBy": [] }
],
"linesConfirmedBy": []

lineIndex is the invoice line, counted from 0. A line no document covers makes the row missing only once every matched document’s lines are confirmed; while any rests on CargoLint’s proposal the row is cannot_tell.

Dispositions

"disposition": { "disposition": "provided", "note": "Held by our broker", "setBy": "Ada Byron", "setAt": "2026-10-22T11:02:00Z" }

disposition is acknowledged (seen, it will be handled), provided (the document exists outside CargoLint) or not_applicable (with the reason in note). setBy is the user’s name, or “the organization’s API key”. A disposition is shown beside the row; it never changes the row’s status.

Declare a shipment fact

PUT    /shipments/{id}/facts/{factId}
DELETE /shipments/{id}/facts/{factId}

Declare a fact the documents do not give, or give wrongly. The declaration wins over the documents; clearing it brings back what the documents say.

`factId`	`values`
`mode`	One or more of `sea`, `air`, `road`, `rail`
`dangerous-goods`	Exactly one of `yes`, `no`
`origin`	One or more ISO 3166-1 alpha-2 codes
`transit`	One or more ISO 3166-1 alpha-2 codes
`preference`	One or more agreements: `USMCA`, `CPTPP`, `CETA`, `EU-UK-TCA` or `EUR1` (a known alias such as `CUSMA` is stored as its id)

The regulated-goods fact (goods) comes from the declared HS codes and cannot be declared; correct a code on the invoice instead.

curl -X PUT "https://api.cargolint.com/api/v1/shipments/{id}/facts/transit" \
  -H "X-API-Key: cl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "values": ["US"] }'

{
  "id": "0c9a7b6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "declaredFacts": [
    { "factId": "transit", "values": ["US"], "setBy": "the organization's API key", "setAt": "2026-10-22T11:00:00Z" }
  ]
}

A value that is not allowed returns 400 with the reason. Each change is recorded in the audit log (shipment.fact_declared, shipment.fact_cleared) and queues a new evaluation of the shipment.

Mark a checklist row

PUT    /shipments/{id}/checklist/{requirementId}/disposition
DELETE /shipments/{id}/checklist/{requirementId}/disposition

curl -X PUT "https://api.cargolint.com/api/v1/shipments/{id}/checklist/us.packing-list/disposition" \
  -H "X-API-Key: cl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "disposition": "not_applicable", "note": "Single-line bulk shipment" }'

disposition is acknowledged, provided or not_applicable; note is optional except for not_applicable, and at most 500 characters.
requirementId must be a row of a destination, transit or export profile or of the baseline, or a row a regulated-goods list adds (list.<agency>.<kind>, such as list.usda-aphis.phytosanitarycertificate) for an agency and kind the lists carry; any other id returns 400.
Returns id, requirementId and the disposition as set; DELETE returns "disposition": null.
Recorded in the audit log (shipment.checklist_disposition_set, shipment.checklist_disposition_cleared). Nothing is re-evaluated.

Confirm invoice line links

PUT    /shipments/{id}/documents/{documentId}/lines
DELETE /shipments/{id}/documents/{documentId}/lines

curl -X PUT "https://api.cargolint.com/api/v1/shipments/{id}/documents/{documentId}/lines" \
  -H "X-API-Key: cl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "covered": [1], "notCovered": [2] }'

documentId is an active document of the shipment for particular goods (the regulatedGoods family); other documents return 400, as does a shipment without an invoice.
covered and notCovered are invoice line indexes from 0. Between them they name at least one line, each line once.
The lines you name are stored as your word, and CargoLint stops proposing lines for that document. DELETE forgets what users said, and CargoLint proposes again.
Returns id, documentId, covered and notCovered. Recorded in the audit log (shipment.lines_confirmed, shipment.lines_cleared) and queues a new evaluation.

Set the destination

PUT    /shipments/{id}/destination
DELETE /shipments/{id}/destination

{ "countryCode": "DE" }

Sets the destination the shipment is checked against, replacing the one read from its documents; DELETE goes back to the documents. countryCode must be an ISO 3166-1 alpha-2 code; names, aliases and three-letter codes return 400. Returns id, destinationOverride and the new route. Each change is recorded in the audit log (shipment.destination_set, shipment.destination_cleared) and re-evaluates the shipment.

Who can call these

Any user of the organization, or its API key. Each change records who made it: the user, or the organization’s API key. On a settled shipment every endpoint on this page that changes something returns 409 with {"error": "This shipment is settled. Re-open it to change it."}; re-opening the shipment lifts the lock.

What’s next

Shipments - the rest of the shipment detail
Configuration and Destination Profiles - what each destination checks
Webhooks - shipment.evaluated after each evaluation

Checklist and Shipment Facts EndpointsCargoLint REST API.