Try out UPS APIs with example requests using Postman and learn more about the UPS Postman Collection by visiting our Postman Guide. Explore API documentation and sample applications through GitHub.
servers:
- url: https://wwwcie.ups.com/api
description: Customer Integration Environment
- url: https://onlinetools.ups.com/api
description: Production
paths:
"/dangerousgoods/{version}/prenotification":
post:
summary: Pre-Notification
tags:
- Pre-Notification
security:
- OAuth2: []
description: The Pre-Notification API allows customer applications to inform
UPS operations of Dangerous Goods shipments as they are processed and will
enter the UPS transportation network prior to an upload of manifest information
at the end of the day.
operationId: PreNotification
parameters:
- in: header
name: transId
schema:
type: string
description: An identifier unique to the request. Length 32
required: false
- in: header
name: transactionSrc
schema:
type: string
default: testing
description: An identifier of the client/source application that is making
the request.Length 512
required: false
- in: path
name: version
schema:
type: string
default: v2
description: |
Version of API.
Valid values:
- v2
required: true
requestBody:
description: 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".
required: true
content:
application/json:
schema:
"$ref": "#/components/schemas/PRENOTIFICATIONRequestWrapper"
examples:
json:
summary: A sample JSON request (Standard Example)
value:
PreNotificationRequest:
Request:
RequestOption: RequestOption
SubVersion: '3'
TransactionReference:
CustomerContext: ''
Shipment:
ShipperNumber: ''
ShipmentIdentificationNumber: 1Z2398YY81288
ShipFromAddress:
AddressLine: MY STREET 12
City: BOGOTA
StateProvinceCode: NJ
PostalCode: K1A0B1
CountryCode: CA
ShipToAddress:
AddressLine: MY STREET 12
City: BOGOTA
StateProvinceCode: NJ
PostalCode: K1A0B1
CountryCode: CA
PickupDate: '20171101'
Service:
Code: GND
Description: Ground
RegulationSet: TDG
Package:
TrackingNumber: 1Z33445567001
PackageWeight:
UnitOfMeasurement:
Code: KGS
Description: Kilo
Weight: '12'
TransportationMode: GND
VoidIndicator: ''
PackagePoints: '12'
ChemicalRecord:
ReportableQuantity: '1'
ClassDivisionNumber: I
SubRiskClass: '1234'
IDNumber: UN2761
PackagingGroupType: '0'
Quantity: '1'
UOM: LBS
PackagingInstructionCode: TEST
EmergencyPhone: ''
EmergencyContact: ''
ProperShippingName: TEST SHIPPING
TechnicalName: ''
AdditionalDescription: ''
PackagingType: ''
HazardLabelRequired: LABEL
PackagingTypeQuantity: '1'
CommodityRegulatedLevelCode: LR
TransportCategory: '0'
TunnelRestrictionCode: '1'
QValue: '0.1'
OverPackedIndicator: ''
AllPackedInOneIndicator: ''
responses:
'200':
description: successful operation
content:
application/json:
schema:
"$ref": "#/components/schemas/PRENOTIFICATIONResponseWrapper"
'400':
description: Invalid Request
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorResponse"
'401':
description: Unauthorized Request
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorResponse"
'403':
description: Blocked Merchant
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorResponse"
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/dangerousgoods/{deprecatedVersion}/prenotification":
post:
deprecated: true
summary: Pre-Notification
tags:
- Pre-Notification
security:
- OAuth2: []
description: The Pre-Notification API allows customer applications to inform
UPS operations of Dangerous Goods shipments as they are processed and will
enter the UPS transportation network prior to an upload of manifest information
at the end of the day.
operationId: Deprecated PreNotification
parameters:
- in: header
name: transId
schema:
type: string
description: An identifier unique to the request. Length 32
required: false
- in: header
name: transactionSrc
schema:
type: string
default: testing
description: An identifier of the client/source application that is making
the request.Length 512
required: false
- in: path
name: deprecatedVersion
schema:
type: string
default: v1
description: |
Version of API.
Valid values:
- v1
required: true
requestBody:
description: 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".
required: true
content:
application/json:
schema:
"$ref": "#/components/schemas/PRENOTIFICATIONRequestWrapper"
examples:
json:
summary: A sample JSON request (Standard Example)
value:
PreNotificationRequest:
Request:
RequestOption: RequestOption
SubVersion: '3'
TransactionReference:
CustomerContext: ''
Shipment:
ShipperNumber: ''
ShipmentIdentificationNumber: 1Z2398YY81288
ShipFromAddress:
AddressLine: MY STREET 12
City: BOGOTA
StateProvinceCode: NJ
PostalCode: K1A0B1
CountryCode: CA
ShipToAddress:
AddressLine: MY STREET 12
City: BOGOTA
StateProvinceCode: NJ
PostalCode: K1A0B1
CountryCode: CA
PickupDate: '20171101'
Service:
Code: GND
Description: Ground
RegulationSet: TDG
Package:
TrackingNumber: 1Z33445567001
PackageWeight:
UnitOfMeasurement:
Code: KGS
Description: Kilo
Weight: '12'
TransportationMode: GND
VoidIndicator: ''
PackagePoints: '12'
ChemicalRecord:
ReportableQuantity: '1'
ClassDivisionNumber: I
SubRiskClass: '1234'
IDNumber: UN2761
PackagingGroupType: '0'
Quantity: '1'
UOM: LBS
PackagingInstructionCode: TEST
EmergencyPhone: ''
EmergencyContact: ''
ProperShippingName: TEST SHIPPING
TechnicalName: ''
AdditionalDescription: ''
PackagingType: ''
HazardLabelRequired: LABEL
PackagingTypeQuantity: '1'
CommodityRegulatedLevelCode: LR
TransportCategory: '0'
TunnelRestrictionCode: '1'
QValue: '0.1'
OverPackedIndicator: ''
AllPackedInOneIndicator: ''
responses:
'200':
description: successful operation
content:
application/json:
schema:
"$ref": "#/components/schemas/PRENOTIFICATIONResponseWrapper"
'400':
description: Invalid Request
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorResponse"
'401':
description: Unauthorized Request
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorResponse"
'403':
description: Blocked Merchant
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorResponse"
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorResponse"
components:
securitySchemes:
OAuth2:
type: oauth2
description: |
Find your Client ID and Secret on your app info page.
1. Select \"Try It\"
2. In the Security section enter your Client ID and Secret.
3. Select \"Request Token\"
4. Enter any additional information in the Body and Parameters sections.
5. Select \"Send\" to execute your API request
flows:
clientCredentials:
x-tokenEndpointAuthMethod: client_secret_basic
tokenUrl: https://wwwcie.ups.com/security/v1/oauth/token
scopes: {}
schemas:
PRENOTIFICATIONRequestWrapper:
xml:
name: PreNotificationRequest
description: 'N/A '
maximum: 1
type: object
required:
- PreNotificationRequest
properties:
PreNotificationRequest:
"$ref": "#/components/schemas/PreNotificationRequest"
PRENOTIFICATIONResponseWrapper:
xml:
name: PreNotificationResponse
description: 'N/A '
maximum: 1
type: object
required:
- PreNotificationResponse
properties:
PreNotificationResponse:
"$ref": "#/components/schemas/PreNotificationResponse"
PreNotificationRequest:
type: object
required:
- Request
- Shipment
properties:
Request:
"$ref": "#/components/schemas/PreNotificationRequest_Request"
Shipment:
"$ref": "#/components/schemas/PreNotificationRequest_Shipment"
xml:
name: PreNotificationRequest
description: Pre-Notification Request.
maximum: 1
PreNotificationRequest_Request:
type: object
properties:
TransactionReference:
"$ref": "#/components/schemas/Request_TransactionReference"
xml:
name: Request
description: Request Container
maximum: 1
Request_TransactionReference:
type: object
maximum: 1
properties:
CustomerContext:
description: The CustomerContext information which will be echoed during
response.
maximum: 1
type: string
minLength: 1
maxLength: 512
xml:
name: TransactionReference
description: TransactionReference identifies transactions between client and
server.
PreNotificationRequest_Shipment:
type: object
maximum: 1
required:
- ShipToAddress
- ShipFromAddress
- Service
- ShipperNumber
- RegulationSet
- Package
- ShipmentIdentificationNumber
- PickupDate
properties:
ShipperNumber:
description: Shipper's six digit account number.
maximum: 1
type: string
minLength: 6
maxLength: 6
ShipmentIdentificationNumber:
description: 1Z Number of the first package in the shipment.
maximum: 1
type: string
minLength: 18
maxLength: 18
ShipToAddress:
"$ref": "#/components/schemas/Shipment_ShipToAddress"
ShipFromAddress:
"$ref": "#/components/schemas/Shipment_ShipFromAddress"
PickupDate:
description: Date of the On Call Air Pickup. Format is YYYYMMDD
maximum: 1
type: string
minLength: 8
maxLength: 8
Service:
"$ref": "#/components/schemas/Shipment_Service"
RegulationSet:
description: |
The Regulatory set associated with every regulated shipment. It must be same across the shipment. Valid values are:
- ADR – European Agreement concerning the International Carriage of Dangerous Goods by Road.
- 49CFR – Title 49 of the United States Code of Federal Regulations.
- IATA – International Air Transport Association (IATA) Dangerous Goods Regulations.
maximum: 1
type: string
minLength: 3
maxLength: 5
Package:
type: array
maximum: 1000
items:
"$ref": "#/components/schemas/Shipment_Package"
xml:
name: Shipment
description: Shipment Container
Shipment_ShipToAddress:
type: object
maximum: 1
required:
- AddressLine
- CountryCode
properties:
AddressLine:
description: The Ship To street address including name and number (when
applicable).
type: array
maximum: 4
minLength: 1
maxLength: 35
items:
type: string
City:
description: The Ship To city.
maximum: 1
type: string
minLength: 1
maxLength: 30
StateProvinceCode:
description: |
The Ship To location's state or province code. Required for US, Canada, and Vietnam (VN).
- For US or Canada, the value must be a valid US state or Canadian province code.
- For Vietnam (VN), the value must be a valid province code (for example, VN-44).
- If the country or territory is Ireland, the StateProvinceCode must contain the county.
maximum: 1
type: string
minLength: 2
maxLength: 5
PostalCode:
description: The Ship To location's postal code. 9 characters are accepted.
maximum: 1
type: string
minLength: 1
maxLength: 9
CountryCode:
description: The Ship To location's country or territory code.
maximum: 1
type: string
minLength: 2
maxLength: 2
xml:
name: ShipToAddress
description: Ship To address container.
Shipment_ShipFromAddress:
type: object
maximum: 1
required:
- AddressLine
- CountryCode
properties:
AddressLine:
description: The Ship From street address including name and number (when
applicable).
type: array
maximum: 4
minLength: 1
maxLength: 35
items:
type: string
City:
description: The Ship From city.
maximum: 1
type: string
minLength: 1
maxLength: 30
StateProvinceCode:
description: |
The Ship From location's state or province code. Required for US, Canada, and Vietnam (VN).
- For US or Canada, the value must be a valid US state or Canadian province code.
- For Vietnam (VN), the value must be a valid province code (for example, VN-44).
- If the country or territory is Ireland, the StateProvinceCode must contain the county.
maximum: 1
type: string
minLength: 2
maxLength: 5
PostalCode:
description: The Ship From location's postal code. 9 characters are accepted.
maximum: 1
type: string
minLength: 1
maxLength: 9
CountryCode:
description: The Ship From location's country or territory code.
maximum: 1
type: string
minLength: 2
maxLength: 2
xml:
name: ShipFromAddress
description: Ship From address container.
Shipment_Service:
type: object
maximum: 1
required:
- Code
properties:
Code:
description: UPS service type code.
maximum: 1
type: string
minLength: 3
maxLength: 3
Description:
description: Description of the service code. Examples are Next Day Air,
Worldwide Express, and Ground.
maximum: 1
type: string
minLength: 1
maxLength: 35
xml:
name: Service
description: UPS service type.
Shipment_Package:
type: object
maximum: 1
required:
- ChemicalRecord
- TrackingNumber
- PackageWeight
properties:
TrackingNumber:
description: The packages tracking number.
maximum: 1
type: string
minLength: 18
maxLength: 18
PackageWeight:
"$ref": "#/components/schemas/Package_PackageWeight"
TransportationMode:
description: 'Declares that a package was prepared according to ground,
passenger aircraft, or cargo aircraft only. Only required when the CommodityRegulatedLevelCode
is FR or LQ. Valid entries include: GND, CAO, PAX.'
maximum: 1
type: string
minLength: 3
maxLength: 3
VoidIndicator:
description: Indicator to specify that a Dangerous Goods package is voided.
True if VoidIndicator tag exists; false otherwise.
maximum: 1
type: string
PackagePoints:
description: Regulated Commodity Transport Package Score Quantity
maximum: 1
type: string
minLength: 5
maxLength: 5
ChemicalRecord:
type: array
maximum: 3
items:
"$ref": "#/components/schemas/Package_ChemicalRecord"
xml:
name: Package
description: Package Information container.
Package_PackageWeight:
type: object
required:
- UnitOfMeasurement
- Weight
properties:
UnitOfMeasurement:
"$ref": "#/components/schemas/PackageWeight_UnitOfMeasurement"
Weight:
description: Packages weight.
maximum: 1
type: string
minLength: 15
maxLength: 15
xml:
name: PackageWeight
maximum: 1
description: Container to hold package weight information.
PackageWeight_UnitOfMeasurement:
type: object
maximum: 1
required:
- Code
properties:
Code:
description: "Package weight unit of measurement code. \nCodes are: \nLBS
= Pounds\nKGS = Kilograms"
maximum: 1
type: string
minLength: 3
maxLength: 3
Description:
description: Description of the unit of measurement for package weight.
maximum: 1
type: string
minLength: 1
maxLength: 35
xml:
name: UnitOfMeasurement
description: Container to hold UnitOfMeasurement information for package weight.
Package_ChemicalRecord:
type: object
maximum: 1
properties:
ReportableQuantity:
description: Indicates whether or not a material being transported meets the definition of a hazardous material and meets or exceeds a reportable quantity threshold. If reportable quantity is met, "RQ" should be entered. Any other value will be interpreted as "Non Reportable" quantity.
maximum: 1
type: string
minLength: 1
maxLength: 2
ClassDivisionNumber:
description: This is the hazard class associated to the specified commodity. Required if CommodityRegulatedLevelCode is 'LQ' or 'FR'
maximum: 1
type: string
minLength: 1
maxLength: 7
SubRiskClass:
description: Secondary hazardous characteristics of a package. (There can be more than one – separate each with a comma.)
maximum: 1
type: string
minLength: 7
maxLength: 7
IDNumber:
description: 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).
maximum: 1
type: string
minLength: 1
maxLength: 6
PackagingGroupType:
description: |
This is the packing group category associated to the specified commodity. Must be shown in Roman Numerals. Valid values are:
- I
- II
- III
- blank
maximum: 1
type: string
minLength: 1
maxLength: 5
Quantity:
description: Required if CommodityRegulatedLevelCode = LQ or FR. The numerical value of the mass capacity of the regulated good.
maximum: 1
type: string
minLength: 1
maxLength: 5
UOM:
description: Required if CommodityRegulatedLevelCode = LQ or FR. The unit of measure used for the mass capacity of the regulated good.
maximum: 1
type: string
minLength: 1
maxLength: 10
PackagingInstructionCode:
description: The packing instructions related to the chemical record.
maximum: 1
type: string
minLength: 1
maxLength: 4
EmergencyPhone:
description: |
24 Hour Emergency Phone Number of the shipper.
Valid values for this field are (0) through (9) with trailing blanks.
For numbers within the U.S., the layout is 1, area code, 7-digit number. For all other countries the layout is country code, area code, number. The following are restricted in the phone number
period ".", dash "-", plus sign "+" and conventional parentheses "(" and ")", "EXT" or "OPT" The following are restricted in the phone number
period ".", dash "-", plus sign "+" and conventional parentheses "(" and ")", "EXT" or "OPT"
maximum: 1
type: string
minLength: 1
maxLength: 25
EmergencyContact:
description: The emergency information, contact name and/or contract number, required to be communicated when a call is placed to the EmergencyPhoneNumber.
maximum: 1
type: string
minLength: 1
maxLength: 35
ProperShippingName:
description: The Proper Shipping Name assigned by ADR, CFR or IATA. Required if CommodityRegulatedLevelCode = LQ or FR.
maximum: 1
type: string
minLength: 1
maxLength: 150
TechnicalName:
description: The technical name (when required) for the specified commodity.
maximum: 1
type: string
minLength: 200
maxLength: 200
AdditionalDescription:
description: Additional remarks or special provision information.
maximum: 1
type: string
minLength: 1
maxLength: 255
PackagingType:
description: "The type of package used to contain the regulated good. (Ex: Fiberboard Box)."
maximum: 1
type: string
minLength: 1
maxLength: 255
HazardLabelRequired:
description: Defines the type of label that is required on the package for the commodity.
maximum: 1
type: string
minLength: 50
maxLength: 50
PackagingTypeQuantity:
description: The number of pieces of the specific commodity. Required if CommodityRegulatedLevelCode = LQ or FR. Valid values are 1 to 999.
maximum: 1
type: string
minLength: 1
maxLength: 3
CommodityRegulatedLevelCode:
description: Indicates the type of commodity, Fully Regulated (FR), Limited Quantity (LQ), Lightly Regulated (LR) Valid values are LR, FR and LQ.
maximum: 1
type: string
minLength: 2
maxLength: 2
TransportCategory:
description: Transport Category. Valid values are 0 to 4.
maximum: 1
type: string
minLength: 1
maxLength: 1
TunnelRestrictionCode:
description: Defines what is restricted to pass through a tunnel.
maximum: 1
type: string
minLength: 1
maxLength: 10
QValue:
description: 'When a HazMat shipment specifies AllPackedInOneIndicator and
the regulation set for that shipment is IATA, Q-Value specifies exactly
one of the following values: 0.1; 0.2; 0.3; 0.4; 0.5; 0.6; 0.7; 0.8; 0.9;
1.0 Valid values are : 0.1; 0.2; 0.3; 0.4; 0.5; 0.6; 0.7; 0.8; 0.9; 1.0'
maximum: 1
type: string
minLength: 3
maxLength: 3
OverPackedIndicator:
description: Presence/Absence Indicator. Any value is ignored. Presence indicates that shipment is overpack.
maximum: 1
type: string
AllPackedInOneIndicator:
description: Presence/Absence Indicator. Any value is ignored. Presence indicates if multiple, different hazmat/chemicals are contained within one box in a package
maximum: 1
type: string
xml:
name: ChemicalRecord
required:
- CommodityRegulatedLevelCode
description: Dangerous Goods Accessorial Commodity Container
PreNotificationResponse:
type: object
required:
- Response
properties:
Response:
"$ref": "#/components/schemas/PreNotificationResponse_Response"
xml:
name: PreNotificationResponse
description: Pre-Notification Response container.
maximum: 1
PreNotificationResponse_Response:
type: object
required:
- ResponseStatus
properties:
ResponseStatus:
"$ref": "#/components/schemas/Response_ResponseStatus"
Alert:
description: |
Alert Container. There can be zero to many alert containers with code and description.
**NOTE:** For versions >= v2, this element will always be returned as an array. For requests using version = v1, this element will be returned as an array if there is more than one object and a single object if there is only 1.
type: array
items:
"$ref": "#/components/schemas/Response_Alert"
TransactionReference:
"$ref": "#/components/schemas/Response_TransactionReference"
xml:
name: Response
description: Contains Pre-Notification response components.
maximum: 1
Response_ResponseStatus:
type: object
maximum: 1
required:
- Description
- Code
properties:
Code:
description: Identifies the success or failure of the transaction. Valid
values 1 = Successful.
maximum: 1
type: string
minLength: 1
maxLength: 1
Description:
description: Describes Response Status Code. Returns text of Success.
maximum: 1
type: string
minLength: 1
maxLength: 35
xml:
name: ResponseStatus
description: Response status container.
Response_Alert:
type: object
maximum: 1
required:
- Description
- Code
properties:
Code:
description: Warning code returned by the system.
maximum: 1
type: string
minLength: 1
maxLength: 10
Description:
description: Warning messages returned by the system.
maximum: 1
type: string
minLength: 1
maxLength: 150
xml:
name: Alert
description: Alert Container. There can be zero to many alert containers with
code and description.
Response_TransactionReference:
type: object
maximum: 1
properties:
CustomerContext:
description: The CustomerContext information which will be echoed during
response.
maximum: 1
type: string
minLength: 1
maxLength: 512
xml:
name: TransactionReference
description: Transaction Reference Container.
ErrorResponse:
type: object
properties:
response:
"$ref": "#/components/schemas/CommonErrorResponse"
CommonErrorResponse:
type: object
description: The error response containing any errors that occurred.
properties:
errors:
type: array
description: The error array containing any errors that occurred.
items:
"$ref": "#/components/schemas/ErrorMessage"
ErrorMessage:
type: object
properties:
code:
type: string
description: The error code.
message:
type: string
description: The error message.
description: The error response containing any errors that occurred.