Shipment Status (DHL Global Forwarding)
v 1.0.2
Division: DHL Global Forwarding

Best for:

  • Providing access to the latest shipment event
  • Business customers of DHL Global Forwarding
  • Air and Ocean Freight shipments
Region: Global
Used for: Tracking
Overview

ShipmentStatus 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).

Shipment Status (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. Fill in the form to complete the customer verification process.
  2. Once the form is submitted, an app will be created under My Apps.
  3. DGF Customer IT Solutions (CIS) team will contact you in case of further inquiries.
  4. Once approved/rejected, an email notification will be sent out.

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:  

EnvironmentDescription
https://api.dhl.com/dgff/transportation/shipment-statusProduction 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 LevelMaximum callsApproval
Starter50 per dayAuto Approved
Standard2500 per dayVerification and approval required
Internal5000 per dayVerification 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

 

Message Definition

 

ElementsData TypeLength (min..max)Cardinality (min..max)DescriptionCode List
ShipmentStatusGROUP 1..1Root Element 
 MessageHeaderGROUP 1..1Attributes describing the message 
 VersionString 1..1Version of the Schema e.g. 1.0 
SenderIDString 0..1Included for possible future use 
ReceiverIDString 0..1Included for possible future use 
MessageIDString 1..1Unique ID 
CreationDateTimeDateTime 1..1Creation DateTime 
ShipmentGROUP 1..1Shipment Details 
 HousebillNumber    String1..351..1Housebill Number 
HouseFileNumber    String1..350..1Internal Number 
OriginGROUP 1..1Origin Details 
 LocationCode   String3..51..13-character Location Code 
LocationName   String1..350..1Location Name 
CountryCode   String20..1ISO 2-character country code 
DestinationGROUP 1..1Destination Details 
 LocationCode   String3..51..13-character Location Code 
LocationName   String1..350..1Location Name 
CountryCode   String21..1ISO 2-character country code 
ProductType    String1..101..1Product TypeProductType
TotalPackages    Integer 1..1Total number of packages 
TotalWeight      Decimal 1..1Total Shipment weight (in kilograms) 
 @uom    String1..31..1Total Shipment weight uom

Default to KGM
 
TotalVolume      Decimal 1..1Total Shipment volume (in cubic meters) 
 @uom    String1..31..1Total Shipment volume uom

Default to MTQ
 
TimestampGROUP 1..1Current Status of shipment 
 TimestampCode   String 0..1Status CodeEventAirCode
EventOceanCode
EventDomesticCode
TimestampDescription  String 1..1Current Status textual description 
TimestampDateTime  DateTime 1..1Current Status Date Time 

Code List

EventAirCode

CodeDescription
HBEShipment Entered Into System
APTActual Pickup Time
RCDReceived at Origin
DEWDeparted DHL Station
DEPCarrier: Departed
EAACarrier: Arrived (1st Transit Point)
EABCarrier: Departed (1st Transit Point)
EACCarrier: Arrived (2nd Transit Point)
EADCarrier: Departed (2nd Transit Point)
ARRCarrier: Arrived
ARVArrived Final Destination
FPRFreight Recovered at
TBNBroker Notified
CUSCustoms Entry
CLCImport Customs Cleared
OFDOut for Delivery
DOSDocument Handover (Export)
EPDEstimated Delivery
PODShipment Delivered
RRTEstimated Future Pick-Up
EXDAll Export Documents Received
CACDelivered to airline
RCSReceived at airline
DLVHandover Freight to Forwarder
DIHPick-up from Airline
DOHImport Document Handover
RFDAppointment Requested by DGF
EODAppointment Confirmed by Customer
FUTFuture Delivery Requested
STUReady for Import Clearance
DOIDocument Handover (Import)
SHOShipment Handover
ECRExport Customs Cleared

EventDomesticCode

CodeDescription
TBDTBD

EventOceanCode

CodeDescription
A17Customer Booking Received
A34Shipment Entered into System
A31CFS/CY Cut-Off Date
A02Estimated Pick Up Date
A28Estimated Vessel Departure
EDLEstimated Vessel Departure (Last Updated)
A29Estimated Vessel Arrival
EALEstimated Vessel Arrival (Last Updated)
A20Booking Confirmed to Customer
A04Actual Pickup Date (customer)
A30Arrival at Origin DGF Terminal
A37Actual Arrival at Destination CFS/CY
A42Actual Vessel Departure
A41Consignee / Broker Notified
ARDActual Vessel Arrival
EPDEstimated Delivery
A39Import Customs Cleared
ONHArrival to CFS
B07Shipment Handover
A60Document Handover (if no POD)
A48Requested Delivery
A32Proof of Delivery
A45Export Customs Cleared

ProductType

CodeDescription
AIRAir freight
OCEANOcean freight
ROADRoad freight
RAILRail freight
Legal Terms
specifics for the use of STATUS Data
  • Data requested and received via this Shipment Status (DHL Global Forwarding) API, such as transport status, estimated delivery time, including the tracking/housebill number is hereinafter referred to as “Status Data”.
  • Status 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 Status 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.
  • Status 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 Status Data solely for Your own or Your customers’ legitimate tracking purposes.
  • The use and submission of Status 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 Status 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 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.
  • 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
  • Please note, that we provide free text boxes (e.g. for customer references) to improve the functionalities and user experience of the Shipment Status (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 Status 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).
FAQ

1. How to Register?

  • Please check the User Guide available on this page for detailed instructions.

2. Who to Contact?

  • For assistance, please engage with your DGF regional Customer IT Solutions (CIS) contact

 3. How to receive updates?

  • Click on the notification button at the top of this page.
1.0.2
30.Nov.2022
  • Migrated the backend tracking system to a new platform.
  • All location groups will now contain: LocationCode, LocationCodeUN, LocationName and CountryCode.
  • POD Signatory Name is now available under $.ShipmentStatus.Shipment.Timestamps.Timestamp.TimestampText for TimestampCode of A32 or POD.
1.0.1
18.Jun.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-status" resource.

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

1.0
26.Feb.2019
  • Initial release