Dangerous Goods (ADR) via API

The Cargoboard API supports dangerous goods (ADR) information to ensure safe and legally compliant transportation. When shipping dangerous goods, provide the ADR data in the dangerousGoods array of the shipment line that contains them.

The information is based on the requirements of the European Agreement concerning the International Carriage of Dangerous Goods by Road (ADR) and is used for transport planning, carrier validation and legal compliance.

Example

The following example shows a shipment containing one package of UN 3480 – Lithium-ion batteries.

"lines": [
  {
    "unitQuantity": 1,
    "unitPackageType": "KT",
    "unitLength": 33,
    "unitWidth": 31,
    "unitHeight": 45,
    "unitWeight": 11,
    "content": "Batteries",
    "wantsPalletExchange": false,
    "isStackable": false,
    "dangerousGoods": [
      {
        "unNo": "3480",
        "substanceName": "LITHIUM-IONEN-BATTERIEN",
        "packageType": "KISTE",
        "quantity": 1,
        "weightGross": 11,
        "weightNetOrVolume": 9,
        "weightNetOrVolumeUnit": "NGW",
        "riskMain": "9A",
        "pointsTotal": 27,
        "pointsMultiplier": 3,
        "adrVersion": "ADR2025",
        "classificationCode": "M4",
        "packagingGroup": null,
        "isExemptedQuantity": false,
        "isLimitedQuantity": false,
        "isHighConsequencesDangerousGood": false,
        "isSpecialProvision188": false,
        "transportCategory": "2",
        "tunnelRestriction": "(E)"
      }
    ]
  }
]

📦
Dangerous goods (including LQ/EQ) cannot be shipped as parcels.

A complete booking flow with dangerous goods is shown in B2C shipment with dangerous goods.

ADR fields

Field	Description
`unNo`	UN number of the dangerous goods.
`substanceName`	Proper shipping name according to ADR.
`packageType`	Descriptive packaging name in the national language, e.g. `KISTE` — see below.
`quantity`	Number of dangerous goods packages of this type. This is the authoritative value — always fill it.
`packageQuantity`	Optional. You can leave it empty; if you send it, use the same value as `quantity`.
`weightGross`	Gross weight of the dangerous goods package in kilograms.
`weightNetOrVolume`	Net quantity or volume of the dangerous goods, depending on the value of `weightNetOrVolumeUnit`.
`weightNetOrVolumeUnit`	Indicates whether `weightNetOrVolume` represents a net weight (`NGW`) or a volume in litres (`LIT`).
`riskMain`	Primary hazard label according to ADR — see allowed values.
`pointsTotal`	Total ADR points for the shipment.
`pointsMultiplier`	ADR multiplier used to calculate transport points.
`adrVersion`	ADR regulation version. Currently only `ADR2025` is supported — any other value is rejected.
`classificationCode`	ADR classification code.
`packagingGroup`	ADR packing group, or `null` if none applies (as in the example above).
`transportCategory`	ADR transport category.
`tunnelRestriction`	ADR tunnel restriction code.
`isLimitedQuantity`	Indicates whether the shipment is transported as Limited Quantity (LQ).
`isExemptedQuantity`	Indicates whether the shipment is transported as Excepted Quantity (EQ).
`isSpecialProvision188`	Indicates whether ADR Special Provision 188 applies.
`isHighConsequencesDangerousGood`	Indicates whether the dangerous goods are classified as High Consequence Dangerous Goods.

Hazard labels

riskMain and riskAdditional1–riskAdditional3 accept these values: 2.1, 2.2, 2.3, 3, 4.1, 4.2, 4.3, 5.1, 5.2, 6.1, 8, 9, 9A, LQ. The main label and the additional labels must all be different.

Restrictions

packageType is required for every dangerous goods entry.
weightGross must not exceed the weight of the line (unitWeight × unitQuantity).
Dangerous goods can't be shipped to or from Great Britain (GB), Ireland (IE), Norway (NO), Sweden (SE), Turkey (TR) and Finland (FI), to some postcode areas, or to private consignees in Spain.
Dangerous goods can't be shipped as parcels.

Weight / volume unit (`weightNetOrVolumeUnit`)

The field weightNetOrVolumeUnit specifies whether the value in weightNetOrVolume represents a net weight or a volume.

The following values are supported:

Value	Description
`NGW`	Net weight (value provided in kilograms)
`LIT`	Liter / Volume (value provided in litres)

❗️
Only NGW and LIT are accepted
If your system stores the net quantity in kilograms, send the unit as NGW. Values such as kg, KG, Kilogram, l or Liter are not supported.

Correct example:

{
  "weightNetOrVolume": 9,
  "weightNetOrVolumeUnit": "NGW"
}

Incorrect examples:

{
  "weightNetOrVolumeUnit": "kg"
}

{
  "weightNetOrVolumeUnit": "Kilogram"
}

Package type (`packageType`)

packageType is a descriptive packaging name in the national language (e.g. German) — not a code.

Use the singular form.
Don't use abbreviations or ADR packaging codes such as 4G.
You can add details after the packaging name, e.g. FASS aus Stahl.

Valid examples

FASS
FASS aus Stahl
FASS aus Stahl mit abnehmbarem Deckel
KANISTER
KANISTER aus Aluminium
KISTE
KOMBINATIONSVERPACKUNG

Invalid examples

Value	Reason
`FAESSER aus Stahl`	Package descriptions must be provided in singular form. Use `FASS`.
`KANI`	Abbreviations are not permitted. Use `KANISTER`.
`4G`	ADR packaging codes are not accepted. Use a descriptive package type such as `KISTE`.

💡
Recommendation
Whenever possible, provide the complete packaging description rather than only the package type. This improves interoperability with carriers and downstream ADR systems.

UN number lookup (ADR master data)

Instead of maintaining your own dangerous goods database, you can retrieve ADR master data for a UN number directly from the Cargoboard API and use it to fill the dangerousGoods fields of your booking. This way your ADR data is always up to date.

GET /v1/dangerous-goods/un-numbers/{unNumber}

Full specification: Get dangerous goods ADR data by UN number.

A UN number can apply to several packing groups, each with its own ADR data — for example different Limited Quantity limits. The response therefore contains one entry per packing group in entries. Pick the entry that matches the packing group of your goods.

Example: UN 1993 (three packing groups, shortened)

{
  "unNumber": "1993",
  "entries": [
    { "packingGroup": "I",   "properShippingName": "ENTZÜNDBARER FLÜSSIGER STOFF, N.A.G.", "adrClass": "3", "limitedQuantityQuantityText": "0",   "exemptedQuantityType": "E3" },
    { "packingGroup": "II",  "properShippingName": "ENTZÜNDBARER FLÜSSIGER STOFF, N.A.G.", "adrClass": "3", "limitedQuantityQuantityText": "1 L", "exemptedQuantityType": "E2" },
    { "packingGroup": "III", "properShippingName": "ENTZÜNDBARER FLÜSSIGER STOFF, N.A.G.", "adrClass": "3", "limitedQuantityQuantityText": "5 L", "exemptedQuantityType": "E1" }
  ]
}

Example: UN 3480 (no packing group, complete)

UN numbers without a packing group return a single entry with packingGroup: null.

{
  "unNumber": "3480",
  "entries": [
    {
      "packingGroup": null,
      "properShippingName": "LITHIUM-IONEN-BATTERIEN",
      "adrClass": "9",
      "classificationCode": "M4",
      "adrRelease": "012",
      "labels": {
        "mainRisk": "9A",
        "subRisks": []
      },
      "tunnelRestriction": "(E)",
      "limitedQuantityCode": "LQ00",
      "limitedQuantityQuantityText": "0",
      "exemptedQuantityType": "E0",
      "packagingInstructions": "P903 P908 P909 P910 P911 LP903 LP904 LP905 LP906",
      "generalSpecialRegulations": "188 230 310 348 376 377 387 636 677",
      "flags": {
        "limitedQuantity": true,
        "highConsequenceDangerousGoods": false,
        "notOtherwiseSpecifiedRequired": false,
        "specialRegulation274": false,
        "specialRegulation61": false,
        "specialRegulation640": false,
        "allowedInCentralCrossDock": true,
        "allowedOnLineHaul": true
      }
    }
  ]
}

From lookup to booking

Lookup field (entry)	Booking field (`dangerousGoods[]`)
`unNumber` (top level)	`unNo`
`properShippingName`	`substanceName`
`packingGroup`	`packagingGroup`
`classificationCode`	`classificationCode`
`labels.mainRisk`	`riskMain`
`labels.subRisks`	`riskAdditional1` – `riskAdditional3`
`tunnelRestriction`	`tunnelRestriction`

Responses

Response	Meaning
`200`	ADR data found — one entry per packing group
`202`	Data is being fetched in the background — retry after a short while
`404`	No ADR data exists for this UN number (`code`: `DANGEROUS_GOODS_UN_NUMBER_NOT_FOUND`)
`422`	Invalid UN number — use 1 to 4 digits, e.g. `3480`
`429`	More than 20 requests per minute

Dangerous Goods ⚠

Example

ADR fields

Hazard labels

Restrictions

Weight / volume unit (`weightNetOrVolumeUnit`)

Only `NGW` and `LIT` are accepted

Package type (`packageType`)

Valid examples

Invalid examples

Recommendation

UN number lookup (ADR master data)

Example: UN 1993 (three packing groups, shortened)

Example: UN 3480 (no packing group, complete)

From lookup to booking

Responses

Example

ADR fields

Hazard labels

Restrictions

Weight / volume unit (weightNetOrVolumeUnit)

Only NGW and LIT are accepted

Package type (packageType)

Valid examples

Invalid examples

Recommendation

UN number lookup (ADR master data)

Example: UN 1993 (three packing groups, shortened)

Example: UN 3480 (no packing group, complete)

From lookup to booking

Responses

Weight / volume unit (`weightNetOrVolumeUnit`)

Only `NGW` and `LIT` are accepted

Package type (`packageType`)