Shipment Booking

 NOTE: For DGF Internal application use only. This version of API contains additional fields and code list not available in public Shipment Booking API

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 your request is approved, you are automatically granted access to Timestamp Notification Push API. The API will automatically push notifications about the status of your shipments to your API endpoint. It helps you to keep track of the shipments you created using the Shipment Booking API.

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

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:

• For SEA/RAI, alternate mapping of the Consignee Account via Note will take effect if IRP is populated and Z42 is not populated
• 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 Internal (DHL Global Forwarding) - Environment: Sandbox - Rate Limit: Standard" 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.  

Legal Terms Content. This section is required for customer facing APIs.

Simon Wirges (simon.wirges@dhl.com) is the point of contact for this matter.