Score one shipment against its freight benchmark

POST/freight-risk/score$0.05 per call

Scores one shipment against its freight benchmark and returns a 0-99 score, the deviation and percentile behind it, reason codes, and the points it would add to a composite score. Authenticate with `Authorization: Bearer <API key>` or the `x-api-key` header. This release accepts USD only (convert first), does not post to a counterparty's composite score (`contribution.posted_to` is null), and serves the 24-month benchmark window. Errors use RFC 9457 problem details.

Send an Idempotency-Key header to retry safely.

Request body

Field	Type	Description
originrequired	string	UN/LOCODE or ISO 3166-1 alpha-2 country code
destinationrequired	string	US port or US in v1
moderequired	string	one of "ocean", "ocean_container", "air"
hs_coderequired	string	4–10 digits; dots and spaces are stripped
weight_kgrequired	number
goods_valuerequired	object
goods_value.amountrequired	number	min 0
goods_value.currencyrequired	string	ISO 4217. This release accepts USD only; other currencies return 422 `unsupported_currency`.
freightrequired	object
freight.amountrequired	number	min 0
freight.currencyrequired	string	ISO 4217. This release accepts USD only; other currencies return 422 `unsupported_currency`.
freight_scopeoptional	string	one of "port_to_port", "door_to_door" · default "port_to_port"
incotermoptional	string	one of "EXW", "FCA", "FAS", "FOB", "CFR", "CIF", "CPT", "CIP", "DAP", "DPU", "DDP"
shipment_dateoptional	string	format date
shipment_refoptional	string	max length 128
counterparty_idoptional	string	Accepted and stored with the score. Posting the score to that entity's composite score is not enabled in this release.
optionsoptional	object
options.include_bandsoptional	boolean	default true
options.benchmark_as_ofoptional	string	format date

Response fields

Field	Type	Description
id	string
object	string
created_at	string
shipment_ref	string or null
score	integer
level	string
driving_measure	string
measures	object
measures.freight_per_kg	object
measures.freight_per_kg.value	number
measures.freight_per_kg.unit	string
measures.freight_per_kg.z	number	Robust z-score against the band
measures.freight_per_kg.percentile	number
measures.freight_per_kg.band	object
measures.freight_per_kg.band.p5	number
measures.freight_per_kg.band.p10	number
measures.freight_per_kg.band.p25	number
measures.freight_per_kg.band.p50	number
measures.freight_per_kg.band.p75	number
measures.freight_per_kg.band.p90	number
measures.freight_per_kg.band.p95	number
measures.freight_per_kg.band.robust_sigma	number	(p75 - p25) / 1.349
measures.freight_per_kg.band.n_cells	integer
measures.freight_per_kg.band.weight_kg_covered	number
measures.freight_pct_of_value	object
measures.freight_pct_of_value.value	number
measures.freight_pct_of_value.unit	string
measures.freight_pct_of_value.z	number	Robust z-score against the band
measures.freight_pct_of_value.percentile	number
measures.freight_pct_of_value.band	object
measures.freight_pct_of_value.band.p5	number
measures.freight_pct_of_value.band.p10	number
measures.freight_pct_of_value.band.p25	number
measures.freight_pct_of_value.band.p50	number
measures.freight_pct_of_value.band.p75	number
measures.freight_pct_of_value.band.p90	number
measures.freight_pct_of_value.band.p95	number
measures.freight_pct_of_value.band.robust_sigma	number	(p75 - p25) / 1.349
measures.freight_pct_of_value.band.n_cells	integer
measures.freight_pct_of_value.band.weight_kg_covered	number
measures.value_per_kg	object
measures.value_per_kg.value	number
measures.value_per_kg.unit	string
measures.value_per_kg.z	number	Robust z-score against the band
measures.value_per_kg.percentile	number
measures.value_per_kg.band	object
measures.value_per_kg.band.p5	number
measures.value_per_kg.band.p10	number
measures.value_per_kg.band.p25	number
measures.value_per_kg.band.p50	number
measures.value_per_kg.band.p75	number
measures.value_per_kg.band.p90	number
measures.value_per_kg.band.p95	number
measures.value_per_kg.band.robust_sigma	number	(p75 - p25) / 1.349
measures.value_per_kg.band.n_cells	integer
measures.value_per_kg.band.weight_kg_covered	number
reasons	array of object
reasons[].code	string	Stable within v1; new codes may be added, so treat unknown codes as info.
reasons[].severity	string
reasons[].measure	string
reasons[].message	string
contribution	object
contribution.factor	string
contribution.weight	number	Factor weight in the composite (default 0.15)
contribution.confidence_multiplier	number	The multiplier already applied to the score (1.0 high, 0.8 medium, 0.6 low). Reported for transparency.
contribution.points	number	score × weight. The score already includes the confidence multiplier, so it is not applied a second time.
contribution.composite_model	string
contribution.posted_to	string or null	counterparty_id the points were posted to
benchmark	object
benchmark.id	string
benchmark.lane_requested	string
benchmark.lane_used	string	The lane the benchmark was built for. A district benchmark is written CN-US:27-ocean_container.
benchmark.hs_used	string
benchmark.resolution	string
benchmark.window	object
benchmark.window.from	string
benchmark.window.to	string
benchmark.as_of	string
benchmark.confidence	string
benchmark.sources	array of string
benchmark.district	object	Present when the benchmark is at customs-district level: the U.S. Customs district of unlading.
benchmark.district.code	string
benchmark.district.name	string or null
benchmark.cells	object	The data behind the bands.
benchmark.cells.n_cells	integer
benchmark.cells.weight_kg_covered	number
benchmark.next_refresh	string or null	When the next version is expected (Census publishes about 28 days after the month following the data month); null when that date has passed without a new version.
model	object
model.name	string
model.version	string
sandbox	boolean	Present and true on the sandbox host, where bands are fixed fixtures.

Fields are read from a real response captured 2026-11-04. Optional fields may be absent in other responses.

Errors

400 invalid request
401 missing or bad key
403 not in your plan
429 rate limited, see Retry-After
402 payment required
404 not found
409 conflict or not ready
422 validation failed
500 server error, retry with backoff
503 temporarily unavailable
5xx retry with backoff

This endpoint reports errors as RFC 9457 problem details (application/problem+json) with a stable code and a request_id.

curl -X POST "https://api.compliancegrid.ai/freight-risk/score" \
  -H "Authorization: Bearer $CG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "CNSHA",
    "destination": "USLAX",
    "mode": "ocean_container",
    "hs_code": "8471.30",
    "weight_kg": 12400,
    "goods_value": {
      "amount": 1490000,
      "currency": "USD"
    },
    "freight": {
      "amount": 6300,
      "currency": "USD"
    }
  }'

Try it in the sandbox

Runs against sandbox.api.compliancegrid.ai with your own sandbox key, which stays in this browser. Sandbox responses are mock data. Get a free key.

Sandbox key

Remember for this tab

Request body (JSON)

Example response · captured from production 2026-11-04

{
  "id": "frs_6e082e44f8ce4e3b",
  "object": "freight_risk_score",
  "created_at": "2026-11-04T09:01:20.242Z",
  "shipment_ref": null,
  "score": 0,
  "level": "low",
  "driving_measure": "freight_pct_of_value",
  "measures": {
    "freight_per_kg": {
      "value": 0.5081,
      "unit": "USD/kg",
      "z": -0.02,
      "percentile": 47.3,
      "band": {
        "p5": 0.422292,
        "p10": 0.458759,
        "p25": 0.480125,
        "p50": 0.511471,
        "p75": 0.679763,
        "p90": 0.743363,
        "p95": 0.7807,
        "robust_sigma": 0.14799,
        "n_cells": 24,
        "weight_kg_covered": 49725481
      }
    },
    "freight_pct_of_value": {
      "value": 0.423,
      "unit": "%",
      "z": -0.62,
      "percentile": 32.3,
      "band": {
        "p5": 0.372419,
        "p10": 0.391266,
        "p25": 0.398408,
        "p50": 0.481624,
        "p75": 0.525986,
        "p90": 0.555711,
        "p95": 0.74388,
        "robust_sigma": 0.094572,
        "n_cells": 24,
        "weight_kg_covered": 49725481
      }
    },
    "value_per_kg": {
      "value": 120.1613,
      "unit": "USD/kg",
      "z": 0,
      "percentile": 50.1,
      "band": {
        "p5": 76.956874,
        "p10": 82.04351,
        "p25": 102.211303,
        "p50": 120.035977,
        "p75": 141.74656,
        "p90": 150.38972,
        "p95": 151.930666,
        "robust_sigma": 29.307085,
        "n_cells": 24,
        "weight_kg_covered": 49725481
      }
    }
  },
  "reasons": [
    {
      "code": "OK",
      "severity": "info",
      "message": "All measures are inside the expected range for this lane and commodity."
    },
    {
      "code": "Q01",
      "severity": "info",
      "message": "Confidence is medium: the benchmark used the customs-district benchmark, built from 24 data cells."
    }
  ],
  "contribution": {
    "factor": "freight_pricing",
    "weight": 0.15,
    "confidence_multiplier": 0.8,
    "points": 0,
    "composite_model": "cg-composite-v3",
    "posted_to": null
  },
  "benchmark": {
    "id": "bm_2026-08_CN-US:27-ocean_container_847130",
    "lane_requested": "CNSHA-USLAX-ocean_container",
    "lane_used": "CN-US:27-ocean_container",
    "hs_used": "847130",
    "resolution": "country_district",
    "district": {
      "code": "27",
      "name": "Los Angeles, CA"
    },
    "window": {
      "from": "2024-09-01",
      "to": "2026-08-31"
    },
    "as_of": "2026-11-03",
    "next_refresh": null,
    "confidence": "medium",
    "sources": [
      "us_census_imports_hs"
    ],
    "cells": {
      "n_cells": 24,
      "weight_kg_covered": 49725481
    }
  },
  "model": {
    "name": "freight-risk",
    "version": "1.0.0"
  }
}