Push API (DHL Global Forwarding)
v 2.4.0
Division: DHL Global Forwarding

Best for:

  • Subscribing to DHL Global Forwarding Push APIs
    • Register for Push API subscription
    • Provide your URL callback details
    • Start to receive messages pushed from DHL to your API
  • Business customers of DHL Global Forwarding
  • Air and Ocean Freight shipments
Region: Global
Used for: Shipping, Tracking
Overview

Push API allows developer to subscribe to messages/notifications from DHL Global Forwarding transport management systems. Developer can specify his/her callback URL and credentials during the registration process. Messages/notifications will be pushed to the callback URL on best effort basis.

Available Push APIs

  1. Timestamp Push API v1
    • To subscribe to notifications on availability of new shipment timestamps, for shipments booked using Shipment Booking (DHL Global Forwarding) API
       
  2. Sales Invoice Push API
    • To subscribe to Sales Invoice data once shipment invoice is posted by DHL Global Forwarding. Developer can choose to receive a notification message or choose to receive the Sales Invoice data
       
  3. Timestamp Push API v2
    • To subscribe to either Shipment Tracking or Timestamp notifications based on the filters subscribed

 

Timestamp Push API v1

Purpose

As shipment is being transported, shipment's latest location and events are constantly being recorded in order to provide up-to-date shipment visibility. Each recorded event creates a timestamp containing information about the event.

Use this API to subscribe to notifications of new timestamps for your shipments booked using Shipment Booking (DHL Global Forwarding) API. The notification is a simple JSON message containing basic information about the latest event. 

Example use case:

  1. Book a shipment using Shipment Booking (DHL Global Forwarding) API
  2. Subscribe to the Timestamp Push API v1
    • Specify your API endpoint and credentials for DHL to push the notification to 
  3. DHL will push a notification to your API endpoint whenever a new timestamp is recorded for your shipment
  4. If you need full shipment tracking details for the shipment, invoke the Shipment Tracking (DHL Global Forwarding) API
Sample Timestamp Notification Message

{
    "timestampNotification": {
        "type": "shipment",
        "shipmentID": "S2100012844",
        "housebillNumber": "Q398960",
        "timestampCode": "POD",
        "timestampDescription": "Shipment Delivered",
        "timestampDateTime": "2021-07-16T19:32:00+08:00",
        "timestampText": "John Doe",
        "notificationID": "efe7147f-f9cf-4046-9606-33ba8ed4c709",
        "shipmentTrackingURL": "https://api-sandbox.dhl.com/dgff/transportation/shipment-tracking?housebill=Q398960",
        "_DGFBookingID": "02b3b90cb0294077b37d2efc0f78c7f6"
    }
}

NEW! When shipment is delivered we now include the signatory name under $.timestampNotification.timestampText.

Below are the timestamp codes to expect from the API.

Please note that for A40/CAN event codes (Shipment Cancelled), the timestamp will only display the date without the time.

Ocean Freight Shipment

TimestampCodeTimestampDescription
A02Estimated Pick Up Date
A17Customer Booking Received
A20Booking Confirmed to Customer
A30Arrival at Origin DGF Terminal
A31CFS/CY Cut-Off Date
A37Actual Arrival at Destination CFS/CY
A39Import Customs Cleared
A40Shipment Cancelled (if applicable)
A41Consignee / Broker Notified
A60Document Handover (if no POD)
ARDActual Vessel Arrival
A29Estimated Vessel Arrival
A28Estimated Vessel Departure
A34Shipment Entered into System
A04Actual Pickup Date (customer)
A32Shipment Delivered
A42Actual Vessel Departure
A98 (In Testing)Customer Documentation Cut-Off
B15 (In Testing)Customer VGM Cut-Off

Air Freight Shipment

TimestampCodeTimestampDescription
HBEShipment Entered into System
RRTEstimated Future Pick-Up
FUTFuture Delivery Requested
RFDAppointment Requested by DGF
EODAppointment Confirmed by Customer
APTActual Pickup Time
RCDReceived at Origin
EXDAll Export Documents Received
DEWDeparted DHL Station
CACDelivered to airline
RCSReceived at airline
DOSDocument Handover (Export)
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
DLVHandover Freight to Forwarder
DIHPick-up from Airline
FPRFreight Recovered at
TBNBroker Notified
STUReady for Import Clearance
CUSImport Customs Entry
CLCImport Customs Cleared
OFDOut for Delivery
DOHImport Document Handover
DOIDocument Handover (Import)
EPDEstimated Delivery
PODShipment Delivered
CANShipment Cancelled

Prerequisite

You must have access to Shipment Booking (Global Forwarding) API in order to subscribe to Timestamp Push API v1. 

For more information on Shipment Booking (Global Forwarding) API, see https://developer.dhl.com/api-reference/dgf-shipment-booking#get-started-section/overview

Approval process

Timestamp Push API v1 is automatically approved for users of Shipment Booking (Global Forwarding) API. Please contact dgf.apisupport@dhl.com if you need any help.

Sales Invoice Push API

Purpose

Use this API to subscribe to invoice data posted to your organization account. Developer can choose to receive a notification (with link to download the Invoice data) or to receive the complete Invoice data from DHL Global Forwarding Push API. 

Example use case:

  1. Subscribe to the Sales Invoice Push API
    • Specify your API endpoint and credentials for DHL to push the notification to 
  2. Contact dgf.apisupport@dhl.com to approve your request
  3. DHL will push Invoice data to your API endpoint whenever a new invoice is posted to your organization account

Sample Invoice Notification Message

{
  "invoiceNotification" : {
    "type" : "sales-invoice",
    "invoiceNumber" : "X0000494",
    "issueDate" : "2021-04-09T14:33:00",
    "paymentDueDate" : "2021-12-09T14:33:00",
    "url" : "https://api-uat.dhl.com/dgff/finance/sales-invoice/68dc1075-b90a-47e1-94d4-28f2b1899b59"
  }
}

 

Prerequisite

You must be a valid customer of DHL Global Forwarding to subscribe to Sales Invoice Push API. 

Approval process

Please contact dgf.apisupport@dhl.com to approve your request. The team will perform the necessary verification and setup on your accounts for you to start receive Sales Invoice Push API data.

Timestamp Push API v2

Purpose

As shipment is being transported, shipment's latest location and events are constantly being recorded in order to provide up-to-date shipment visibility. Each recorded event creates a timestamp containing information about the event.

Use this API to subscribe to notifications of new timestamps for your shipments booked. The notification can be a simple JSON message containing basic information about the latest event or a detailed shipment with the latest & historical events.

Example use case:

  1. Subscribe to the Timestamp Push API v2
    • Specify your API endpoint and credentials for DHL to push the notification to 
    • Set the filters on which type of shipments you want to receive
  2. DHL will push a notification to your API endpoint whenever a new timestamp is recorded for your shipment

For sample Shipment Tracking data, please refer to DGF Shipment Tracking API page.

Sample Timestamp Push API v2 Message
{
    "timestampNotification": {
        "type": "shipment",
        "shipmentID": "S2100012844",
        "housebillNumber": "Q398960",
        "timestampCode": "POD",
        "timestampDescription": "Shipment Delivered",
        "timestampDateTime": "2021-07-16T19:32:00+08:00",
        "timestampText": "John Doe",
        "notificationID": "efe7147f-f9cf-4046-9606-33ba8ed4c709",
        "shipmentTrackingURL": "https://api-sandbox.dhl.com/dgff/transportation/shipment-tracking?housebill=Q398960"
    }
}

Note: timestampDateTime format can either be in CCYY-MM-DD'T'HH:mm:ss or CCYY-MM-DD depending on the data available on our TMS.

Below are the timestamp codes to expect from the API.

* Timestamp that are available at Container Level (applicable for ocean freight)

Please note that for A40/CAN event codes (Shipment Cancelled), the timestamp will only display the date without the time.

Ocean Freight Shipment

TimestampCodeTimestampDescription
A02*Estimated Pick Up Date
A17Customer Booking Received
A20Booking Confirmed to Customer
A30Arrival at Origin DGF Terminal
A31CFS/CY Cut-Off Date
A37Actual Arrival at Destination CFS/CY
A39Import Customs Cleared
A40Shipment Cancelled (if applicable)
A41Consignee / Broker Notified
A60Document Handover (if no POD)
ARDActual Vessel Arrival
A29Estimated Vessel Arrival
A28Estimated Vessel Departure
A04*Actual Pickup Date (customer)
A32*Shipment Delivered
A42Actual Vessel Departure
A05*Gated in at Port/Terminal
A12Actual Freight Available
A13*Gated out at Port/Terminal
A45Export Customs Cleared
A48Requested Delivery
B07Shipment Handover
EPDEstimated Delivery
A98 (In Testing)Customer Documentation Cut-Off
B15 (In Testing)Customer VGM Cut-Off

Air Freight Shipment

TimestampCodeTimestampDescription
HBEShipment Entered into System
RRTEstimated Future Pick-Up
FUTFuture Delivery Requested
RFDAppointment Requested by DGF
EODAppointment Confirmed by Customer
APTActual Pickup Time
RCDReceived at Origin
EXDAll Export Documents Received
DEWDeparted DHL Station
CACDelivered to airline
RCSReceived at airline
DOSDocument Handover (Export)
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
DLVHandover Freight to Forwarder
DIHPick-up from Airline
FPRFreight Recovered at
TBNBroker Notified
ECRExport Customs Cleared
CUSImport Customs Entry
CLCImport Customs Cleared
OFDOut for Delivery
DOHImport Document Handover
EPDEstimated Delivery
PODShipment Delivered
CANShipment Cancelled
SHOShipment Handover
EPUEstimated Pick Up Date
EDPEstimated Carrier Departure (Origin)
EAREstimated Carrier Arrival (Destination)

Prerequisite

You must be a DHL Global Forwarding customer with an existing DGF account number in order to subscribe to the Timestamp Push API v2.

Approval process

Please reach out to dgf.apisupport@dhl.com with your DHL account manager contact (email) and DHL Global Forwarding account number.

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 the + Create App button to create a new app
    The “Create App” form appears.
  3. If you wish to add the API to an existing App, click on App's "Edit" button 
  4. Fill in the form
    • Select the following from the API drop down list
      • For Sales Invoice Push API, select "DGF Push Invoice Subscription(DHL Global Forwarding) - Environment: Sandbox"
      • For Timestamp Push API v2, select "DGF Push Subscription V2 (DHL Global Forwarding) - Environment: Sandbox" to complete testing before production approval "DGF Push Subscription V2 (DHL Global Forwarding) - Environment: Production"
      • For Timestamp Push API v1, please use your shipment booking API credentials.
  5. When you have completed the form, click the Add App button or Save button
  6. Please email dgf.apisupport@dhl.com for API request approval along with your DGF account number and DGF account manager for verification purposes.

Authentication

Push API subscriptions uses oAuth 2.0 protocol to authenticate and authorize access to API consumers. For implementation details, please see Swagger specification on the "Reference Docs" tab. 

To view your API credentials :

  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 environments are:  

Environment Description
https://api-sandbox.dhl.com/dgff/push/subscription/timestamp-notification Test environment
https://api.dhl.com/dgff/push/subscription/timestamp-notification

Production environment

https://api-sandbox.dhl.com/dgff/push/subscription/invoice Test environment
https://api.dhl.com/dgff/push/subscription/invoice Production environment
https://api-sandbox.dhl.com/dgff/push/subscription/timestamp Test environment
https://api.dhl.com/dgff/push/subscription/timestamp Production environment

 

Legal Terms

Specifics for the use of Push API Data

  1. To register for the use of and access to the Push API (DHL Global Forwarding) – hereinafter “DGF Push API” – You and/or the legal entity you are authorized to represent (hereinafter “You”/”Your”) need to have an active customer account with a DHL Global Forwarding entity (hereinafter referred to as “DHL”). An API Productive Key and access details will be provided to You subject to a successful validation of Your credentials by DHL. For the avoidance of doubt, a reference to the DGF Push API in these Legal Terms is deemed a reference to the DGF Push API including the API Services (such API Services include the upload and download of documents as set forth herein and in the scope description), unless the context suggests otherwise.
  2. The DGF Push API provides the possibility to receive notifications of new timestamps (i.e. records of shipment's latest location and other transport events) for Your DHL shipments booked using the Shipment Booking API (DHL Global Forwarding). Data, which You receive via the DGF Push API shall generally be deemed Confidential Information in the meaning of section “Communication” of the General Developer Portal Terms of Use. You must not reveal and/or provide third parties with the 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.
  3. If You engage an external developer, or other IT services provider to develop Your Application or any other third party (“Third Parties”) to access and/or use the DGF Push API on Your behalf, You remain fully liable for any acts or omissions of such Third Parties in connection with the access to and/or usage of the DGF Push API.
  4. These Legal Terms and the General Developer Portal Terms of Use govern Your use of and/or access to the DGF Push API and, unless otherwise stated herein, do not replace and/or modify the applicable terms and conditions of carriage; any transportation services agreement; or any other agreements with DHL or any of its affiliates, which govern services or products provided to You (separately, each an “Agreement”). Notwithstanding the foregoing, You expressly acknowledge and agree that solely with respect to Your use of and access to the DGF Push API the Legal Terms shall take precedence over the terms and conditions in an Agreement, unless an Agreement specifically addresses the use of or access to the DGF Push API by You, in which case the Agreement shall prevail.

 

2.4.0
02.Dec.2024
  • In Testing: Added a new subscription type "tracking-notification-v2" for Push API v2. This update enables the push of shipment tracking v2 message format.
2.3.0
06.Nov.2024
  • Push API v2 updates now in Production
    • Tracking Notification:
      • New fields added under $.ShipmentTracking.Shipment.OperationalIrregularity: CreationTimestamp, ExceptionCategory and ExceptionType
      • New field added $.ShipmentTracking.MessageHeader._DGFBookingID
    • ExceptionCategory and ExceptionType Codelist
    • Subscription: New field onlyNotifyAPIBookings added
2.2.4
03.Oct.2024
  • Push API v2 updates
    • Tracking Notification: New fields added under $.ShipmentTracking.Shipment.OperationalIrregularity (In Testing): CreationTimestamp, ExceptionCategory and ExceptionType
    • Subscription: New field onlyNotifyAPIBookings added
2.2.3
23.Aug.2024
  • Push API v2 updates
    • New timestamps for Air freight: EPU, EDP, EAR. Refer to the codelist under Get Started for more details.
    • Tracking-Notification: included registered user details, and new fields sealNumber, & _DGFBookingID.
2.2.2
20.May.2024
  • Timestamp Push API v2: Tracking Notification schema added under callbacks tab.
2.2.1
17.May.2024
  • Timestamp Push API v2 transitioned out of the BETA phase.
2.2.0
11.Mar.2024
  • For timestamp push API v2, $.filters.modeOfTransport is now mandatory and changed to string instead of array.
2.1.0
15.Jan.2024
  • New serviceCode field added to the invoice-payload under Sales Invoice Push API
2.0.1
29.Jun.2023
  • BETA release of Timestamp Push API v2
2.0.0
23.May.2023
  • Initial release of Timestamp Push API v2
  • Renamed Timestamp Notification Push API to Timestamp Push API v1
1.0.2
14.Nov.2022
  • Updated the Group Type for the following fields.
    • $.billToParty.taxIDs
    • $.billingParty.taxIDs
    • $.taxSubtotals
    • $.lineItems                   
    • $.shipment.transportUnits
    • $.shipment.goodsLines
    • $.shipment.references
1.0.1
19.Sep.2022
  • Initial release of Sale Invoice Push API
  • Added the callbacks schema.
1.0.0
01.Jul.2021
  • First release
  • Added Timestamp Notification Push API