Document Kinds and Statuses
CargoLint REST API.

Document Kinds and Statuses

Responses and webhooks name a document’s kind by its registry id, in detectedDocumentType, and its state by a status string, in status. This page lists both. The registry itself is served by GET /config under documentKinds, with a version; read it from there rather than hard-coding the list.

documentType on a document is the file’s media type (application/pdf, image/png, image/jpeg or image/tiff), not its kind.

Tiers

Each kind sits in one tier, which says how far CargoLint goes with it:

A Recognized document ends with status Recognized, and its check result is a pass with a coverage statement whose reason is kind_not_read: the check did not run, and the coverage says so.

Document kinds

RoadConsignmentNote covers the CMR road consignment note. Unknown is a document CargoLint could not name; it is kept like any other Recognized document.

Families

transport, commercial, origin, regulatedGoods and customs. An expected-documents row can ask for a family rather than a kind; any kind of that family satisfies it. A transport kind also has a mode (sea, air, road or rail), which is how CargoLint reads a shipment’s transport mode.

Kept per shipment

The registry’s multiplicity says how many active documents of a kind a shipment keeps:

• one - a newer document of the kind replaces the older one for checks.
• onePerNumber - one per document number. A corrected copy with the same number replaces the old one; different numbers stay active, so a master bill and its house bill are both kept. The house bill drives the shipment checks, and the master is compared with it.
• many - every document of the kind is kept.

A replaced document stays attached to its shipment with supersededByDocumentId and supersededAt set.

Other registry fields

• multilingual - the kind is a form pre-printed in several languages, so it is read even when its labels are not in English. Other kinds must be in English.

Which kinds and forms carry HS codes, and which fields each must carry, are in the document requirements.

Document statuses

A document’s status moves from PendingApproval to RequiresReview when its document checks finish and its counted problems add up to one that needs fixing, or two warnings. It can move back from PendingApproval or Completed to RequiresReview when a check across its shipment finds an Error, or from PendingApproval when it finds a Warning. A document a person already approved stays Completed on a Warning. Statuses are never raised automatically.

For what each status means in the app, see Document Statuses.

Where these values appear

• detectedDocumentType and status on GET /documents, GET /documents/{id} and the shipment detail.
• documentKind and documentFamily on checklist rows.
• status, and the kind id in documentType, in webhook payloads, including document.recognized and document.split. In webhook payloads documentType is the kind, not the media type.