DHL Express API (MyDHL API)

Complete reference guide for integrating with DHL Express MyDHL REST API. Covers shipment creation, tracking, rate calculation, and pickup services.

Overview

REST API — DHL Express uses a modern JSON-based REST API, unlike the SOAP-based Aramex API.

Aspect	Details
API Type	REST (JSON)
Version	3.1.1
Authentication	HTTP Basic Auth
Production URL	`https://express.api.dhl.com/mydhlapi`
Test URL	`https://express.api.dhl.com/mydhlapi/test`

Available Services

Service	Endpoints	Description
Rating	`/rates`, `/landed-cost`	Get shipping rates and duty/tax calculations
Shipment	`/shipments`	Create shipments with labels
Pickup	`/pickups`	Schedule, update, cancel pickups
Tracking	`/tracking`	Track shipments by AWB
Address	`/address-validate`	Validate pickup/delivery capabilities
Products	`/products`	Get available DHL Express products

Authentication

DHL Express API uses HTTP Basic Authentication with your API credentials.

Request Headers

Authorization: Basic base64(apiKey:apiSecret)
Content-Type: application/json

Required Credentials

Credential	Description
`apiKey`	Your DHL API key
`apiSecret`	Your DHL API secret
`accountNumber`	Your DHL shipper account number

Common Data Types

PostalAddress

Field	Type	Required	Description
`addressLine1`	string	Yes	Street address line 1
`addressLine2`	string	No	Street address line 2
`cityName`	string	Yes	City name
`postalCode`	string	Yes	Postal/ZIP code
`countryCode`	string	Yes	ISO 2-letter country code
`provinceCode`	string	No	State/province code

ContactInformation

Field	Type	Required	Description
`fullName`	string	Yes	Contact person full name
`companyName`	string	No	Company name
`phone`	string	Yes	Phone number
`email`	string	No	Email address

Package

Field	Type	Description
`weight`	number	Package weight (kg or lb)
`dimensions.length`	number	Length (cm or in)
`dimensions.width`	number	Width (cm or in)
`dimensions.height`	number	Height (cm or in)
`typeCode`	string	"BOX", "DOCUMENT", "PALLET", "ENVELOPE"

Account

Field	Type	Description
`typeCode`	string	"shipper", "payer", "receiver", "duties-taxes"
`number`	string	DHL account number

1. Rating API

Base Path: /rates and /landed-cost

GET/rates

Get shipping rates for a single piece shipment.

Query Parameters

Parameter	Type	Required	Description
`accountNumber`	string	Yes	DHL account number
`originCountryCode`	string	Yes	Origin country (ISO 2-letter)
`originPostalCode`	string	Yes	Origin postal code
`originCityName`	string	Yes	Origin city name
`destinationCountryCode`	string	Yes	Destination country
`destinationPostalCode`	string	Yes	Destination postal code
`destinationCityName`	string	Yes	Destination city name
`weight`	number	Yes	Package weight
`length`	number	Yes	Package length
`width`	number	Yes	Package width
`height`	number	Yes	Package height
`plannedShippingDate`	string	Yes	YYYY-MM-DD format
`isCustomsDeclarable`	boolean	Yes	Requires customs declaration
`unitOfMeasurement`	string	Yes	"metric" or "imperial"

Response: Product Object

Field	Type	Description
`productName`	string	Product display name
`productCode`	string	DHL product code (P, D, Y, etc.)
`totalPrice`	array	Price breakdown by currency type
`deliveryCapabilities`	object	Estimated delivery date and transit days

POST/rates

Get shipping rates for multi-piece shipments.

Request Body

Field	Type	Required	Description
`customerDetails.shipperDetails`	RateAddress	Yes	Shipper address
`customerDetails.receiverDetails`	RateAddress	Yes	Receiver address
`plannedShippingDateAndTime`	string	Yes	ISO 8601 datetime
`unitOfMeasurement`	string	Yes	"metric" or "imperial"
`isCustomsDeclarable`	boolean	Yes	Requires customs
`packages`	Package[]	Yes	Array of packages
`accounts`	Account[]	Yes	Billing accounts

POST/landed-cost

Calculate duty, tax, and total shipping charges (landed cost).

Similar to POST /rates, with additional fields for customs value and commodity details. Returns shipping charges, import duties, import taxes, and total landed cost.

2. Shipment API

Endpoint: POST /shipments

POST/shipments

Create a DHL Express shipment and get labels.

Request Body

Field	Type	Required	Description
`plannedShippingDateAndTime`	string	Yes	ISO 8601 datetime
`pickup`	object	Yes	Pickup configuration
`productCode`	string	Yes	DHL product code
`accounts`	Account[]	Yes	Billing accounts
`customerDetails.shipperDetails`	Party	Yes	Shipper info
`customerDetails.receiverDetails`	Party	Yes	Receiver info
`content`	object	Yes	Package/customs details
`outputImageProperties`	object	No	Label format options

Content Object

Field	Type	Required	Description
`packages`	Package[]	Yes	Package details
`isCustomsDeclarable`	boolean	Yes	Requires customs
`description`	string	Yes	Contents description
`incoterm`	string	No	"DAP", "DDP", "DDU", "EXW", "FCA"
`unitOfMeasurement`	string	Yes	"metric" or "imperial"
`exportDeclaration`	object	No	Customs details

Output Image Properties

Field	Description
`encodingFormat`	"pdf", "png", "zpl", "epl"
`imageOptions.typeCode`	"waybillDoc", "label", "invoice", "receipt", "qr-code"

Response

Field	Type	Description
`shipmentTrackingNumber`	string	Master AWB number
`trackingUrl`	string	DHL tracking URL
`dispatchConfirmationNumber`	string	Pickup confirmation
`packages`	array	Package tracking numbers
`documents`	array	Labels/documents (base64)

Product Codes

Code	Name	Type
`P`	EXPRESS WORLDWIDE	International
`D`	EXPRESS WORLDWIDE (Non-Doc)	International
`Y`	EXPRESS 12:00	International
`T`	EXPRESS 12:00 (Non-Doc)	International
`K`	EXPRESS 9:00	International
`W`	ECONOMY SELECT	International
`X`	EXPRESS ENVELOPE	International
`N`	DOMESTIC EXPRESS	Domestic
`1`	DOMESTIC EXPRESS 12:00	Domestic

3. Pickup API

Endpoint: /pickups

POST/pickups

Create a pickup request.

Request Body

Field	Type	Required	Description
`plannedPickupDateAndTime`	string	Yes	Pickup date/time
`closeTime`	string	Yes	Location closing time
`location`	string	No	Pickup location description
`locationType`	string	No	"business" or "residence"
`accounts`	Account[]	Yes	Account details
`customerDetails.shipperDetails`	Party	Yes	Shipper info
`shipmentDetails`	array	Yes	Shipment summary

Response

Field	Type	Description
`dispatchConfirmationNumbers`	string[]	Pickup confirmation IDs
`readyByTime`	string	Pickup ready time

Update & Cancel Pickup

PATCH/pickups/{dispatchConfirmationNumber}

Update an existing pickup request. Request body same as POST /pickups.

DELETE/pickups/{dispatchConfirmationNumber}

Cancel a pickup request.

Query Parameter	Required	Description
`requestorName`	Yes	Name of person canceling
`reason`	Yes	Cancellation reason

4. Tracking API

Endpoints: /tracking and /shipments/{id}/tracking

GET/shipments/{shipmentTrackingNumber}/tracking

Track a single shipment by AWB number.

Query Parameters

Parameter	Description
`trackingView`	"shipment-details-only", "all-checkpoints", "last-checkpoint"
`levelOfDetail`	"shipment" or "piece"

Tracking Event Type Codes

Code	Description
`PU`	Picked up
`PL`	Processed at facility
`AF`	Arrived at DHL facility
`DF`	Departed DHL facility
`AR`	Arrived at destination
`WC`	With delivery courier
`OK`	Delivered
`CC`	Customs clearance

5. Address Validation

GET/address-validate

Validate DHL pickup/delivery capabilities at an address.

Query Parameters

Parameter	Required	Description
`type`	Yes	"pickup" or "delivery"
`countryCode`	Yes	ISO 2-letter country code
`postalCode`	Yes	Postal code
`cityName`	No	City name

6. Products API

GET/products

Get available DHL Express products for a route. Query parameters same as GET /rates.

Response includes product availability, delivery capabilities, and pickup cutoff times.

Error Handling

Error Response Format

{
  "instance": "/expressapi/shipments",
  "detail": "Error description",
  "title": "Error title",
  "message": "Error message",
  "status": "400"
}

HTTP Status Codes

Status	Description
`200`	Success
`201`	Created (shipment, pickup)
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid credentials
`404`	Not Found - Resource not found
`422`	Unprocessable Entity - Validation error
`500`	Internal Server Error

Environments

Environment	Base URL
Production	`https://express.api.dhl.com/mydhlapi`
Test/Sandbox	`https://express.api.dhl.com/mydhlapi/test`

Test Tracking Numbers

For testing the tracking API, use these sample waybill numbers: 9356579890, 4818240420, 5584773180, 5786694550, 2449648740