Configuration and Destination Profiles

Two endpoints describe the vocabularies and rules behind CargoLint’s responses. The web app reads them too, so a client that uses them shows the same kinds, labels and requirements as the app, without keeping its own copy.

Configuration

GET /config

Public: no API key or token is needed, and nothing in it is specific to an organization.

curl https://api.cargolint.com/api/v1/config

{
  "problemTypes": { "version": "2.1.0", "costs": { "serious": 0.2, "warning": 0.1, "note": 0 }, "review": { "serious": 1, "warnings": 2 }, "types": [ ... ] },
  "branding": { "supportEmail": "support@cargolint.com", "pricingPageUrl": "https://cargolint.com/pricing" },
  "documents": { "maxFileSizeMb": 20, "allowedExtensions": [".pdf", ".png", ".jpg", ".jpeg", ".tif", ".tiff"] },
  "documentRequirements": { "version": "...", "documents": [ ... ] },
  "documentKinds": { "version": "...", "kinds": [ ... ] },
  "partyRoles": { ... },
  "fieldDisplay": { ... },
  "tradeBlocs": { "version": "...", "blocs": [ ... ], "originForms": [ ... ] }
}

Key	What it holds
`problemTypes`	Every problem type a document’s issues can carry, with its one level and what it does
`documents`	The upload size limit and the accepted file extensions
`documentRequirements`	What each kind, and each form of a kind, must or should carry: the document requirements
`documentKinds`	The document kinds registry
`partyRoles`	The party roles vocabulary
`fieldDisplay`	How each extracted field is shown: field display
`tradeBlocs`	The customs unions, agreements and proofs of origin CargoLint knows

Each contract carries a version. Cache the response and refresh it when the version changes.

Problem types

problemTypes.types lists every problem a document’s issues can carry, each with one level wherever it appears:

{ "code": "missing_required_field", "owner": "checks", "kind": "document", "level": "graded", "levelBy": "The document requirement row that asks for the field (contracts/document-requirements.json, or the country package that replaces it): required is serious, nice to have a warning." }

owner is who raises it: reading (how the document was read), checks (what it says or lacks), hs (the HS verdicts) or app (CargoLint itself, on a generated, cloned or drafted document).
kind says when a problem 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 per document at their worst level, and an unconfirmed code holds it.
level is serious (shown as Needs fixing), warning or note, or graded when each finding carries its own level by the rule in levelBy; a missing field takes its level from the document requirement that asks for it. holds: true marks a problem that always holds the document, such as a degraded scan.
costs is what each level takes off the Quality score, as a fraction: 0.2 for serious, 0.1 for a warning, nothing for a note.
review is the one routing rule: a document goes to Review when its counted problems, from any source, include at least serious problems that need fixing or warnings warnings. With the costs above that is a Quality score below 90%.

Document kinds

documentKinds.kinds lists every kind CargoLint can name:

{ "id": "AirWaybill", "label": "Air Waybill", "family": "transport", "mode": "air", "tier": "Validated", "multiplicity": "onePerNumber", "multilingual": false }

The ids, tiers, families and multiplicities are explained in Document Kinds and Statuses.

Document requirements

documentRequirements.documents lists, for each kind CargoLint reads and for each form of a kind that changes it, the fields it must or should carry:

{
  "kind": "CertificateOfOrigin", "form": "Eur1",
  "rows": [
    { "id": "certifying_authority", "label": "Box 11 customs office", "fields": ["CertifyingAuthority", "AuthorityEndorsement"], "tier": "required" },
    { "id": "hs_code", "label": "HS code", "fields": ["Items[].HsCode"], "perLine": true, "tier": "notOnForm" }
  ]
}

form is an origin form id from tradeBlocs.originForms, or master or house for a bill of lading or an air waybill. A form’s rows replace its kind’s rows with the same id.
fields are the stored field names that hold the value; Items[].X is a line field. One field with a value is enough unless match is all; perLine asks for it on every line.
tier is required (missing needs fixing), niceToHave (missing is a warning), optional (missing raises nothing) or notOnForm (the form has no place for it, so it is not read). A row whose tier depends on a condition or on the invoice value is served with the tier it has when that holds; a condition that cannot be told makes it a warning at most.
The hs_code row says how a document’s line HS codes are handled: check is full (each printed code is judged against its description) or structural (only that it exists, for freight descriptions such as a bill of lading’s), and minDigits the digits a code needs.

The rows are the general case. A destination’s or export country’s profile can replace a row where its rules differ; a checked document’s coverage carries the rows as they held for it.

Party roles

partyRoles lists the roles a party plays on a trade document (shipper, seller, exporter, consignee, buyer, notify, carrier, agent) and the side of the movement each stands on (origin, destination or other), with labels and descriptions.

Field display

fieldDisplay.kinds describes, for each kind CargoLint reads, every extracted field: its name (as it appears in extraction results), label, group (document, parties, transport, goods, totals or lines), type (such as date, money, country or hsCode), whether a line field is a column of the lines table, and the party slot it belongs to. Each kind also names its party slots with their roles, its numberField, dateField, totalField and linesLabel.

"Invoice": {
  "numberField": "InvoiceId",
  "dateField": "InvoiceDate",
  "totalField": "InvoiceTotal",
  "linesLabel": "Line Items",
  "parties": [
    { "role": "seller", "prefix": "Vendor", "label": "Shipper / Exporter" },
    { "role": "consignee", "prefix": "Customer", "label": "Consignee / Importer" },
    { "role": "buyer", "prefix": "Buyer", "label": "Buyer" }
  ],
  "fields": [
    { "name": "InvoiceId", "label": "Invoice No", "group": "document", "type": "text", "column": false, "party": null }
  ]
}

New fields appear here when CargoLint starts reading them, for example the invoice’s manufacturer (ProducerName, ProducerAddress) and the air waybill consignee’s phone and email (CustomerPhone, CustomerEmail).

Trade blocs

tradeBlocs.blocs lists customs unions (such as the EU, the GCC and Mercosur), free trade agreements (such as USMCA, CPTPP, CETA and the EU-UK Trade and Cooperation Agreement) and origin schemes (EUR.1 / Pan-Euro-Med), each with its kind (customsUnion, freeTradeAgreement or originScheme), its member countries and whether its members share one tariff schedule. originForms lists the proofs of origin a certificate can be, the agreements each serves, who issues it (issuedBy) and whether it is a statement on the invoice (onInvoice).

Destination profiles

GET /destination-profiles/{destination}

Returns what a destination’s profile checks on top of the baseline, and what it does not check at all. Any user or API key of an organization can call it; the answer is the same for every organization.

destination is an ISO 3166-1 alpha-2 code. Profiles exist for US, CA, GB, AU, JP and MX, and for the European Union: EU, or the code of any member state, returns the EU profile. Other codes return 404.

curl https://api.cargolint.com/api/v1/destination-profiles/US \
  -H "X-API-Key: cl_YOUR_API_KEY"

{
  "destination": "US",
  "version": "2026.10.24.1",
  "lastVerified": "2026-10-24",
  "checks": [
    {
      "id": "us.importer-security-filing",
      "what": "The ten ISF elements for ocean cargo",
      "documentType": null,
      "level": "Shipment",
      "kind": "Filing",
      "condition": "the goods move by sea",
      "appliesAbove": null,
      "gradedBy": null,
      "elements": ["Seller name and address", "Buyer", "Importer of record number", "..."],
      "notRun": null,
      "citations": [ { "text": "19 CFR 149.3", "link": "https://www.ecfr.gov/current/title-19/section-149.3" } ]
    }
  ],
  "notChecked": [ ... ]
}

Field	Description
`level`	`Document` for the fields a document must carry; `Shipment` for a row of the expected-documents checklist
`kind`	`Fields` for the fields a document must carry (one entry per kind or form, its `elements` each with its tier); `Document`, `Filing`, `Identifier` or `Marking` for a checklist row
`documentType`	The kind whose fields are listed
`condition`	When the requirement applies: `Always`, a named claim such as `UsmcaClaim`, or a condition in words
`appliesAbove`	The value (`currency`, `amount`) above which the requirement applies at all
`gradedBy`	The value its findings are graded by
`elements`	The elements checked or listed
`notRun`	For an entry of `notChecked`: why CargoLint cannot check it
`citations`	The regulatory sources

lastVerified is when the profile was last checked against its sources. Transit and export profiles are applied to shipments (see Coverage) but are not returned by this endpoint.

What’s next

Checklist and Shipment Facts - how the profiles apply to a shipment
Document Kinds and Statuses - the registry in detail

Configuration and Destination ProfilesCargoLint REST API.