Best for:
- Providing access to the latest shipment event
- Business customers of DHL Global Forwarding
- Air and Ocean Freight shipments
Freight Status API allows developer to use shipment's housebill number (DHL shipment number) to request for shipment status information. The response includes the shipment's latest timestamp, origin and destination, package count and weight.
API also allows query using customer's reference, container number or masterbill number. To do that, use GET /housebill-number to get a list of housebill numbers for a given reference, like, customer’s reference, container number or masterbill number. Use the housebill number list returned by the response to perform the next step, GET /shipment-tracking.
Please see API specification for more details.
If you wish to query the all historic events please use ShipmentTracking API.
Scope
The Shipment Status (DHL Global Forwarding) API provides access to tracking services relating to various products at DHL Global Forwarding.
Using the API
You must have an eligible housebill number (DHL shipment number) for the shipment and an API subscription key (this key needs to be either passed through a query string parameter or specified in the request header).
Get Access
You must request credentials for any applications you develop
To register your app and get your API subscription keys:
- Click My Apps on the portal website.
- Click Add Developer App.
The “Add App” form appears. - Complete the Add App form.
You can select the APIs you want to access. - When you have completed the form, click the Add App button.
The “Approved” label will appear next to the app name when the app has been approved.
Note: Additional verification steps may be required for some applications.
Authentication
Every call to the API requires a subscription key. This key needs to be either passed through a query string parameter or specified in the request header (DHL-API-Key).
To view your API subscription keys:
- From the My Apps screen, click on the name of your app.
The Details screen appears. - If you have access to more than one API, click the name of the relevant API.
Note: The APIs are listed under the “Credentials” section. - Click the Show link below the asterisks that is hiding the Consumer Key.
The Consumer Key appears.
Environments
The addressable API base URL/URI environment is:
| Environment | Description |
| https://api.dhl.com/dgff/transportation/shipment-status | Production environment |
Rate limits
Rate limits protect the DHL infrastructure from suspicious requests that exceed defined thresholds.
The table below details the main request limits:
| Service Level | Maximum calls |
|---|---|
| Starter | 50 per day |
| Standard | 2500 per day |
| Internal | 5000 per day |
Please contact dgf.apisupport@dhl.com if you need higher throughput.
When the limit is reached, you will receive an HTTP Status code:
HTTP/1.1 429 Too Many Requests
Additional Information
Permitted HTTP methods
- GET for retrieving data
Message Definition
| Elements | Data Type | Length (min..max) | Cardinality (min..max) | Description | Code List | ||||||||
| ShipmentStatus | GROUP | 1..1 | Root Element | ||||||||||
| MessageHeader | GROUP | 1..1 | Attributes describing the message | ||||||||||
| Version | String | 1..1 | Version of the Schema e.g. 1.0 | ||||||||||
| SenderID | String | 0..1 | Included for possible future use | ||||||||||
| ReceiverID | String | 0..1 | Included for possible future use | ||||||||||
| MessageID | String | 1..1 | Unique ID | ||||||||||
| CreationDateTime | DateTime | 1..1 | Creation DateTime | ||||||||||
| Shipment | GROUP | 1..1 | Shipment Details | ||||||||||
| HousebillNumber | String | 1..35 | 1..1 | Housebill Number | |||||||||
| HouseFileNumber | String | 1..35 | 0..1 | Internal Number | |||||||||
| Origin | GROUP | 1..1 | Origin Details | ||||||||||
| LocationCode | String | 3..5 | 1..1 | 3-character Location Code | |||||||||
| LocationName | String | 1..35 | 0..1 | Location Name | |||||||||
| CountryCode | String | 2 | 0..1 | ISO 2-character country code | |||||||||
| Destination | GROUP | 1..1 | Destination Details | ||||||||||
| LocationCode | String | 3..5 | 1..1 | 3-character Location Code | |||||||||
| LocationName | String | 1..35 | 0..1 | Location Name | |||||||||
| CountryCode | String | 2 | 1..1 | ISO 2-character country code | |||||||||
| ProductType | String | 1..10 | 1..1 | Product Type | ProductType | ||||||||
| TotalPackages | Integer | 1..1 | Total number of packages | ||||||||||
| TotalWeight | Decimal | 1..1 | Total Shipment weight (in kilograms) | ||||||||||
| @uom | String | 1..3 | 1..1 | Total Shipment weight uom Default to KGM |
|||||||||
| TotalVolume | Decimal | 1..1 | Total Shipment volume (in cubic meters) | ||||||||||
| @uom | String | 1..3 | 1..1 | Total Shipment volume uom Default to MTQ |
|||||||||
| Timestamp | GROUP | 1..1 | Current Status of shipment | ||||||||||
| TimestampCode | String | 0..1 | Status Code | EventAirCode EventOceanCode EventDomesticCode |
|||||||||
| TimestampDescription | String | 1..1 | Current Status textual description | ||||||||||
| TimestampDateTime | DateTime | 1..1 | Current Status Date Time | ||||||||||
Code List
| Code | Description |
|---|---|
| HBE | Shipment Entered Into System |
| APT | Actual Pickup Time |
| RCD | Received at Origin |
| DEW | Departed DHL Station |
| DEP | Carrier: Departed |
| EAA | Carrier: Arrived (1st Transit Point) |
| EAB | Carrier: Departed (1st Transit Point) |
| EAC | Carrier: Arrived (2nd Transit Point) |
| EAD | Carrier: Departed (2nd Transit Point) |
| ARR | Carrier: Arrived |
| ARV | Arrived Final Destination |
| FPR | Freight Recovered at |
| TBN | Broker Notified |
| CUS | Customs Entry |
| CLC | Import Customs Cleared |
| OFD | Out for Delivery |
| DOS | Document Handover |
| EPD | Estimated Delivery |
| POD | Shipment Delivered |
| CAN | Shipment Cancelled |
| Code | Description |
|---|---|
| TBD | TBD |
| Code | Description |
|---|---|
| A17 | Customer Booking Received |
| A34 | Shipment Entered into System |
| A31 | CFS/CY Cut-Off Date |
| A20 | Booking Confirmed to Customer |
| A28 | Estimated Vessel Departure |
| A29 | Estimated Vessel Arrival |
| A04 | Actual Pickup Date (customer) |
| A30 | Arrival at Origin DGF Terminal |
| A05 | Gated in at Port/Terminal |
| A42 | Actual Vessel Departure |
| A41 | Consignee / Broker Notified |
| A11 | Actual Vessel Arrival (ATA) |
| A62 | Sent to Import Customs |
| A39 | Import Customs Cleared |
| A13 | Gated Out at Port/Terminal |
| A12 | Actual Freight Available |
| A60 | Document Handover (if no POD) |
| A48 | Estimated Delivery |
| A32 | Proof of Delivery |
| A40 | Shipment Cancelled (if applicable) |
| Code | Description |
|---|---|
| AIR | Air freight |
| OCEAN | Ocean freight |
| USDOMESTIC | US Domestic freight |
specifics for the use of STATUS Data
- Status data is provided to You and/or the entity you are authorized to represent (hereinafter “You”/”Your”) via this SHIPMENT STATUS (DHL GLOBAL FORWARDING) API under the prerequisite, that You retrieved the according housebill number (DHL shipment number) in compliance with the applicable law, especially in the field of data protection and competition law and that You use the housebill number (DHL shipment number) and/or status data solely for Your own legitimate tracking purposes.
- You may only submit status data to the recipient of DHL Global Forwarding shipment and no other person; such submission shall always been in compliance with applicable laws in the field of data protection and competition law, which includes that the data shall not be combined with advertisement or presented in a way that it could be regarded as advertisement.
- If You are neither the sender nor the recipient of DHL Global Forwarding-shipment/s, the status data refers to,
- You shall ensure, that you are authorized to act on behalf of the sender
- You shall make the sender aware of the restrictions set out in this User Guide just as the General Developer Portal Terms of Use
- You shall make the sender aware of the necessity to inform the recipient transparently about the processing of his/her personal data according to applicable data protection laws.
- In no case shall you reveal and/or provide third parties with the housebill number (DHL shipment number) and/or status data and/or analyze, modify such data in any form and/or derive data/information especially for competitive reasons from it without our prior written consent.
- Status data shall be used in accordance with the following specification:
- Display “Delivered by Deutsche Post DHL Group“ in text (minimum font size) as soon as it is presented/submitted to recipient
- You shall delete the housebill number (DHL shipment number) and status data which You received via the SHIPMENT STATUS (DHL GLOBAL FORWARDING) API 30 days after the delivery (of the shipment) to the recipient is completed.
1.0
- Initial release