OpenAPI Specification
openapi: 3.0.3
info:
title: UPS Shipping Address Validation Tracking API
description: The UPS Shipping API enables developers to create and manage shipments, generate shipping labels, validate addresses, retrieve rates, track packages, schedule pickups, manage returns, and access time-in-transit information. UPS uses OAuth 2.0 with client credentials for authentication.
version: v1
contact:
name: UPS Developer Support
url: https://developer.ups.com/
termsOfService: https://www.ups.com/us/en/help-center/legal-terms-conditions/developer-terms-of-service.page
servers:
- url: https://onlinetools.ups.com/api
description: UPS Production API
- url: https://wwwcie.ups.com/api
description: UPS Customer Integration Environment (CIE - Testing)
security:
- BearerAuth: []
tags:
- name: Tracking
description: Package tracking and status
paths:
/track/v1/details/{inquiryNumber}:
get:
operationId: trackShipment
summary: Track Shipment
description: Retrieve real-time tracking information for a package or shipment using a UPS tracking number.
tags:
- Tracking
parameters:
- name: inquiryNumber
in: path
required: true
schema:
type: string
description: UPS tracking number (1Z...) or shipment reference number
- name: locale
in: query
schema:
type: string
default: en_US
description: Locale for response messages
- name: returnSignature
in: query
schema:
type: string
enum:
- 'true'
- 'false'
description: Include delivery signature image if available
- name: returnMilestones
in: query
schema:
type: string
enum:
- 'true'
- 'false'
description: Include delivery milestone tracking
responses:
'200':
description: Tracking details
content:
application/json:
schema:
$ref: '#/components/schemas/TrackResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: OAuth token missing or expired
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
TrackResponse:
type: object
properties:
trackResponse:
type: object
properties:
shipment:
type: array
items:
type: object
properties:
inquiryNumber:
type: string
package:
type: array
items:
type: object
properties:
trackingNumber:
type: string
currentStatus:
type: object
properties:
code:
type: string
description:
type: string
simplifiedTextDescription:
type: string
statusCode:
type: string
deliveryDate:
type: array
items:
type: object
properties:
date:
type: string
type:
type: string
activity:
type: array
items:
type: object
properties:
location:
type: object
properties:
address:
$ref: '#/components/schemas/Address'
status:
type: object
properties:
code:
type: string
description:
type: string
date:
type: string
time:
type: string
Address:
type: object
properties:
AddressLine:
type: array
items:
type: string
description: Street address lines
City:
type: string
StateProvinceCode:
type: string
description: Two-letter state/province code
PostalCode:
type: string
CountryCode:
type: string
description: Two-letter ISO country code
example: US
ResidentialAddressIndicator:
type: string
description: Presence indicates residential address
ErrorResponse:
type: object
properties:
response:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
message:
type: string
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://onlinetools.ups.com/api/security/v1/oauth/token
scopes: {}
BearerAuth:
type: http
scheme: bearer
description: OAuth 2.0 bearer token from /security/v1/oauth/token