Shipment Tracking (DHL Global Forwarding)
v 2.1.0
Division: DHL Global Forwarding

Best for:

  • Providing access to the shipment status at any time
  • Business customers of DHL Global Forwarding
  • Air, Ocean, Road and Rail Freight shipments
Region: Global
Used for: Tracking
Overview

Shipment Tracking API allows developer to request for shipment's information using shipment housebill number (DHL shipment number). API response includes:

  • Shipment details
  • Latest event & timestamp
  • Historical events & timestamps

There are additional fields (masterbill number, operational irregularity and etc.) that will only be visible for Registered Users. To be a Registered User, the requestor should be an existing DGF customer. During the rate limit upgrade process, we will automatically set up customers as a Registered User.

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.

Scope

The Shipment Tracking (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 HTTP request header).

Shipment Tracking (DHL Global Forwarding) - Environment: Production - Rate Limit: Starter API product is auto-approved. It is meant for users with low usage and for users to try out the API without having to wait for approval. Higher rate limit API product (Standard and Internal rate limit) requires approval from DHL team. 

 

 

User Guide

Get Access

You must request credentials for any applications you develop

To register your app and get your API subscription keys:

  1. Click My Apps on the portal website.
  2. Click + Create App.
    The “Create App” form appears.
  3. Complete the Create App form. 
    You can select the APIs you want to access. 
  4. When you have completed the form, click the Create App button. 
  5. Click on the name of the newly created App
  6. Click on the Upgrade Rate Limit button and complete the request form
    The “Approved” label will appear next to the app name when the app has been approved.
    Note: Additional verification steps may be required for increasing the Rate Limit.

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:

  1. From the My Apps screen, click on the name of your app.
    The Details screen appears. 
  2. 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. 
  3. 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-tracking 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 Approval
Starter 50 per day Auto Approved
Standard 2500 per day Verification and approval required
Internal 5000 per day Verification and approval required

 

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
Code List
DeliveryTerms
Code Description
Prepaid Prepaid shipment
Collect Collect shipment

EventAirCode

Code Description
HBE Shipment Entered into System
RRT Estimated Future Pick-Up
APT Actual Pickup Time
RCD Received at Origin
EXD All Export Documents Received
DOS Document Handover (Export)
DEW Departed DHL Station
CAC Delivered to airline
RCS Received at airline
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
DLV Handover Freight to Forwarder
DIH Pick-up from Airline
FPR Freight Recovered at
RFD Appointment Requested by DGF
EOD Appointment Confirmed by Customer
FUT Future Delivery Requested
STU Ready for Import Clearance
TBN Broker Notified
CUS Import Customs Entry
CLC Import Customs Cleared
OFD Out for Delivery
DOI Document Handover (Import)
EPD Estimated Delivery
DOH Import Document Handover
POD Shipment Delivered
SHO Shipment Handover
ECR Export Customs Cleared

EventOceanCode

Code Description
A17 Customer Booking Received
A34 Shipment Entered into System
A31 CFS/CY Cut-Off Date
A02 Estimated Pick Up Date
A04 Actual Pickup Date (customer)
A28 Estimated Vessel Departure
EDL Estimated Vessel Departure (Last Updated)
A29 Estimated Vessel Arrival
EAL Estimated Vessel Arrival (Last Updated)
A30 Arrival at Origin DGF Terminal
A42 Actual Vessel Departure
A41 Consignee / Broker Notified
ARD Actual Vessel Arrival
A39 Import Customs Cleared
A60 Document Handover (if no POD)
A32 Shipment Delivered
A20 Booking Confirmed to Customer
A48 Requested Delivery
EPD Estimated Delivery
B07 Shipment Handover
A45 Export Customs Cleared
G22 Requested Shipping
A05 Gated in at Port/Terminal
AID All Import Documents Received
A13 Gated out at Port/Terminal

EventRoadCode

Code Description
A17 Customer Booking Received
A34 Shipment Entered into System
A02 Estimated Pick Up Date
A04 Actual Pickup Date (customer)
A30 Arrival at Origin DGF Terminal
A42 Actual Vessel Departure
A41 Consignee / Broker Notified
ARD Actual Vessel Arrival
A39 Import Customs Cleared
A60 Document Handover (if no POD)
A32 Shipment Delivered
A20 Booking Confirmed to Customer
A48 Requested Delivery
B07 Shipment Handover
A45 Export Customs Cleared
G22 Requested Shipping
AID All Import Documents Received

EventRailCode

Code Description
A17 Customer Booking Received
A34 Shipment Entered into System
A31 CFS/CY Cut-Off Date
A02 Estimated Pick Up Date
A04 Actual Pickup Date (customer)
A28 Estimated Vessel Departure
EDL Estimated Vessel Departure (Last Updated)
A29 Estimated Vessel Arrival
EAL Estimated Vessel Arrival (Last Updated)
A30 Arrival at Origin DGF Terminal
A42 Actual Vessel Departure
A41 Consignee / Broker Notified
ARD Actual Vessel Arrival
A39 Import Customs Cleared
A60 Document Handover (if no POD)
A32 Shipment Delivered
A20 Booking Confirmed to Customer
A48 Requested Delivery
B07 Shipment Handover
A45 Export Customs Cleared
G22 Requested Shipping
A05 Gated in at Port/Terminal
AID All Import Documents Received
A13 Gated out at Port/Terminal
A12 Actual Freight Available
A37 Actual Arrival at Destination CFS/CY

ExpressBOLFlag

Code Description
Y Express B/L
N Standard

ProductType

Code Description
AIR Air freight
OCEAN Ocean freight
ROAD Road freight
RAIL Rail freight

 

ExceptionCategory

Code Description
CDZ CDZ, Gov, Authority, Rules & Reg
DDS DDS Related
GTW Gateway Internal Only
INF Information (Docs, Data)
PHS Physical Issues
TPT Transport Deviation

ExceptionType

Code Description
DIB 02-Brokerage Docs or Info
DIC 02-Commercial Docs or Info
DII 02-Invoice Docs or Info
DIS 02-Special Docs or Info
DIT 02-Transport Docs or Info
DLD 03-Delivery Delay
PUD 03-Pick-up Delay
DTF 04-Duties and Taxes insufficient funds
HLD 04-Refused / On Hold
CSD 05-Customs / Authorities Service Delay
CHI 05-Customs Hold / Inspection
GAH 05-Government Agency Hold / Inspection
LPA 05-Late Pre-Alert notification
PRR 05-Prohibitions, Restrictions and requisites
OTH 06-Other CDZ, GOV, Authorities Issues
MLD 07-Mainleg Delay (AFR)
VAD 07-Vessel Arrival Delay
VDD 07-Vessel Departure Delay
PRT 08-Partial or Split
MSR 10-Misrouted
MIL 11-Missing
PWS 11-Partially or wrongly stored
WEI 11-Warehouse Issue
TEM 12-Temperature Excursion
UCI 12-ULD / Container Issue
DMC 14-Damage (Major) - Rank C
DMA 20-Damage (Minor) - Rank A
DMB 21-Damage (Moderate) - Rank B
Legal Terms
specifics for the use of Tracking Data
  • Data requested and received via this Shipment Tracking (DHL Global Forwarding) API, such as transport status, estimated delivery time, including the tracking/housebill number is hereinafter referred to as “Tracking Data”.
  • Tracking Data is Confidential Information in the meaning of section “Communication” of the General Developer Portal Terms of Use. Other than set forth below You must not reveal and/or provide third parties with the Tracking Data and/or analyze, modify such data in any form and/or derive data/information especially for competitive purposes from it without our prior written consent.
  • Tracking Data is provided to You and/or the entity you are authorized to represent (hereinafter “You”/”Your”) 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 Tracking Data solely for Your own or Your customers’ legitimate tracking purposes.
  • The use and submission of Tracking Data – including submission to any of Your subcontractors – shall always be in compliance with applicable laws and regulations, including – without limitation – data protection laws and competition/antitrust law.
  • You shall not combine Tracking Data with advertisement or present it in a way that it could be regarded as advertisement.
  • Unless otherwise agreed, You shall delete the housebill number (DHL shipment number) and Tracking Data which You received via the Shipment Tracking (DHL Global Forwarding) API 30 days after the delivery (of the shipment) to the recipient is completed.
  • Tracking 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
  • Please note, that we provide free text boxes (e.g. for customer references) to improve the functionalities and user experience of the Shipment Tracking (DHL Global Forwarding) API. We explicitly ask you to refrain from sending any personal or business critical data and/or information as free text. It is within your sole responsibility to ensure that the data or information you send does not infringe upon applicable law, esp. data protection law, and that you are entitled to use the respective data and/or information accordingly.
  • If You are neither the shipper/sender nor the recipient of the DHL Global Forwarding shipment/s, the Tracking Data refers to,
    • You shall ensure, that you are authorized to act on behalf of the sender and/or the recipient;
    • You shall make the sender and/or the recipient 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;
    • You shall inform the sender and/or recipient transparently that the use of Your Application may result in the disclosure of data being subject to postal secrecy and data protection laws to third parties (including You).
2.3
03.Oct.2024
  • New fields added under $.ShipmentTracking.Shipment.OperationalIrregularity (In Testing)
    • CreationTimestamp
    • ExceptionCategory
    • ExceptionType
2.1.0
14.Jun.2024
  • New ExternalBookingID field added under $.ShipmentTracking.Shipment.ExternalBookingID
2.0.1
05.Feb.2024
  • New Ocean Freight milestones added (G22, A05, AID, A13)
2.0.0
18.Jan.2024
  • New emissions group added under $.ShipmentTracking.Shipment.Emissions (Go live on 15 February 2024)
1.9.0
17.Aug.2023
  • New Vessel Lloyds Number field is added: $.ShipmentTracking.Shipment.Routes.Route.VesselLloydsNumber
  • Actual mode of transport will now be reflected to $.ShipmentTracking.Shipment.ProductType
1.8.0
27.Apr.2023
  • Estimated Delivery Date will not show once POD event is available.
  • New LocationCodeUN field will be available for all of the timestamp events: $.ShipmentTracking.Shipment.Timestamps.Timestamp.LocationCodeUN
  • GMT offset will be available to all of the date/time fields.
  • New Chargeable Weight field is added: $.ShipmentTracking.Shipment.ChargeableWeight
  • VoyageFlightNumber will be provided for Air Freight timestamp of ARV (Arrived Final Destination): $.ShipmentTracking.Shipment.Timestamps.Timestamp.VoyageFlightNumber
  • New Shipment Handover Milestone - Timestamp Code: B07 (Ocean) and SHO (Air)
  • New Export Customs Cleared Milestone - Timestamp Code: A45 (Ocean) and ECR (Air)
1.7.0
16.Jan.2023
  • Added TimestampCode to Last Event group under $.ShipmentTracking.Shipment.LastEvent.TimestampCode. TimestampCode is only populated for timestamps offered by shipment tracking API.
1.6.0
11.Jan.2023
  • LastEvent now visible to public API users.
1.5.0
30.Nov.2022
  • Migrated the backend tracking system to a new platform.
  • New structure for TransportUnits group.
  • All location groups will now contain: LocationCode, LocationCodeUN, LocationName and CountryCode.
  • POD Signatory Name is now available under $.ShipmentTracking.Shipment.Timestamps.Timestamp.TimestampText for TimestampCode of A32 or POD.
  • Routes will now contain routing for Courier shipments.
  • Timestamps will be returned from earliest to latest
1.4.0
30.Mar.2022
  • Updated origin and destination LocationCode description.
1.3.0
22.Feb.2022
  • New structure for Masterbill and Carrier group.
  • Added Registered User fields ($.ShipmentTracking.Shipment.Masterbills.Masterbill.Carrier.StandardCarrierCode and $.ShipmentTracking.Shipment.Masterbills.Masterbill.Carrier.BookingReference)
1.2.0
09.Apr.2021
  • Rearranged fields as per schema.
  • Added Registered User fields (Masterbill group, Carrier group, OperationalIrregularity group, Incoterms, TransportUnitType, Phase, LastEvent group, Status)
  • Added descriptions, examples and min/max length to the fields.
1.1.0
24.May.2019
  • Added "/housebill-numbers" resource for developers to get a list of housebill numbers using customer reference, container number or masterbill number as query parameter. The result (list of housebill numbers) can be used to query the "/shipment-tracking" resource.

This allows developers to search for shipment-tracking resources using customer reference, container number or masterbill number as search criteria.

1.0.0
26.Feb.2019
  • Initial Release