A dangerous goods API takes a product description and returns the answers a shipper needs before a parcel leaves the warehouse: is it regulated at all, which UN number applies, which proper shipping name, hazard class and packing group go on the paperwork, and which carriers will accept it. This guide explains how the request is built, what a usable response looks like, and where a good dangerous goods API should stop and ask for more information rather than guess.
It is written for developers and operations teams who classify more than a handful of products. If you have one item to check, the free classifier on the homepage is quicker. The API earns its place once the catalogue runs to hundreds of lines and someone has to make the answers repeatable and auditable.
What a dangerous goods API request should carry
Most classification errors start with thin input, not with a wrong lookup. The request body accepts four kinds of evidence, and the more specific the evidence, the fewer assumptions the answer has to make:
- A free-text description, up to 2,000 characters. This is the usual starting point, such as "70% isopropyl alcohol screen cleaner, 500 ml spray bottle".
- Composition rows, up to 100. A CAS number in a composition row usually settles the match outright, because it identifies the substance rather than the marketing name on the bottle.
- Safety data sheet text, up to 200,000 characters. Section 14, the transport information, is the most useful part to paste, although it is often written for a bulk drum rather than the retail size you ship.
- A UN number, if you already hold one and want it checked against the description rather than trusted on its own.
The practical rule is to send the composition and the transport section together wherever you have them. A description says what the product is called. The composition says what is in it, and that is what a dangerous goods API is actually classifying.
A worked example: a 70% isopropyl cleaner
The API documentation uses a useful test case: a 500 ml spray bottle of screen cleaner that is 70% isopropyl alcohol, with CAS number 67-63-0. The request carries the description, the composition row and the modes the parcel will travel by, ground and air.
The published response reads as follows. The determination is classified, isHazmat is true, and the UN number is UN1219 with the proper shipping name Isopropanol. The hazard class is 3 with no division, the packing group is II, the label is FLAMMABLE LIQUID and the ERG guide is 129. The limited quantity flag is set. Carrier eligibility shows UPS as contract-required by ground and by air, and USPS as restricted by ground and prohibited by air.
Three fields matter more than the rest. confidence reads medium, which tells you the match is strong but not airtight. evidence names the CAS number as the matched key with a weight of 120, so you can see what drove the answer. reasoning lists each step in order. A shipper who has to defend a classification to a carrier needs exactly that trail, not just a four-digit number.
Notice where the operational decision actually sits. The packing group is one line of the answer, but the carrier table is what changes what you can do. The same bottle that ships by UPS ground under contract cannot go by USPS air at all, and a dangerous goods API that returned only the UN number would leave that conclusion to a person who may not check it.
When a dangerous goods API should refuse to answer
A useful dangerous goods API has to be willing to say no. Nail polish is a good test. The identity is clear: it is UN1263, paint or paint related material. The packing group, though, turns on flash point. The documented response for that case returns needs_review, keeps UN1263 and the paint shipping name, leaves the packing group null, and names the missing field, flashPointC.
The reason is in the regulation. For Class 3 flammable liquids, the packing group under 49 CFR 173.121 depends on flash point and initial boiling point. In broad terms, a flash point below 23 °C with an initial boiling point above 35 °C points to packing group II, and a flash point from 23 °C to 60 °C points to packing group III. A packing group chosen without that figure is a guess, and a guessed packing group travels on the shipping paper where a carrier's screening will read it.
Send the flash point and the same request completes. The API handles other properties in the same way: a concentration for Class 8 corrosives, an alcohol by volume figure for beverages, and watt-hours for lithium batteries. That design is deliberate. A nearest-match answer looks helpful in a demo, but it moves the risk from the API into your shipping documents, where nobody can see it until something goes wrong.
| What you send | Determination | Packing group | What you do next |
|---|---|---|---|
| 70% isopropyl alcohol with CAS 67-63-0 | classified | II | Pack to PG II and check carrier eligibility for each mode |
| Nail polish, no flash point | needs_review | null | Take flashPointC from the safety data sheet and resubmit |
| Nail polish, flash point supplied | completes once the property is present | Set by the flash point | Keep the reasoning and the evidence with the SKU |
Running a dangerous goods API in bulk and keeping the audit trail
For a catalogue, the batch endpoint accepts up to 500 items in one call, and each item is classified independently. Give every item a SKU so the results match back to your product records without manual work. An item that comes back as needs_review does not block the others, which is the behaviour you want: the blocked SKU goes into a queue for a flash point or a concentration, not into a shipment.
Two features support the audit side. The determination is stored when the database is configured, so a certificate can be issued later against the exact result that was returned, as a PDF for printing or as signed JSON for a system. The response also carries the ruleset version and a hash, so you can show which rules produced an answer even after the rules have since changed. Store the classification ID and the ruleset hash against each SKU in your own system. That single habit is what turns a classification into something you can defend six months later.
A reasonable integration writes the UN number, packing group, carrier table, classification ID and ruleset hash to its own product record. It re-runs a SKU only when the description, composition or ruleset changes. Re-running everything nightly adds cost and churn without adding any evidence.
Build against the API, or read the rules yourself
You can classify by hand from the Hazardous Materials Table at 49 CFR 172.101, which the eCFR publishes free. That table is the authority, and for a one-off item it is the right tool. The work around it is what takes the time: checking composition, applying the packing group logic, working out carrier eligibility for each mode, and recording why each answer was given. That is the gap the API fills.
The regulations also move on a schedule, and the API inherits that. The 67th edition of the IATA Dangerous Goods Regulations applies through 31 December 2026, and the 68th edition takes effect on 1 January 2027. A classification run in January needs the new edition checked, whichever tool produced it. The same caution applies to the UN Model Regulations, which are the upstream source for the whole system.
Precedence is the step most often skipped by hand. A specific UN entry should win over a generic n.o.s. entry, and the UN number lookup guide explains why. A rules engine should never skip that step, and it should apply it the same way to the four-hundredth SKU as to the first.
A classification is only as reliable as the input it was given. A dangerous goods API that returns a confident answer from a product name alone has made a guess, and the response should make that visible.
Classify7 ruleset team
Where dangerous goods API integrations go wrong
- Sending only a product title. Marketing names carry no classification; the composition does.
- Treating needs_review as a failure. It means the API declined to guess and has named the missing field.
- Ignoring the modes you ship by. An air answer and a ground answer differ, and a ground-only result does not clear a parcel for air.
- Discarding the evidence and reasoning arrays. They are what you show a carrier or an auditor when asked how a packing group was reached.
- Re-using an old classification without checking the ruleset hash. An answer from an earlier ruleset may no longer be the current answer.
Next steps
Start with one product through the free classifier to see the shape of the answer, then move the same description and composition into the API. The API reference covers authentication and the full request schema. Before you classify anything, confirm that it is in scope at all with the guide on whether your product is a dangerous good. For the hazard classes themselves, the hazard class reference sets out the nine classes in one place.
