Shipment Booking (DHL Global Forwarding)
v 2.4.0
Division: DHL Global Forwarding

Best for:

  • Creating shipment and quick bookings in transport management systems 
  • Business customers of DHL Global Forwarding
  • Air, Ocean, Rail, and Road Freight shipments
Region: Global
Used for: Shipping
Overview

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.

Booking Status

Booking Status Descriptions
Accepted Booking data is validated and accepted by the API. Next status is "In-progress".
In-progress Shipment is being processing in system. Next status is "Shipment Created" or "Shipment could not be created"
Shipment Created

Shipment is created successfully. Use the housebill number to track the movement of your shipment using Shipment Tracking API.

New feature: If you are subscribed to Timestamp Notification Push API, DHL will automatically notify your API about the latest status of your shipments.

Shipment could not be created Unfortunately shipment could not be created due to data or unexpected issues. Please contact dgf.apisupport@dhl.com for support. 

 

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

    Deadline 2
Element Update Mode 1 SEA/RAI Others
$.consignee.accountNumber Manual via Note (Priority) IRP IRP
Manual via Note (Alternate)  Z42 n/a
$.notes 3 Automatic Z42 IRP
$.goodsLines Automatic Warehouse Upd Received
$.references Automatic Z42 IRP

*NOTE:

1 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

2 Deadline

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

3 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

 

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 + 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) - 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:  

    Environment Description
    https://api-sandbox.dhl.com/dgff/transportation/shipment-booking Test environment
    https://api.dhl.com/dgff/transportation/shipment-booking

    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 per minute Maximum calls per day

    Standard

    400 per minute No limit

     

    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
    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.
    2.4.0
    05.Dec.2023
    • Added externalBookingID (Live: 13.02.2024)
    • Added customsClassification under goodsLines (in testing)
    • Added shipmentBranchCode to the shipment update API (Live: 13.02.2024)
    2.3.1
    10.Nov.2023
    • Shipment Booking Update: Only consignee account number can be updated and this will reflect to the Notes section.
    2.3.0
    17.Nov.2022
    • Added productCode
    • New ProductCode codelist
    2.2.0
    09.Nov.2022
    • Added shipmentSubType
    • New shipmentSubType codelist
    2.1.0
    30.May.2022
    • Added goodsLines.originCountryCode
    2.0.3
    18.Aug.2021
    • Added innerPackageType
    • Handling of min/max temperature only if temperature control is set to true.
    • Customer group is referring to Controlling Customer - description updated
    • transportUnitID and transportUnitType under goodsLines are for future use - description updated
    2.0.1
    26.Jul.2021
    • Updated assembly description.
    • Added shipmentBranchCode field.
    • Increased the max length of serviceCode from 3 to 4.
    • Added Timestamp Notification API
    • You are automatically granted access to subscribe to Timestamp Notification Push API, DHL will automatically notify your API about the latest status of your shipments
    1.08
    08.Jan.2021
    • added _DGFInsure
    • added Delivery Transport Company (DeliveryLocalCartage) to partyType enum
    1.0.5
    09.Dec.2020
    • Added parties, goodsLine.hazardousMaterial and goodsLine.temperatures groups.
    • New PartyType, GoodsTemperatureUoM, and FlashpointTemperatureUoM codelist.
    • Added transport mode of Rail.
    1.0.4
    10.Mar.2021
    • Added TID (Template ID) to ReferenceType codelist.
    • Added assembly field for quick bookings.
    • New PartyType, GoodsTemperatureUoM, and FlashpointTemperatureUoM codelist.
    1.0.0
    10.Dec.2019
    • Initial release