Introduction

This document is a developer’s guide and provides the necessary information to integrate your websites and mobile apps with our DHL API. Our API endpoints are implemented as RESTful web services so they can be easily integrated on any programming platform.

Basic prior knowledge on JSON, HTTPS and an understanding of software programming is assumed.

A quick overview on all endpoints of the DHL API can be found in our documentation gateway: https://api-gw.dhlparcel.nl/docs/

In this document some of our most important API endpoints are discussed, giving their business context and some examples on how to use specific features provided by the endpoints. The documentation present at the previous URL is generated automatically and therefore more correct over this manually created document. Please use that as the leading technical description of our API.

Please note that our APIs are continually evolving, and as such additional functionality and data may become available over time. Of course, we guarantee backwards compatibility and will never change the contents or semantics of existing fields. However, certain additional fields may appear in the returned JSON, and we expect all clients to be able to deal with this. As such, we consider added fields to be backwards-compatible changes.

The DHL shipping interfaces are there to help you to give the best possible experience to your end users. But if you think there is any information missing, incorrect or you wish to provide us with suggestions, please feel free to contact us at: CIM eCommerce BNL.

Flow

This documentation is ordered in the natural flow when using the api:

FAQ

Where can I find the meaning of a certain API endpoint input field?

In the API documentation you will see the option ‘model’ next to ‘Example Value’. When clicked on the type, a description per field is shown and if required (red asterisk).
How can I integrate Track & trace?

A shipment can be traced through the tracker code (response field in the Create label endpoint) and the receiver’s postal code.
```
curl -X GET "https://api-gw.dhlparcel.nl/track-trace?key=3SBPB0000094346%2B9999AA" -H "Accept: application/json"
```
The Track & trace service is something that DHL can provide. In your correspondence to your clients a URL can be communicated that a shipment is ready. For example, this Dutch shipment:
```
https://www.dhlparcel.nl/nl/volg-uw-zending-0?tt=<tracker code>&pc=<postal code>
```
Another way is to make use of the Track & trace endpoint.

How do I use the authentication token?

An example for the label service when posting a label could be like this in PHP :

curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Content-Type: application/json; charset=utf-8",
  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkYWFkNzU3ZC03NGY4LTQ5YzktOWI4OC1kMzEyN2 Q2ZDczMDAiLCJzdWIiOiI5MWQ5NGZiZC0xODk2LTQyMTctODlkNy0wM2M4ZTY4Y2YwYTAiLCJvcmdhbml6YXRpb 25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzczMSwiZXhw IjoxNTExODY4NjMyLCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJ hY2NvdW50cyI6WyI3NDY1NjE3MCIsIjEyMzQ1Njk4IiwiNDU5MDAxMDAiLCI0MDA0NDU4OSIsIjg3NjU0MzIxIi wiMzMzMzMzMzMiLCIwNTkyMDUxNyIsIjA4NTAwMDAxIiwiMTIzNDU2NzgiLCIwNTk1Nzg0MCJdfQ.KywXOWovoS Vf1WJ-CWAJ9j4rUXuMp-f0q2c2PKkOZno",
  "Accept: application/pdf"
]
);

Example in cURL

curl -X GET "https://api-gw.dhlparcel.nl/labels?trackerCodeFilter=JVGL08500001813590386271" -H "Accept:
application/json" -H "Authorization: Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhNzAxN2EzZi1jMGYzLTQ3ZTAtOGQzNC1mMmZhMDFjYTlkY2EiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb25JZCI6ImE0MDkzM2lLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzUwNywiZXhwIjoxNTExODY4NDA4LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.Qs79ILW0ES4mO8hObOiZXvuuipBQ_
-eJ7pd-10rrSQ"

I want to send a package to a mailbox how can I do that?

A package can be sent to a mailbox by adding the shipment option with key “BP” to the post label request.

See directions on context and syntax in 3.3.1 Create label, Adding shipment options.
I want to send a package as an express shipment (delivery before 11.00 am)?

A package for express delivery can be created by adding the shipment option key “EXP” in the post label request.

See directions on context and syntax in 3.3.1 Create label, Adding shipment options.
How do I create a shipment for a parcel shop or DHL ServicePoint?

With the Find the nearest parcel shop location the id (as input) of the DHL ServicePoint can be derived. In the request you then need to define the shipment option key ‘PS’, like:
```
{
  "key": "PS",
  "input": "8004-NL-272403"
}
```

See directions on context and syntax in 3.3.1 Create label, Adding shipment options.

How can I create a same day delivery (Shipment option key ‘SDD’)?

Same day delivery is a product that is not automatically available for all customers. If you want this enabled, please place your request at: CIM eCommerce BNL.

Same day has the shipment option key ‘SDD’ and is used like :
```
{
  "key": "SDD"
}
```
See directions on context and syntax in 3.3.1 Create label, Adding shipment options.
I want to send a shipment to a German PackStation how can I do that?

In the situation that a parcel is to be delivered at a postbox in a German PackStation, the syntax is first the id of the parcel station delimited by ‘|’ and then the recipient’s postnummer:
```
{
  "key": "PS",
  "input": "8003-4125530|12345"
}
```
See directions on context and syntax in 3.3.1 Create label, Adding shipment options.

APPENDIX

A. Shipment options

This is the current (at time of writing) list of shipment options. For up-to-date information, including a basic description, please use the Shipment options endpoint of our API.

Shipment option	Description
ADD_RETURN_LABEL	Include extra label for return shipment
BOUW	Delivery to construction site
BP	Mailbox delivery
COD_CASH	Cash on delivery. Payment method cash
COD_CHECK	Cash on delivery. Payment method check
DOOR	Delivery to the address of the recipient
EA	Extra Assurance
EVE	Evening delivery
EXP	Expresser
EXW	Ex Works. The recipient pays for the transportation from factory to destination
H	Hold for collection
HANDT	Signature on delivery
HANDTPS	Signature on delivery at parcel shop
INS	All risk insurance
LQ¹	Required for shipments with Limited Quantities
NBB	No neighbor delivery
NO_TRACK_TRACE	No track and trace for shipment
PERS_NOTE	Email to the receiver (for MDP Business app only)
PRINTLESS	Generates a printless label/return label with QR code
PS	Delivery to the specified DHL Parcelshop or DHL Parcelstation
RECAP	Additional proof of delivery
REFERENCE	Reference on label
REFERENCE2	Extra reference label
S	Saturday delivery
SSN	Undisclosed sender

¹ DHL account manager must be informed before using LQ. Weight must be specified. Additional information regarding LQ is available on page 5 of Brochure Sending Dangerous Goods