Skip to main content

Validation API

Validate shipment data against deterministic business rules.

info

Validation is synchronous — the response contains the full validation result. No polling required.

Validate Shipment​

POST /api/v1/shipments/validate

Request Body​

The full TradeShipment object. See TradeShipment Schema.

Response (Pass)​

{
  "valid": true,
  "score": 100,
  "results": [],
  "validated_at": "2026-03-31T10:00:00Z",
  "run_id": "run_a1b2c3d4"
}

Response (Fail)​

{
  "valid": false,
  "score": 62,
  "results": [
    {
      "rule": "hs_code_exists",
      "category": "HS Code",
      "severity": "error",
      "message": "HS code 9999.99.9999 not found in US HTS schedule",
      "field": "goods.line_items[0].hs_code"
    },
    {
      "rule": "port_code_valid",
      "category": "Port Code",
      "severity": "error",
      "message": "Port XXABC is not a valid UN/LOCODE",
      "field": "route.port_of_loading"
    },
    {
      "rule": "total_value_matches",
      "category": "Values",
      "severity": "warning",
      "message": "Total value (25000) does not match sum of line items (24500)",
      "field": "goods.total_value"
    }
  ],
  "validated_at": "2026-03-31T10:00:00Z",
  "run_id": "run_b2c3d4e5"
}

Severity Levels​

SeverityMeaning
errorMust be fixed before document generation
warningRecommended to fix, but documents can still be generated
infoInformational note, no action required

Validate an Existing Shipment​

POST /api/v1/shipments/:id/validate

Validates the shipment using its stored data. Returns the same response format.