Dangerous Goods

The Dangerous Goods API provides the ability to determine if certain materials, such as dangerous goods or hazardous materials, can be shipped with UPS. The API's two endpoints - Chemical Reference Data and Acceptance Audit Precheck, help perform pre-checks before shipping any dangerous goods.

Reference

Try out UPS APIs with example requests using Postman. Explore API documentation and sample applications through GitHub.

Chemical Reference Data

The Chemical Reference Data endpoint of the Dangerous Goods API allows shippers look up hazardous material reference information by ID number and shipping name of the specified regulated good.

SecurityOAuth2

Request

path Parameters

version

required

string >= 1

Default: "v2409"

Version of the API.

Valid values:

v2409

header Parameters

transId required	string An identifier unique to the request. Length 32
transactionSrc required	string Default: testing An identifier of the client/source application that is making the request.Length 512

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1

required

object (ChemicalReferenceDataRequest) <= 1

Dangerous Goods Utility Request container for Chemical Reference Data.

required

object (ChemicalReferenceDataRequest_Request) <= 1

Contains Chemical Reference Data request criteria components.

RequestOption	Array of strings
SubVersion	string <= 1 When UPS introduces new elements in the response that are not associated with new request elements, Subversion is used. This ensures backward compatibility. To get such elements you need to have the right Subversion. The value of the subversion is explained in the Response element Description. Format: YYMM = Year and month of the release. Example: 1801 = 2018 January Supported values: 1801
	object (Request_TransactionReference) <= 1 TransactionReference identifies transactions between client and server.

IDNumber

string [ 1 .. 6 ] characters <= 1

This is the ID number (UN/NA/ID) for the specified commodity. UN/NA/ID Identification Number assigned to the specified regulated good. (Include the UN/NA/ID as part of the entry). At least one of the information - IDNumber or ProperShippingName should be provided to retrieve Chemical Reference Data.

ProperShippingName

string [ 1 .. 250 ] characters <= 1

The Proper Shipping Name assigned by ADR, CFR or IATA. At least one of the information - IDNumber or ProperShippingName should be provided to retrieve Chemical Reference Data.

ShipperNumber

required

string = 6 characters <= 1

Shipper's six digit account number. Your UPS Account Number must have correct Dangerous goods contract to successfully use this Webservice.

Responses

200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/dangerousgoods/{version}/chemicalreferencedata

Request samples

application/json

{"ChemicalReferenceDataRequest": {"IDNumber": "UN1088",
"ProperShippingName": "Acetal",
"ShipperNumber": "Your Shipper Number"
}
}

Response samples

200
400
401
403
429

application/json

{"ChemicalReferenceDataResponse": {"Response": {"ResponseStatus": {"Code": "s",
"Description": "string"
},
"Alert": [{"Code": "string",
"Description": "string"
}
],
"TransactionReference": {"CustomerContext": "string"
}
},
"ChemicalData": [{"ChemicalDetail": {"RegulationSet": "strin",
"IDNumber": "string",
"HazardousMaterialsDescription": "string",
"ClassDivisionNumber": "string",
"SubRiskClass": "string",
"PackagingGroupType": "string",
"SpecialPermit": "stri",
"TechnicalNameRequiredIndicator": "s",
"AdditionalShippingInformationRequiredIndicator": "s",
"TunnelRestrictionCode": "string",
"TransportCategory": "s",
"TransportMultiplierQuantity": "s",
"ChannelTunnelAcceptedIndicator": "s",
"ChemicalType": "stringstringstringstrings",
"CAToUSShipmentAllowedIndicator": "s"
},
"ProperShippingNameDetail": {"ProperShippingName": [ ]
},
"PackageQuantityLimitDetail": [{"PackageQuantityLimitTypeCode": "string",
"Quantity": "stringstringstr",
"UOM": "string",
"PackagingInstructionCode": "string"
}
]
}
]
}
}

Acceptance Audit Pre-check

Enables shippers perform pre-checks before shipping dangerous goods using the chemical record identifier and the commodity's regulated level code.

SecurityOAuth2

Request

path Parameters

version

required

string

Default: "v3"

API version

Valid values:

v2

header Parameters

transId required	string An identifier unique to the request. Length 32
transactionSrc required	string Default: testing An identifier of the client/source application that is making the request.Length 512

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1

required

object (AcceptanceAuditPreCheckRequest) <= 1

Dangerous Goods Utility Request container for Acceptance Audit Pre-check.

required

object (AcceptanceAuditPreCheckRequest_Request) <= 1

Contains Dangerous Goods Utility Acceptance Audit Pre-check request criteria elements.

RequestOption	string Enables the user to specify optional processing. Currently, there is no optional process in Dangerous Goods Utility WS.
SubVersion	string Not Used.
	object (Request_TransactionReference) <= 1 TransactionReference identifies transactions between client and server.

OriginRecordTransactionTimestamp

string <= 1

The time that the request was made from the originating system. UTC time down to milliseconds. Example: 2016-07-14T12:01:33.999

required

object (AcceptanceAuditPreCheckRequest_Shipment) <= 1

Contains shipment information.

ShipperNumber required	string = 6 characters <= 1 Shipper's six digit account number. Your UPS Account Number must have correct Dangerous goods contract to successfully use this Webservice.
required	object (Shipment_ShipFromAddress) <= 1 Ship From address container.
required	object (Shipment_ShipToAddress) <= 1 Ship To address container.
required	object (Shipment_Service) <= 1 UPS service type.
RegulationSet	string [ 3 .. 5 ] characters <= 1 The Regulatory set associated with every regulated shipment. It must be same across the shipment. Not required when the CommodityRegulatedLevelCode is EQ. Valid values: ADR, 49CFR, IATA. ADR = Europe to Europe Ground Movement 49CFR = HazMat regulated by US Dept. of Transportation within the U.S. or ground shipments to Canada IATA= Worldwide Air movement.
required	Array of objects (Shipment_Package) <= 1000

Responses

200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/dangerousgoods/{version}/acceptanceauditprecheck

Request samples

application/json

{"AcceptanceAuditPreCheckRequest": {"Request": {"RequestOption": "Request",
"TransactionReference": {"CustomerContext": ""
}
},
"OriginRecordTransactionTimestamp": "      ",
"Shipment": {"ShipperNumber": " ",
"ShipFromAddress": {"AddressLine": "226 ELMWOOD AVE",
"City": "BOGOTA",
"StateProvinceCode": "NJ",
"PostalCode": "7603",
"CountryCode": "US"
},
"ShipToAddress": {"AddressLinde": "MY STREET 11",
"City": "DIEGEM",
"StateProvinceCode": "          ",
"PostalCode": "1831",
"CountryCode": "BE"
},
"Service": {"Code": "01",
"Description": "GROUND "
},
"RegulationSet": "IATA",
"Package": {"PackageIdentifier": "12",
"PackageWeight": {"Weight": "12",
"UnitOfMeasurement": {"Code": "KGS",
"Description": "KILOS"
}
},
"QValue": "0",
"OverPackedIndicator": "I",
"TransportationMode": "PAX",
"EmergencyContact": "SELF",
"ChemicalRecord": {"ChemicalRecordIdentifier": "12",
"ReportableQuantity": "RQ",
"ClassDivisionNumber": "3",
"SubRiskClass": "            ",
"IDNumber": "UN2621",
"PackagingGroupType": "III",
"Quantity": "10",
"UOM": "KGS",
"PackagingInstructionCode": "Y344",
"ProperShippingName": "ACETYL METHYL CARBINOL",
"TechnicalName": "            ",
"AdditionalDescription": "N",
"PackagingType": "Fiberboard Box",
"HazardLabelRequired": "LABEL IT",
"PackagingTypeQuantity": "22",
"CommodityRegulatedLevelCode": "LQ",
"TransportCategory": "3",
"TunnelRestrictionCode": "1"
}
}
}
}
}

Response samples

200
400
401
403
429

application/json

{"AcceptanceAuditPreCheckResponse": {"Response": {"ResponseStatus": {"Code": "s",
"Description": "string"
},
"Alert": [{"Code": "string",
"Description": "string"
}
],
"AlertDetail": [{"Code": "string",
"Description": "string",
"ElementLevelInformation": {"Level": "s",
"ElementIdentifier": [{"Code": null,
"Value": null
}
]
}
}
],
"TransactionReference": {"CustomerContext": "string"
}
},
"ShipperNumber": "string",
"Service": {"Code": "string"
},
"RegulationSet": "strin",
"PackageResults": [{"PackageIdentifier": "strin",
"AccessibleIndicator": "s",
"EuropeBUIndicator": "s",
"ChemicalRecordResults": [{"ChemicalRecordIdentifier": "str",
"ADRPoints": "stri",
"TransportCategory": "s",
"TunnelRestrictionCode": "string",
"ADRUnits": "strings"
}
]
}
]
}
}

Chemical Reference DataDeprecated

The Chemical Reference Data endpoint of the Dangerous Goods API allows shippers look up hazardous material reference information by ID number and shipping name of the specified regulated good.

SecurityOAuth2

Request

path Parameters

deprecatedVersion

required

string >= 1

Default: "v1"

Version of the API.

Valid values:

v1
v1801.

header Parameters

transId required	string An identifier unique to the request. Length 32
transactionSrc required	string Default: testing An identifier of the client/source application that is making the request.Length 512

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1

required

object (ChemicalReferenceDataRequest) <= 1

Dangerous Goods Utility Request container for Chemical Reference Data.

required

object (ChemicalReferenceDataRequest_Request) <= 1

Contains Chemical Reference Data request criteria components.

RequestOption	Array of strings
SubVersion	string <= 1 When UPS introduces new elements in the response that are not associated with new request elements, Subversion is used. This ensures backward compatibility. To get such elements you need to have the right Subversion. The value of the subversion is explained in the Response element Description. Format: YYMM = Year and month of the release. Example: 1801 = 2018 January Supported values: 1801
	object (Request_TransactionReference) <= 1 TransactionReference identifies transactions between client and server.

IDNumber

string [ 1 .. 6 ] characters <= 1

This is the ID number (UN/NA/ID) for the specified commodity. UN/NA/ID Identification Number assigned to the specified regulated good. (Include the UN/NA/ID as part of the entry). At least one of the information - IDNumber or ProperShippingName should be provided to retrieve Chemical Reference Data.

ProperShippingName

string [ 1 .. 250 ] characters <= 1

The Proper Shipping Name assigned by ADR, CFR or IATA. At least one of the information - IDNumber or ProperShippingName should be provided to retrieve Chemical Reference Data.

ShipperNumber

required

string = 6 characters <= 1

Shipper's six digit account number. Your UPS Account Number must have correct Dangerous goods contract to successfully use this Webservice.

Responses

200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/dangerousgoods/{deprecatedVersion}/chemicalreferencedata

Request samples

application/json

{"ChemicalReferenceDataRequest": {"IDNumber": "UN1088",
"ProperShippingName": "Acetal",
"ShipperNumber": "Your Shipper Number"
}
}

Response samples

200
400
401
403
429

application/json

{"ChemicalReferenceDataResponse": {"Response": {"ResponseStatus": {"Code": "s",
"Description": "string"
},
"Alert": [{"Code": "string",
"Description": "string"
}
],
"TransactionReference": {"CustomerContext": "string"
}
},
"ChemicalData": [{"ChemicalDetail": {"RegulationSet": "strin",
"IDNumber": "string",
"HazardousMaterialsDescription": "string",
"ClassDivisionNumber": "string",
"SubRiskClass": "string",
"PackagingGroupType": "string",
"SpecialPermit": "stri",
"TechnicalNameRequiredIndicator": "s",
"AdditionalShippingInformationRequiredIndicator": "s",
"TunnelRestrictionCode": "string",
"TransportCategory": "s",
"TransportMultiplierQuantity": "s",
"ChannelTunnelAcceptedIndicator": "s",
"ChemicalType": "stringstringstringstrings",
"CAToUSShipmentAllowedIndicator": "s"
},
"ProperShippingNameDetail": {"ProperShippingName": [ ]
},
"PackageQuantityLimitDetail": [{"PackageQuantityLimitTypeCode": "string",
"Quantity": "stringstringstr",
"UOM": "string",
"PackagingInstructionCode": "string"
}
]
}
]
}
}

Acceptance Audit Pre-checkDeprecated

Enables shippers perform pre-checks before shipping dangerous goods using the chemical record identifier and the commodity's regulated level code.

SecurityOAuth2

Request

path Parameters

deprecatedVersion

required

string

Default: "v1"

API version

Valid values:

v1

header Parameters

transId required	string An identifier unique to the request. Length 32
transactionSrc required	string Default: testing An identifier of the client/source application that is making the request.Length 512

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1

required

object (AcceptanceAuditPreCheckRequest) <= 1

Dangerous Goods Utility Request container for Acceptance Audit Pre-check.

required

object (AcceptanceAuditPreCheckRequest_Request) <= 1

Contains Dangerous Goods Utility Acceptance Audit Pre-check request criteria elements.

RequestOption	string Enables the user to specify optional processing. Currently, there is no optional process in Dangerous Goods Utility WS.
SubVersion	string Not Used.
	object (Request_TransactionReference) <= 1 TransactionReference identifies transactions between client and server.

OriginRecordTransactionTimestamp

string <= 1

The time that the request was made from the originating system. UTC time down to milliseconds. Example: 2016-07-14T12:01:33.999

required

object (AcceptanceAuditPreCheckRequest_Shipment) <= 1

Contains shipment information.

ShipperNumber required	string = 6 characters <= 1 Shipper's six digit account number. Your UPS Account Number must have correct Dangerous goods contract to successfully use this Webservice.
required	object (Shipment_ShipFromAddress) <= 1 Ship From address container.
required	object (Shipment_ShipToAddress) <= 1 Ship To address container.
required	object (Shipment_Service) <= 1 UPS service type.
RegulationSet	string [ 3 .. 5 ] characters <= 1 The Regulatory set associated with every regulated shipment. It must be same across the shipment. Not required when the CommodityRegulatedLevelCode is EQ. Valid values: ADR, 49CFR, IATA. ADR = Europe to Europe Ground Movement 49CFR = HazMat regulated by US Dept. of Transportation within the U.S. or ground shipments to Canada IATA= Worldwide Air movement.
required	Array of objects (Shipment_Package) <= 1000

Responses

200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/dangerousgoods/{deprecatedVersion}/acceptanceauditprecheck

Request samples

application/json

{"AcceptanceAuditPreCheckRequest": {"Request": {"RequestOption": "Request",
"TransactionReference": {"CustomerContext": ""
}
},
"OriginRecordTransactionTimestamp": "      ",
"Shipment": {"ShipperNumber": " ",
"ShipFromAddress": {"AddressLine": "226 ELMWOOD AVE",
"City": "BOGOTA",
"StateProvinceCode": "NJ",
"PostalCode": "7603",
"CountryCode": "US"
},
"ShipToAddress": {"AddressLinde": "MY STREET 11",
"City": "DIEGEM",
"StateProvinceCode": "          ",
"PostalCode": "1831",
"CountryCode": "BE"
},
"Service": {"Code": "01",
"Description": "GROUND "
},
"RegulationSet": "IATA",
"Package": {"PackageIdentifier": "12",
"PackageWeight": {"Weight": "12",
"UnitOfMeasurement": {"Code": "KGS",
"Description": "KILOS"
}
},
"QValue": "0",
"OverPackedIndicator": "I",
"TransportationMode": "PAX",
"EmergencyContact": "SELF",
"ChemicalRecord": {"ChemicalRecordIdentifier": "12",
"ReportableQuantity": "RQ",
"ClassDivisionNumber": "3",
"SubRiskClass": "            ",
"IDNumber": "UN2621",
"PackagingGroupType": "III",
"Quantity": "10",
"UOM": "KGS",
"PackagingInstructionCode": "Y344",
"ProperShippingName": "ACETYL METHYL CARBINOL",
"TechnicalName": "            ",
"AdditionalDescription": "N",
"PackagingType": "Fiberboard Box",
"HazardLabelRequired": "LABEL IT",
"PackagingTypeQuantity": "22",
"CommodityRegulatedLevelCode": "LQ",
"TransportCategory": "3",
"TunnelRestrictionCode": "1"
}
}
}
}
}

Response samples

200
400
401
403
429

application/json

{"AcceptanceAuditPreCheckResponse": {"Response": {"ResponseStatus": {"Code": "s",
"Description": "string"
},
"Alert": [{"Code": "string",
"Description": "string"
}
],
"AlertDetail": [{"Code": "string",
"Description": "string",
"ElementLevelInformation": {"Level": "s",
"ElementIdentifier": [{"Code": null,
"Value": null
}
]
}
}
],
"TransactionReference": {"CustomerContext": "string"
}
},
"ShipperNumber": "string",
"Service": {"Code": "string"
},
"RegulationSet": "strin",
"PackageResults": [{"PackageIdentifier": "strin",
"AccessibleIndicator": "s",
"EuropeBUIndicator": "s",
"ChemicalRecordResults": [{"ChemicalRecordIdentifier": "str",
"ADRPoints": "stri",
"TransportCategory": "s",
"TunnelRestrictionCode": "string",
"ADRUnits": "strings"
}
]
}
]
}
}