Shipment Booking API allows developer to book Air Freight and Ocean Freight shipments in various DHL Global Forwarding transport management systems.

The API accepts the following shipment information:

• Parties
• Origin
• Destination
• Goods Lines & Packages
• Notes & References

The API returns a unique DGF Booking ID which you can use to check on the status of the booking. We recommend to check the status of the booking at 5 minutes interval. Once shipment is created, you will receive additional information about the shipment e.g. Housebill Number and Shipment ID.

NEW FEATURE!

Once you have access to the Shipment Booking API, you can use the same credentials to subscribe to and enable the Timestamp Notification Push API v1. This API will automatically send notifications about the status of your shipments to your designated API endpoint, helping you keep track of the shipments you created using the Shipment Booking API.

For more information on the Timestamp Push API v1, please visit: https://developer.dhl.com/api-reference/dgf-push-api#get-started-section/timestamp-push-api-v1

Shipment Booking Update

Developers are also able to update their shipment booking with DHL Global Forwarding. Business rule validation applies.

The table below details the timeframe on when a shipment booking update is allowed:(e.g. Updating Notes of a sea shipment, Z42 timestamp should not be populated.)

*NOTE:

¹ Update Mode

• Automatic = Data from the API is automatically updated into the TMS
• Manual via Note = Data from API is sent as a note, which serves as the Operator's guide for manually applying updates in the TMS
• For SEA/RAI, alternate mapping of the Consignee Account via Note will take effect if IRP is populated and Z42 is not populated

² Deadline

• IRP = Arrival at Origin Terminal
• Z42 = Shipping Instructions sent to Carrier
• WHS Upd Received= Pack Updates Received from Warehouse

³ Notes

• Notes Type is unique and can only be used once within the message.

Scope

The API provides access to create shipment bookings in various transport management systems at DHL Global Forwarding. 

Using the API

You must have an eligible shipper / consignee account number (DHL Global Forwarding accounts) and a valid oAuth2 access token to use the API.

Once access to the API is requested, please send us an email at dgf.apisupport@dhl.com describing your use case and tell us the name/email address of your DHL contact person. We will verify your identity before granting the access.

For additional information, please contact dgf.apisupport@dhl.com

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 + Add App button to create a new app
   The “Add 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 "Shipment Booking (DHL Global Forwarding)" from the API drop down list
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

Authentication

Shipment Booking API 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:  

Rate limits

Rate limits protect the DHL infrastructure from suspicious requests that exceed defined thresholds.

The table below details the main request limits:

Please contact dgf.apisupport@dhl.com if you need a different service level. 

When the limit is reached, you will receive an HTTP Status code: 

429: Too many requests.  

Specifics for the use of Shipment Booking (DHL Global Forwarding) API

• The Shipment Booking (DHL Global Forwarding) API enables the creation of shipment bookings with the corresponding DHL Global Forwarding (“DGF”) entity. For the purposes of these Legal Terms, “you”/”your” or “registrant/user” means the (natural) person or entity holding a (transportation) contract with a DGF entity and having a DGF customer ID. If you engage an external developer or other IT services provider to represent you and to develop Your Application according to the General Developer Portal Terms of Use and these special API terms & conditions (also referred to as “Legal Terms”), you are liable for the acts or omissions of such third party in connection with the usage of the Shipment Booking (DHL Global Forwarding) API and the API Services.
• By registering for the use of and/or using the Shipment Booking (DHL Global Forwarding) API including the service that is integrated via this API, i.e. the booking of shipments with various TMS’s (the “API Service”), each registrant and/or user of the Shipment Booking (DHL Global Forwarding) API in addition to the General Developer Portal Terms of Use agree to these Legal Terms and all the terms included herein. Should the terms of the General Developer Portal Terms of Use and these Legal Terms conflict, these Legal Terms shall govern.
• These Legal Terms and the General Developer Portal Terms of Use govern your usage of Shipment Booking (DHL Global Forwarding) API including the API Service and, unless otherwise stated herein, do not replace and/or modify any other DGF terms and conditions, DGF transportation services agreements and/or any other agreements, contracts or SOWs with a specific DGF entity 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 Shipment Booking (DHL Global Forwarding) API including the API Service these Legal Terms and the General Developer Portal Terms of Use shall have preference over the terms and conditions in an Agreement, unless any terms and conditions in an Agreement specifically address the use of the Shipment Booking (DHL Global Forwarding) API or the API Service by you, in which case the specific terms and conditions of the Agreement shall prevail with respect to Your use of the Shipment Booking (DHL Global Forwarding) API/the API Service.
• The API Productive Key for the Shipment Booking (DHL Global Forwarding) API is a private and individual key for you and your DGF customer account only, i.e. it shall not be used by or for other DGF (transportation) customers. You may not allow your developer or IT services provider to use your API Productive Key for potential other DGF (transportation) customers. 
• For the avoidance of doubt, when data has been sent or received outside of DGF’s business hours, the processing of data and/or execution of the (transportation) services will start according to the terms and conditions set out in the applicable Agreement or, absent thereof, as soon as reasonably practicable. Unless otherwise expressly agreed upon in writing (e.g. in the Agreement), the transmission of a set of data via the Shipment Booking (DHL Global Forwarding) API by you shall be deemed a proposal to enter into an individual (transportation or other) contract and has to be acknowledged/accepted by the receiving DGF entity before a contract with regards to e.g. the transport is effected. The parties expressly waive any rights to contest the validity of an individual (transportation or other) contract effected by the use of the Shipment Booking (DHL Global Forwarding) API in accordance with these API Legal Terms on the sole ground that it was effected via API. DGF may determine which of the offered data fields need to be filled by you, to use the Shipment Booking (DHL Global Forwarding) API properly. You are responsible for the correctness and completeness of the data provided. DGF reserve the right to transform, adapt and/or amend data provided by you to process such data accordingly. It is in your responsibility to review and check the booking confirmation received by DGF in order to make sure that the data  provided by you (e.g. number of containers) has been adopted correctly.
• Neither DGF nor any other affiliate within DP DHL, is responsible for storing a record of any data (API-call or -request data or the actual contents of the data sets), that has been exchanged via the Shipment Booking (DHL Global Forwarding) API, unless expressly agreed upon in writing (e.g. in the Agreement).
• You shall use the services and/or data that you receive via the Shipment Booking (DHL Global Forwarding) API only for the legitimate business purposes, only in connection with DGF’s transportation and/or other services, and in compliance with all applicable laws and regulations, including but not limited to, laws regarding the use of personal data.
• Please note, that we provide free text boxes (e.g. for customer references) to improve the functionalities and user experience of the Shipment Booking (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. 
• You acknowledge that material and information you may acquire, including (but not limited to) transportation methods, booking information, financial or other accounting information and other procedures and processes relating to the Shipment Booking (DHL Global Forwarding) API and the API Service (“Materials”) are proprietary, confidential, and owned by DGF. Other than described herein, you shall have no additional rights to the Materials.
• For the purposes of the use of the Shipment Booking (DHL Global Forwarding) API and the API Service, these Legal Terms and the General Developer Portal Terms of Use are governed by the law and jurisdiction defined in the Agreement. Should no law or jurisdiction be defined in the Agreement or otherwise, these Legal Terms shall be governed according to the law and jurisdiction of the principal place of business of the according DGF entity/division providing the transportation services.