Developer - DHL API Documentation

Version : 1.0
Date : 05-03-2018
Department : DHL MDP Development

DHL API Documentation v1.0 1

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 knowlegde 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 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 Parcel BNL.

DHL API Documentation v1.0 2

1 Authentication and authorization 6

1.2 Intro 7

1.3 Services 8

1.3.1 Get your user-id and key 8

1.3.2 Get your authorization token 8

1.4 Environments and testing 9

1.4.1 Example request code 9

1.4.1.1 Access token 9

1.4.1.2 Refresh token 9

1.4.2 Responses (success) code 10

1.4.3 Testing 10

2 Capabilities 11

2.1 Intro 12

2.2 Services 13

2.2.1 Capabilities 13

2.3 Environment and testing 22

2.3.1 Examples 22

2.3.2 Responses 24

2.3.3 Testing 29

3 Labels 30

3.2 Intro 31

3.3 Services 32

3.3.1 Create label 32

3.3.2 Get label id by trackingcode or order reference 38

3.3.3 Get label by id 38

3.4 Environments and testing 39

3.4.1 Examples request code 39

3.4.1.1 Create Label 39

3.4.1.2 Get Label (trackerCodeFilter) 43

3.4.1.3 Get pdf label specific shipment 43

3.4.2 Responses (success) 43

DHL API Documentation v1.0 3

 3.4.2.1 Create label 43

3.4.2.2 Get label-id 43

3.4.2.3 Get pdf label 44

3.4.3 Testing 44

4 Find parcel shop location 45

4.1 Intro 46

4.2 Services 47

4.2.1 Find the nearest parcel shop location endpoint 47

4.2.2 Get specific DHL Servicepoint 47

4.3 Environment and testing 47

5 Endpoint to get nearest parcel shops 48

6 https://api-gw.dhlparcel.nl/parcel-shop-locations/<countrycode>? 48

6.1.1 Examples 48

6.1.1.1 Nearest parcel shops 48

6.1.1.2 Specific parcel shop 48

6.1.2 Responses (success) 48

6.1.3 Testing 54

7 Track & Trace 55

7.1 Intro 56

7.2 Services 57

7.2.1 Track & Trace 57

7.2.2 Environments and testing 58

Enviroments 58

7.2.2.1 Examples - request code 58

7.2.2.2 Responses (success) 58

7.2.3 Testing 65

8 FAQ 66

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

2. How can I integrate Track & trace? 67

3. How do I use the authentication token? 67

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

DHL API Documentation v1.0 4

 5. I want to send a package as an express shipment (delivery before 11.00 am)? 68

6. How do I create a shipment for a parcel shop or DHL ServicePoint? 68

7. How can I create a same day delivery (Shipment option key 'SDD')? 69

8. I want to send a shipment to a German PackStation how can I do that? 69

9 APPENDIX 70

A. Shipment options 71

DHL API Documentation v1.0 5

1 Authentication and authorization

DHL API Documentation v1.0 6

1.2 Intro

The DHL API endpoints (but not all) make use of JWT (JSON Web Tokens) for secure
authentication and authorization. DHL secure endpoints are identified by a lock in the API docs
(see right hand side of the specific endpoint).

The JWT token is necessary to test and work in the DHL production environment when dealing
with secured endpoints. This token is to be provided in the Authorization header of the HTTP
request using the ‘Bearer’ scheme.

DHL has chosen JWT not just for authentication but also for the secure exchange of JSON
information pertaining to the user account.

Precondition

● A business account for MY DHL Parcel.

A business account is handed out by the sales department. You can place a request for an
account as a business by email to: CIM Parcel BNL

DHL API Documentation v1.0 7

1.3 Services

1.3.1 Get your user-id and key

To get an authentication token, you will need the user-id and user key for your application.
These unique values can be generated under the user account on the My DHL-Parcel Application
page.

By selecting 'Settings' in the user dropdown menu and clicking the button 'CREATE API KEY' in
the tab 'API KEYS', the user-id and key are generated. Hold on to this information, since it will
only be given out once. When pressing the button again, a new user-id and key will be
generated, overwriting and invalidating the previous one.

1.3.2 Get your authorization token

The user-id and key are used to make the initial call to the Authenticate API key endpoint. As a
reponse, the endpoint returns both an access token and a refresh token.

The access token is valid for a limited time, indicated by the expiration time in the response
attribute 'accessTokenExpiration'. When this time (expressed as a unix time stamp) has expired,
the secure access can again be established by obtaining a new access token using the refresh
token and the Authenticate refresh token endpoint. Please keep in mind that this refresh token
also has an expiration date time, but it is significantly longer than that of the access token.

The reponse of the refresh endpoint is the same as the initial call to the Authenticate API key
endpoint; it also results in an access and a refresh token with expiration date times.

Example of response body (200) of the /api-key:

"accessToken":
"yJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIwOGZkMTRhMC05YWYzLTRkZDMtODU3YS1hNzUyYW
Y3ZjUyYTciLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb
25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMDMyNDMxNSwiZXhw

DHL API Documentation v1.0 8

IjoxNTEwMzI1MjE2LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJ
hY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.D9Zf0hnDXhPXoWar42wzSiZHRKLBYriyKQyj1zERrBw",
"accessTokenExpiration": 1510325216,
"refreshToken":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhMWQ5MDMyMi04YmRiLTQ1NjQtOTMxMy04OTg5N
ThmMzgwNDQiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRp
b25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMDMyNDMxNSwiZXh
wIjoxNTEwOTI5MTE2LCJyb2xlcyI6WyJhdXRoLXNlcnZpY2UuUkVGUkVTSCJdLCJhY2NvdW50cyI6WyIwODUwMD
AwMSJdfQ.fi7hn6u3mFwcJ4AG8cYEh8OJFm2NDwOt407aP7sENSo",
"refreshTokenExpiration": 1510929116
}

The red highlighted text is the access token to be used in the HTTP header for authentication
and the blue highlighted text is the unix time stamp for the expiration of the token (in this case,
2017-11-10 14:46:56Z).

1.4 Environments and testing

Description URL

API to get your tokens https://api-gw.dhlparcel.nl/authenticate/api-key

API to be used with the https://api-gw.dhlparcel.nl/authenticate/refresh-token

refresh token

1.4.1 Example request code

cURL

1.4.1.1 Access token

curl -X POST "https://api-gw.dhlparcel.nl/authenticate/api-key" -H "accept:
application/json" -H "content-type: application/json" -d "{ \"userId\": \"f36abdfa-9894-
4d1f-bb6e-e471a953c04d \", \"key\": \"1c8545e1-767f-4531-9c6b-5f5f80737562 \"}

1.4.1.2 Refresh token

curl -X POST "https://api-gw.dhlparcel.nl/authenticate/refresh-token" -H "accept:
application/json" -H "content-type: application/json" -d "{ \"refreshToken\":
\"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIwMWVlYjBkMy1hZmM0LTRiYjEtYTgzZS0wZDkx
YzE4ZjVhZDUiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXR
pb25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMDIxMDcxNSwiZX
hwIjoxNTEwODE1NTE2LCJyb2xlcyI6WyJhdXRoLXNlcnZpY2UuUkVGUkVTSCJdLCJhY2NvdW50cyI6WyIwODUwM
DAwMSJdfQ.y-Hm3T6_moUWXF_v2uyOXcX7tu1uddyhG6fsDQliPXw\"}

DHL API Documentation v1.0 9

PHP
<?php
$auth_string = '{"userId":"{userID}","key":"{key}"}';
$ch = curl_init('https://api-gw.dhlparcel.nl/authenticate/api-key');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $auth_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','Accept:
application/json'));
$auth_response = curl_exec($ch);
$api_key = json_decode($auth_response);
$accessToken = $api_key->{'accessToken'};
?>

1.4.2 Responses (success) code

Response 200:

{ "accessToken": "_Your API key_"

"accessTokenExpiration": 1510138597,
"refreshToken": "_Your refresh API key _"
"refreshTokenExpiration": 1510742497 }

1.4.3 Testing
These test cases with their positive outcomes are merely suggestions and it is not an extensive
test set, e.g. tests with a negative outcome should also be taken into scope. Please extend with
test cases which are suitable for your line of business or wishes.

Suggested Test Cases Expected Result

Create an authorization An access token and a refresh token with expiration are
token (initial request) returned by the My DHLParcel application.

Create an new authorization An access token and a refresh token with expiration are
with refreh token returned by the My DHLParcel application.

DHL API Documentation v1.0 10

2 Capabilities

DHL API Documentation v1.0 11

2.1 Intro

The Capabilities endpoint lists the available shipment options (and their exclusions) given a
certain country, parcel type and whether the recipient of the parcel is a business or a consumer.

The purpose of the endpoint is twofold: it offers all available options to choose from for a given
situation, and can then validate the interdependency of all variables for a shipment, serving as a
validation tool for your shipment request.

By situation you should think of what is possible in terms of the kind of shipment, if it is a
business-to-business or business-to-consumer shipment, does your account allow you to create
return shipments or a same day delivery.

The Create label endpoint makes use of the capabilities endpoint, thereby checking the validity
of a shipment the same way..

Preconditions

No preconditions are applicable.

DHL API Documentation v1.0 12

2.2 Services

2.2.1 Capabilities
In order to get the correct capabilities for your shipment, in addition to the sender type
(mandatory), at least the top three fields in the table below should be given in order to get the
applicable set of options for a specific shipment. Without these parameters, the request will
result in a too broad dataset to be useful for a single shipment.

In certain cases, it is better to not supply the ‘parcelType’ and ‘shipmentOptions` fields. The
input fields work like a filter, returning only valid product combinations; when provided with an
impossible combination of options, the endpoint will not return an error message, but simply
return an empty list.

For example, when Saturday delivery (‘S’) is present and toBusiness is set to true, the call will
be successful, but the response will not contain possible shipment options. In fact that means
that there are none, since these options are incompatible with each other.

Parcel types can be cross-referenced through the Parcel type endpoint. This is useful since
available parcel types can differ per country. The same applies for the Shipments options
endpoint, where options differ per origin/destination country pair.

Field Description

fromCountry Country code of origin

toCountry Country code of destination

Does it concern a delivery to a business? True
toBusiness or false
Check Parcel type API. A parcel type is
available or valid depending on the
'senderType' and the values of 'toBusiness'
parcelType and 'fromCountry'. SeeAd 1.
Check Shipment options API. Depending on
the values of 'senderType', 'parcelType',
'fromCountry' and 'toBusiness' options are
available. Some options are excluded based on
shipment options the chosen option(s). SeeAd 2.

As a result of a 'successful' call the API will return all possible parcel types, shipment options
with its exclusions.

DHL API Documentation v1.0 13

 Ad 1. For example parcel Type "PALLET" is known in the Netherlands, but not in Spain. In
order to get the right parcel types from the sender's point of view (country code), the
Parcel type endpoint should be used.

This is just one example why the input needs to be cross-referenced with the Parcel types (or
with the Shipment options) endpoint. As already mentioned, the input in itself will not be
validated through the Capabilities endpoint. Providing non-existent or incompatible options will
just yield an empty list.

[
{
"key": "SMALL",
"minWeightKg": 0,
"maxWeightKg": 5,
"dimensions": {
"maxLengthCm": 25,
"maxWidthCm": 20,
"maxHeightCm": 5
}
},
{
"key": "MEDIUM",
"minWeightKg": 5,
"maxWeightKg": 15,
"dimensions": {
"maxLengthCm": 60,
"maxWidthCm": 50,
"maxHeightCm": 25
},
{
"key": "LARGE",
"minWeightKg": 16,
"maxWeightKg": 31,
"dimensions": {
"maxLengthCm": 120,
"maxWidthCm": 60,
"maxHeightCm": 60
}
},
{
"key": "BULKY",
"minWeightKg": 0,
"maxWeightKg": 31,
"dimensions": {
"maxLengthCm": 200,
"maxWidthCm": 120,
"maxHeightCm": 80
}
}
]

DHL API Documentation v1.0 14

 Ad 2. The option "PS", meaning delivery to a DHL Servicepoint, and the option "DOOR",
delivery at the door, of course do not go together. If chosen together in the Capabilities
endpoint the response code is 200, but the result will be an empty array.

In the snippet of the Shipment options endpoint below you can see that "DOOR" is listed as an
exclusion to the shipment option "PS", indicating their incompatibility.

{
"key": "PS",
"description": "Delivery to the specified DHL Parcelshop or DHL Parcelstation",
"rank": 1,
"code": 21,
"inputType": "text",
"exclusions": [
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "S",
"rank": 11,
"code": 15
},
{
"key": "NBB",
"rank": 14,
"code": 36
},
{
"key": "HANDT",
"rank": 12,
"code": 56
},
{
"key": "DOOR",
"rank": 2,
"code": 0
},
{
"key": "COD_CASH",
"rank": 17,
"code": 0,
"inputType": "number"
},
{
"key": "COD_CHECK",
"rank": 18,
"code": 0,
"inputType": "number"
},
{
"key": "EXP",
"rank": 15,
"code": 1
},
{

DHL API Documentation v1.0 15

 "key": "H",
"rank": 4,
"code": 21
},
{
"key": "BOUW",
"rank": 19,
"code": 0
},
{
"key": "EXW",
"rank": 20,
"code": 0
},
{
"key": "SSN",
"rank": 16,
"code": 0,
"inputType": "address"
},
{
"key": "RECAP",
"rank": 21,
"code": 0,
"inputType": "text"
},
{
"key": "BP",
"rank": 3,
"code": 91
},
{
"key": "SDD",
"rank": 7,
"code": 6
},
{
"key": "NO_TT",
"rank": 22,
"code": 0
}
]
}

If, for example, a “SMALL” parcel type is chosen and the delivery of the parcel is to a business
(toBusiness = true) and the chosen option is “PS”, again the response will be successful, but
there is no result.

It might be better then not to have shipment option(s) and or parcel types as input. The
endpoint will then return all parcel types and options available based on the base input
(toBusiness, fromCountry and toCountry).

DHL API Documentation v1.0 16

 Then, in your application, show a list of returned options the end-user can choose from and
validate each option against its exclusions.

If no shipment option is entered as input for the endpoint, like in the last example (toBusiness =
true, fromCountry=NL and toCountry=NL) , the shipment option "PS" will only show up in the
result of certain parcel types.

[
{
"rank": 2,
"fromCountryCode": "NL",
"toCountryCode": "NL",
"product": {
"key": "EPL",
"label": "EUROPLUS",
"code": "04",
"menuCode": "01",
"businessProduct": true,
"monoColloProduct": false,
"softwareCharacteristic": "B2X",
"returnProduct": false
},
"parcelType": {
"key": "SMALL",
"minWeightKg": 0,
"maxWeightKg": 20,
"dimensions": {
"maxLengthCm": 80,
"maxWidthCm": 50,
"maxHeightCm": 35
}
},
"options": [
{
"key": "DOOR",
"description": "Delivery to the address of the recipient",
"rank": 2,
"code": 0,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "BP",
"rank": 3,
"code": 91
},
{
"key": "NO_TT",
"rank": 22,
"code": 0
}
]
},

DHL API Documentation v1.0 17

 {
"key": "H",
"description": "Hold for collection",
"rank": 4,
"code": 21,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "EXP",
"rank": 15,
"code": 1
},
{
"key": "BOUW",
"rank": 19,
"code": 0
},
{
"key": "BP",
"rank": 3,
"code": 91
},
{
"key": "DOOR",
"rank": 2,
"code": 0
}
]
},
{
"key": "REFERENCE",
"description": "Reference",
"rank": 5,
"code": 0,
"inputType": "text",
"inputMax": "15"
},
{
"key": "PERS_NOTE",
"description": "E-mail to receiver",
"rank": 6,
"code": 0,
"inputType": "text"
},

DHL API Documentation v1.0 18

 {
"key": "ADD_RETURN_LABEL",
"description": "Print extra label for return shipment",
"rank": 8,
"code": 0
},
{
"key": "INS",
"description": "All risks insurance",
"rank": 10,
"code": 0,
"inputType": "number"
},
{
"key": "S",
"description": "Saturday delivery",
"rank": 11,
"code": 15,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "EXP",
"rank": 15,
"code": 1
},
{
"key": "BP",
"rank": 3,
"code": 91
}
]
},
{
"key": "EXP",
"description": "Expresser",
"rank": 15,
"code": 1,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},

DHL API Documentation v1.0 19

 {
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "S",
"rank": 11,
"code": 15
},
{
"key": "H",
"rank": 4,
"code": 21
},
{
"key": "BP",
"rank": 3,
"code": 91
}
]
},
{
"key": "SSN",
"description": "Undisclosed sender",
"rank": 16,
"code": 0,
"inputType": "address",
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "BP",
"rank": 3,
"code": 91
}
]
},
{
"key": "COD_CASH",
"description": "Cash on delivery. Payment method cash.",
"rank": 17,
"code": 0,
"inputType": "number",
"exclusions": [

DHL API Documentation v1.0 20

 {
"key": "COD_CHECK",
"rank": 18,
"code": 0,
"inputType": "number"
},
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "BP",
"rank": 3,
"code": 91
}
]
},
{
"key": "BOUW",
"description": "Delivery to construction site",
"rank": 19,
"code": 0,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "H",
"rank": 4,
"code": 21
},
{
"key": "BP",
"rank": 3,

DHL API Documentation v1.0 21

 "code": 91
}
]
},
{
"key": "EXW",
"description": "Ex Works",
"rank": 20,
"code": 0,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "BP",
"rank": 3,
"code": 91
}
]
},
{
"key": "REFERENCE2",
"description": "Reference",
"rank": 22,
"code": 0,
"inputType": "text",
"inputMax": "70"
}
]
}
]

2.3 Environment and testing

Description Production
https://api-
Capabilities gw.dhlparcel.nl/capabilities/business?

2.3.1 Examples

cURL

DHL API Documentation v1.0 22

curl -X GET "https://api-
gw.dhlparcel.nl/capabilities/business?fromCountry=NL&toCountry=NL&toBusiness=false&parc
elType=SMALL&option=PS" -H "accept: application/json"

PHP - WordPress

<?php

// {@see https://codex.wordpress.org/HTTP_API}
$response = wp_remote_get( 'https://api-
gw.dhlparcel.nl/capabilities/business?fromCountry=NL&toCountry=NL&toBusiness=false&parc
elType=SMALL&option=PS', array(
'headers' => array(
'Accept' => 'application/json',
),
) );

if ( ! is_wp_error( $response ) ) {
// The request went through successfully, check the response code against
// what we're expecting
if ( 200 == wp_remote_retrieve_response_code( $response ) ) {
// Do something with the response
// $body = wp_remote_retrieve_body( $response );
// $headers = wp_remote_retrieve_headers( $response );
} else {
// The response code was not what we were expecting, record the message
$error_message = wp_remote_retrieve_response_message( $response );
}
} else {
// There was an error making the request
$error_message = $response->get_error_message();
}

PHP cURL - WordPress

<?php

// Get cURL resource

$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://api-
gw.dhlparcel.nl/capabilities/business?fromCountry=NL&toCountry=NL&toBusiness=false&parc
elType=SMALL&option=PS');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Accept: application/json",
]
);

DHL API Documentation v1.0 23

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources

curl_close($ch);

2.3.2 Responses

Response 200:

[
{
"rank": 2,
"fromCountryCode": "NL",
"toCountryCode": "NL",
"product": {
"key": "EPL",
"label": "EUROPLUS",
"code": "04",
"menuCode": "01",
"businessProduct": true,
"monoColloProduct": false,
"softwareCharacteristic": "B2X",
"returnProduct": false
},
"parcelType": {
"key": "PALLET",
"minWeightKg": 50,
"maxWeightKg": 1000,
"dimensions": {
"maxLengthCm": 240,
"maxWidthCm": 100,
"maxHeightCm": 200
}
},
"options": [
{
"key": "DOOR",
"description": "Delivery to the address of the recipient",
"rank": 2,
"code": 0,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{

DHL API Documentation v1.0 24

 "key": "BP",
"rank": 3,
"code": 91
},
{
"key": "NO_TT",
"rank": 22,
"code": 0
}
]
},
{
"key": "H",
"description": "Hold for collection",
"rank": 4,
"code": 21,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "EXP",
"rank": 15,
"code": 1
},
{
"key": "BOUW",
"rank": 19,
"code": 0
},
{
"key": "BP",
"rank": 3,
"code": 91
},
{
"key": "DOOR",
"rank": 2,
"code": 0
}
]
},
{
"key": "REFERENCE",
"description": "Reference",
"rank": 5,

DHL API Documentation v1.0 25

 "code": 0,
"inputType": "text",
"inputMax": "15"
},
{
"key": "PERS_NOTE",
"description": "E-mail to receiver",
"rank": 6,
"code": 0,
"inputType": "text"
},
{
"key": "ADD_RETURN_LABEL",
"description": "Print extra label for return shipment",
"rank": 8,
"code": 0
},
{
"key": "INS",
"description": "All risks insurance",
"rank": 10,
"code": 0,
"inputType": "number"
},
{
"key": "EXP",
"description": "Expresser",
"rank": 15,
"code": 1,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "S",
"rank": 11,
"code": 15
},
{
"key": "H",
"rank": 4,
"code": 21
},
{
"key": "BP",
"rank": 3,

DHL API Documentation v1.0 26

 "code": 91
}
]
},
{
"key": "SSN",
"description": "Undisclosed sender",
"rank": 16,
"code": 0,
"inputType": "address",
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "BP",
"rank": 3,
"code": 91
}
]
},
{
"key": "COD_CASH",
"description": "Cash on delivery. Payment method cash.",
"rank": 17,
"code": 0,
"inputType": "number",
"exclusions": [
{
"key": "COD_CHECK",
"rank": 18,
"code": 0,
"inputType": "number"
},
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{

DHL API Documentation v1.0 27

 "key": "EA",
"rank": 9,
"code": 58
},
{
"key": "BP",
"rank": 3,
"code": 91
}
]
},
{
"key": "BOUW",
"description": "Delivery to construction site",
"rank": 19,
"code": 0,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",
"rank": 13,
"code": 14
},
{
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "H",
"rank": 4,
"code": 21
},
{
"key": "BP",
"rank": 3,
"code": 91
}
]
},
{
"key": "EXW",
"description": "Ex Works",
"rank": 20,
"code": 0,
"exclusions": [
{
"key": "PS",
"rank": 1,
"code": 21,
"inputType": "text"
},
{
"key": "EVE",

DHL API Documentation v1.0 28

 "rank": 13,
"code": 14
},
{
"key": "EA",
"rank": 9,
"code": 58
},
{
"key": "BP",
"rank": 3,
"code": 91
}
]
},
{
"key": "REFERENCE2",
"description": "Reference",
"rank": 22,
"code": 0,
"inputType": "text",
"inputMax": "70"
}
]
}
]

2.3.3 Testing
These test cases with positive outcomes are merely suggestions and it is not an extensive test set, e.g.
tests with a negative outcome should also be taken into scope. Please extend with test cases which are
suitable for your line of business or wishes.

Suggested Test Cases Expected Result

Check capabilities business to business Parcel type(s) with options are returned for a
business based on the input of being a business,
country code and shipment option(s) and or on a
specific parcel type.
Check capabilities business to consumer Parcel type(s) with options are returned for a
consumer based on the input of being a consumer,
country code and shipment option(s) and or on a
specific parcel type.

DHL API Documentation v1.0 29

3 Labels

DHL API Documentation v1.0 30

3.2 Intro

The Labels endpoints make it possible to create and retrieve your own labels.

The endpoints of Label are secured, therefore the use of an authorization header with 'Bearer' as
prefix and your token is required.

Preconditions

● Business account for the test environment and or on MY DHL Parcel.

A business account is handed out by the sales department. You can place a request for an
account as a business by email to: CIM Parcel BNL

● Authentication token. See documentation on the Authentication and authorization endpoint.

DHL API Documentation v1.0 31

3.3 Services

3.3.1 Create label

The Create label endpoint constructs one label at a time, which can be either a standard label or
a return label.

In order to create a label, a unique identifier is needed as input for the label request. The format
for this identifier is the Universally Unique Identifier (UUID). The use of UUIDs keeps our API
idempotent. It ensures in this case that a label is created uniquely and just once, without
needing to do any expensive and complicated synchronized bookkeeping.

Most programming languages and platforms have a built-in UUID generator that you can use for
this purpose.A brief explanation on the other input data is given in the table below.

Be aware that the use of an authorization token in the header of the HTTP request is mandatory.

Field Type Mandatory Description

labelId string Y Use a UUID Generator

Determines label binary representation
included in the JSON response. Defaults to
labelFormat string Y ‘pdf’.
Your own reference for the label(s), e.g.
orderReference string N your order number.

parcelTypeKey string Y See ParcelTypes endpoint in API docs

receiver Y Name and address

name

firstName string N

lastName string N

companyName string N

additionalName string N
Depending on country, use designated
address endpoint to check input address

countryCode string Y
Format is checked based on country
postalCode string N Code

city string N

street string N

number string N

DHL API Documentation v1.0 32

isBusiness boolean Y Receiver consumer is false

addition string N

email string N

phoneNumber string N

onBehalfOf N Name and address. See Ad 1.

name

firstName string

lastName string

companyName string

additionalName string
Depending on country, use designated
address endpoint for address

countryCode string
Format is checked based on country
postalCode string code

city string N

street string N

number string N

isBusiness boolean Y Receiver consumer is false

addition string N

email string N

phoneNumber string N

shipper Y Name and address

name

firstName string N

lastName string N

companyName string N

additionalName string N
Depending on country, use designated
address endpoint to check input address

countryCode string Y
Format is checked based on country
postalCode string N code

city string N

DHL API Documentation v1.0 33

street string N

number string N

isBusiness boolean Y Default (as business) true

addition string N

email string N

phoneNumber string N

accountId string Y

options array
See Capabilities endpoint in API docs
key string Y and Ad 2.

returnLabel boolean Y See Ad 3.

pieceNumber integer Y See Ad 4.

quantity integer Y
If true, PDF labels wil include a flag that
opens the print dialog in supported software
automaticPrintDialogboolean N (Acrobat reader).

Ad 1. An 'on behalf of' shipment

For destinations offering the ‘SSN’ shipment option (e.g. Benelux) it is possible to do a shipment
on behalf of someone else. This is done by an extra information block called 'onBehalfOf'. It has
the same structure as the 'shipper' block.

"onBehalfOf": {
"name": {
"firstName": "Mr",
"lastName": "Onbehalfof",
"companyName": "DHL Parcel",
"additionalName": "Benelux"
},
"address": {
"countryCode": "NL",
"postalCode": "3542AD",
"city": "Onbehalf",
"street": "Onbehalfweg",
"number": "2",
"isBusiness": false
},
"email": "[email protected]",
"phoneNumber": "0031612345678"
}

DHL API Documentation v1.0 34

In addition to the onBehalfOn block the shipping option undisclosed sender (SSN) is required:

{
"key": "SSN"
}

It is possible to do an onBehalfOf shipment outside the Benelux, but the original sender will not
be anonymous in the Track & Trace info (DHL).

In the case of an onBehalfOf shipment outside the Benelux it also necessary to use the
onBehalfOf json block, but the shipping option undisclosed sender should be left out of the
request.

Ad 2. Adding shipment options

Some shipments options require specifying extra information. For example, in the case of a cash
on delivery, the amount should be specified or in case of a reference, some text is needed as
input.

Whether additional information is necessary for the shipping option is determined by the 'input
type' listed with the shipment option (See Shipment Options or Capabilities endpoint).

For example shipment option 'REFERENCE' will be returned like:

{
"key": "REFERENCE",
"description": "Reference",
"rank": 5,
"code": 0,
"inputType": "text",
"inputMax": "15"
}

When the extra information is required the field "input" can be used to specify this.

For example in the case of a delivery to a parcel shop, the parcel shop is identified by it's id
through the input field.

{
"key": "PS",
"input": "8004-NL-272403"
}

In the situation that a parcel is to be delivered at a postbox of German PackStation, the syntax
is first the id of the parcel station delimited by ‘|’ and then the postummer of the recipient:

DHL API Documentation v1.0 35

{
"key": "PS",
"input": "8003-4125530|12345"
}

In case of cash on delivery, the amount that needs to be paid by the recipient serves as input.

{
"key": "COD_CASH",
"input": 5
}
Ad 3. Create return label

A label is either a 'normal', so an initial label or a return label. By setting the value of the
‘returnLabel’ attribute to ‘true’, the endpoint will create a return label; a return label is marked
as a RETURN label. Note that there must be a return product available (a setting for your
account) .

When creating a return label, make sure the receiver and shipper information are set correctly.
If a customer returns a package, the customer's address becomes the shipper's address and the
company's address becomes the receiver's address.

DHL API Documentation v1.0 36

 Ad 4. Multi collo (pieces)

The create label service will produce just one label per request, but if the shipment contains
more than one piece or package it is possible to specify this on the label through ‘pieceNumber’
and ‘quantity’ request attributes.

If a shipment contains for example two packages, the label service needs to be called twice. The
information set for first call to label service would be pieceNumber 1, quantity 2. For the second
label this information is set to pieceNumber 2, quantity 2.

See given examples of the created labels.

Multi colli is only possible if the shipment is not a single piece product (mono collo). In general
shipments meant for consumers are mono collo products, but not necessarily.

DHL API Documentation v1.0 37

 In the capabilities service you can determine if the product is a mono collo. See example of an
excerpt from the capability service below, the attribute monoColloProduct is either true or false.

{
"rank": 2,
"fromCountryCode": "NL",
"toCountryCode": "NL",
"product": {
"key": "DFY-SDD",
"label": "DFY",
"code": "00",
"menuCode": "07",
"businessProduct": true,
"monoColloProduct": true,
"softwareCharacteristic": "B2X",
"returnProduct": false
},
"parcelType": {
"key": "MEDIUM",
"minWeightKg": 20,
"maxWeightKg": 31,
"dimensions": {
"maxLengthCm": 80,
"maxWidthCm": 50,
"maxHeightCm": 35
}
},
"options": [
{
"key": "DOOR",
"description": "Delivery to the address of the recipient",
"rank": 2,
"code": 0,
"exclusions": [
{

3.3.2 Get label id by trackingcode or order reference

The Find labels endpoint by tracker code is essentially necessary if the label id is not stored in
your own application and the zpl or pdf of a label needs to be retrieved again.

The endpoint will return, among other identifying information (but not the label), the registered
label id to call the label endpoint that holds the zpl or pdf label, Get label endpoint by id.

The use of the authorization token in the header of http request is mandatory.

3.3.3 Get label by id

With the label id, as fetched with the endpoint Get label-id by trackingcode or order reference,
the pdf or zpl file for the specific label can be recovered through Get label endpoint by id.

The Get label endpoint by id has the same result as the post label endpoint and in addition the
organization-id is given.

DHL API Documentation v1.0 38

3.4 Environments and testing

Description URL

Create label endpoint https://api-gw.dhlparcel.nl/labels

https://api-
Endpoint to get label information by trackinggw.dhlparcel.nl/labels?trackerCodeFilter="your_t
code or order reference racking_code"
Endpoint to get the pdf label of specific
shipping https://api-gw.dhlparcel.nl/labels/your_labelId

3.4.1 Examples request code

3.4.1.1 Create Label

cURL

curl -X POST "https://api-gw.dhlparcel.nl/labels" -H "accept: application/json" -H

"Authorization: Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhNzAxN2EzZi1jMGYzLTQ3ZTAtOGQzNC1mMmZhMD
FjYTlkY2EiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb
25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzUwNywiZXhw
IjoxNTExODY4NDA4LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJ
hY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.Qs79I-LW0ES4mO8hObOiZXvuuipBQ_-eJ7pd-10rrSQ" -H
"content-type: application/json" -d "{ \"labelId\": \"331708e4-e876-4f9a-94f3-
c74bd482988b\", \"labelFormat\": \"pdf\", \"orderReference\": \"myReference\",
\"parcelTypeKey\": \"SMALL\", \"receiver\": { \"name\": { \"firstName\": \"John\",
\"lastName\": \"Doe\", \"companyName\": \"ACME Corp.\", \"additionalName\": \"Benelux\"
}, \"address\": { \"countryCode\": \"NL\", \"postalCode\": \"3542AD\", \"city\":
\"Utrecht\", \"street\": \"Reactorweg\", \"number\": \"25\", \"isBusiness\": true,
\"addition\": \"A\" }, \"email\": \"[email protected]\", \"phoneNumber\":
\"0031612345678\" }, \"shipper\": { \"name\": { \"firstName\": \"John\", \"lastName\":
\"Doe\", \"companyName\": \"ACME Corp.\", \"additionalName\": \"Benelux\" },
\"address\": { \"countryCode\": \"NL\", \"postalCode\": \"3542AD\", \"city\":
\"Utrecht\", \"street\": \"Reactorweg\", \"number\": \"25\", \"isBusiness\": true,
\"addition\": \"A\" }, \"email\": \"[email protected]\", \"phoneNumber\":
\"0031612345678\" }, \"accountId\": \"01234567\", \"options\": [ { \"key\": \"DOOR\" }
], \"returnLabel\": false, \"pieceNumber\": 1, \"quantity\": 1,
\"automaticPrintDialog\": true}"

PHP

<?php

// Get cURL resource

$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://api-gw.dhlparcel.nl/labels');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

DHL API Documentation v1.0 39

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
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",
]
);
// Create body
$json_array = [
"accountId" => "01234567",
"labelId" => "85146e8f-c5c6-40a5-9a1b-25548d607cd7",
"receiver" => [
"email" => "[email protected]",
"phoneNumber" => "0031612345678",
"name" => [
"firstName" => "Slab",
"companyName" => "Lechio",
"lastName" => "Krampus"
],
"address" => [
"countryCode" => "NL",
"number" => "74",
"isBusiness" => true,
"street" => "Baan",
"city" => "Rotterdam",
"postalCode" => "3011CD"
]
],
"shipper" => [
"email" => "[email protected]",
"phoneNumber" => "0031612345678",
"name" => [
"firstName" => "Jan",
"lastName" => "Jansen"
],
"address" => [
"street" => "Reactorweg",
"city" => "Utrecht",
"number" => "25",
"postalCode" => "3542AD",
"isBusiness" => true,
"addition" => "A",
"countryCode" => "NL"
]
],
"parcelTypeKey" => "SMALL",
"pieceNumber" => 1,
"quantity" => 1,
"automaticPrintDialog" => false,

DHL API Documentation v1.0 40

 "options" => [
[
"key" => "DOOR"
],
[
"key" => "COD_CASH",
"input" => "5"
]
],
"returnLabel" => false
];
$body = json_encode($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp

$resp = curl_exec($ch);

if(!$resp) {
die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources

curl_close($ch);

PHP cURL - WordPress

<?php

// Create JSON body

$json = json_encode( array(
'accountId' => '01234567',
'labelId' => '1e877014-fa2f-424c-95e7-2e2e8a05af44',
'receiver' => array(
'email' => '[email protected]',
'phoneNumber' => '0031612345678',
'name' => array(
'firstName' => 'Slab',
'companyName' => 'Lechio',
'lastName' => 'Krampus'
),,
'address' => array(
'countryCode' => 'NL',
'number' => '74',
'isBusiness' => true,
'street' => 'Baan',
'city' => 'Rotterdam',
'postalCode' => '3011CD'
),
),,
'shipper' => array(

DHL API Documentation v1.0 41

 'email' => '[email protected]',
'phoneNumber' => '0031612345678',
'name' => array(
'firstName' => 'Jan',
'lastName' => 'Jansen'
),,
'address' => array(
'street' => 'Reactorweg',
'city' => 'Utrecht',
'number' => '25',
'postalCode' => '3542AD',
'isBusiness' => true,
'addition' => 'A',
'countryCode' => 'NL'
),
),,
'parcelTypeKey' => 'SMALL',
'pieceNumber' => 1,
'quantity' => 1,
'automaticPrintDialog' => false,
'options' => array(
array(
'key' => 'DOOR'
),,
array(
'key' => 'COD_CASH',
'input' => '5'
),
),,
'returnLabel' => false
) );

// {@see https://codex.wordpress.org/HTTP_API}
$response = wp_remote_post( 'https://api-gw.dhlparcel.nl/labels', array(
'headers' => array(
'Content-Type' => 'application/json; charset=utf-8',
'Authorization' => 'Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkYWFkNzU3ZC03NGY4LTQ5YzktOWI4OC1kMzEyN2
Q2ZDczMDAiLCJzdWIiOiI5MWQ5NGZiZC0xODk2LTQyMTctODlkNy0wM2M4ZTY4Y2YwYTAiLCJvcmdhbml6YXRpb
25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzczMSwiZXhw
IjoxNTExODY4NjMyLCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJ
hY2NvdW50cyI6WyI3NDY1NjE3MCIsIjEyMzQ1Njk4IiwiNDU5MDAxMDAiLCI0MDA0NDU4OSIsIjg3NjU0MzIxIi
wiMzMzMzMzMzMiLCIwNTkyMDUxNyIsIjA4NTAwMDAxIiwiMTIzNDU2NzgiLCIwNTk1Nzg0MCJdfQ.KywXOWovoS
Vf1WJ-CWAJ9j4rUXuMp-f0q2c2PKkOZno',
'Accept' => 'application/pdf',
),
'body' => $json,
) );

if ( ! is_wp_error( $response ) ) {
// The request went through successfully, check the response code against
// what we're expecting
if ( 200 == wp_remote_retrieve_response_code( $response ) ) {
// Do something with the response
// $body = wp_remote_retrieve_body( $response );
// $headers = wp_remote_retrieve_headers( $response );
} else {
// The response code was not what we were expecting, record the message
$error_message = wp_remote_retrieve_response_message( $response );

DHL API Documentation v1.0 42

 }
} else {
// There was an error making the request
$error_message = $response->get_error_message();
}

3.4.1.2 Get Label (trackerCodeFilter)

curl -X GET "https://api-
gw.dhlparcel.nl/labels?trackerCodeFilter=JVGL08500001813590386271" -H "accept:
application/json" -H "Authorization: Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhNzAxN2EzZi1jMGYzLTQ3ZTAtOGQzNC1mMmZhMD
FjYTlkY2EiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb
25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzUwNywiZXhw
IjoxNTExODY4NDA4LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJ
hY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.Qs79I-LW0ES4mO8hObOiZXvuuipBQ_-eJ7pd-10rrSQ"

3.4.1.3 Get pdf label specific shipment

curl -X GET "https://api-gw.dhlparcel.nl/labels/ecda3006-b605-413f-b3b1-e0dca32e987e" -
H "accept: application/json" -H "Authorization: Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhNzAxN2EzZi1jMGYzLTQ3ZTAtOGQzNC1mMmZhMD
FjYTlkY2EiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb
25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzUwNywiZXhw
IjoxNTExODY4NDA4LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJ
hY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.Qs79I-LW0ES4mO8hObOiZXvuuipBQ_-eJ7pd-10rrSQ"

3.4.2 Responses (success)

3.4.2.1 Create label

Response 201:

{
"labelId": "331708e4-e876-4f9a-94f3-c74bd482988b",
"labelType": "B2X_Generic_A4_Third",
"trackerCode": "JVGL01234567889003262926",
"routingCode": "2LNL3542AD+04000000",
"userId": "a86628b8-a4bd-436b-8d92-cd735223c9e5",
"orderReference": "myReference",
"pdf": "<pdf-label>"
}

3.4.2.2 Get label-id

Response 200:

[
{
"labelId": "ecda3006-b605-413f-b3b1-e0dca32e987e",
"orderReference": "393d649c-fdf4-4e16-b329-40c36e8cff48",
"labelType": "B2X_Generic_A4_Third",
"trackerCode": "JVGL08500001813590386271",
"routingCode": "2LIC12342+04000001",
"userId": "6bfc7561-4b41-4cb7-a1c3-dc31faf860db",
"organizationId": "a40933de-bd17-4944-b7e9-23fc7ee9c835"

DHL API Documentation v1.0 43

 }
]

3.4.2.3 Get pdf label

Response 200:

{
"labelId": "ecda3006-b605-413f-b3b1-e0dca32e987e",
"labelType": "B2X_Generic_A4_Third",
"trackerCode": "JVGL08500001813590386271",
"routingCode": "2LIC12342+04000001",
"userId": "6bfc7561-4b41-4cb7-a1c3-dc31faf860db",
"organizationId": "a40933de-bd17-4944-b7e9-23fc7ee9c835",
"orderReference": "393d649c-fdf4-4e16-b329-40c36e8cff48",
"pdf": "<base64-encoded pdf-label>"
}

3.4.3 Testing
These test cases with positive outcomes are merely suggestions and it is not an extensive test
set, e.g. test with negative outcome should also be taken into scope. Please extend with test
cases which are suitable for your line of business or wishes.

Suggested Test Cases Expected Result

A label is created and the identifying information and pdf
Create a label of the label is returned.
Get label id by tracking code or order
reference The label identification is returned.

Get pdf label by id The pdf of the label is returned.

DHL API Documentation v1.0 44

4 Find parcel shop location

DHL API Documentation v1.0 45

4.1 Intro

The Parcel shop finder endpoint makes it possible to find parcel shops or DHL Servicepoints in a
country based on address information and or a wildcard.

Preconditions

No preconditions are applicable.

DHL API Documentation v1.0 46

4.2 Services

4.2.1 Find the nearest parcel shop location endpoint

The Find the nearest parcel shop location endpoint gets you a list of the nearby DHL
Servicepoints based on the country code and address information or a wildcard (q) like a piece
of the recipient's address e.q. city and or name or the postal code of an address.

So in order to get a list of parcel shops the country code is required and at least one of these
fields: free format location description, postal code, city.

Field Description
free format location description, where multiple
keywords can be entered. For example country
code 'NL' and keywords 'Tabak' and '1055' will
return a parcel shop in Amsterdam (postal code
q with 1055 in it) and that has 'Tabak' in its name.

format depends on the country e.g. for the country

zipCode code 'NL' it is '9999XX', 'ES' is is '99999' etc.

The more specific the address is the less DHL Servicepoints will be returned and the more
accurate the result is. A query based on just the street name will not suffice. There is the option
to limit the result with the inputfield 'limit'.

The result is ordered ascending based on the geo location, meaning the nearest DHL
ServicePoint is at the top.

In the response the identification is given of a DHL ServicePoint. This id serves as extra input in
the shipment option as explained in 3.3.1 Create Label when sending a shipment to a DHL
ServicePoint.

4.2.2 Get specific DHL Servicepoint

The Find the information for a specific parcel shop location endpoint allows you to select a
specific DHL ServicePoint. The country code is mandatory and the DHL ServicePoint id is needed.
This id can be queried by using the Find the nearest parcel shop location endpoint.

4.3 Environment and testing

Description URL

DHL API Documentation v1.0 47

 6 https://api-gw.dhlparcel.nl/parcel-shop-
5 Endpoint to get nearest parcel shops locations/<countrycode>?
https://api-gw.dhlparcel.nl/parcel-shop-
Endpoint to get specific parcel shop locations/<countrycode>/<parcelshopId>

6.1.1 Examples

cURL

6.1.1.1 Nearest parcel shops

curl -X GET "https://api-gw.dhlparcel.nl/parcel-shop-
locations/ES?city=Madrid&showUnavailable=false" -H "accept: application/json"
cURL

6.1.1.2 Specific parcel shop

curl -X GET "https://api-gw.dhlparcel.nl/parcel-shop-locations/ES/5017-ES-0000104" -H
"accept: application/json"

6.1.2 Responses (success)

Find nearest parcel shops 200:

[
{
"id": "5017-ES-0000104",
"harmonisedId": "101",
"psfKey": "ES-0000104",
"shopType": "parcelShop",
"name": "FOLDER PLAZA DEL ANGEL",
"keyword": "DHL ServicePoint",
"address": {
"countryCode": "ES",
"zipCode": "28012",
"postalCode": "28012",
"city": "MADRID",
"street": "C/ PLAZA DEL ANGEL",
"number": "16",
"isBusiness": true
},
"geoLocation": {
"latitude": 40.414381,
"longitude": -3.702893
},
"distance": 284,
"openingTimes": [
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 1
},
{

DHL API Documentation v1.0 48

 "timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 1
},
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 2
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 2
},
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 3
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 3
},
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 4
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 4
},
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 5
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 5
},
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 6
},
{
"timeFrom": "16:30:00.000",
"timeTo": "20:30:00.000",
"weekDay": 6
}
],
"closurePeriods": []
},
{
"id": "5017-ES-0001288",

DHL API Documentation v1.0 49

 "harmonisedId": "101",
"psfKey": "ES-0001288",
"shopType": "parcelShop",
"name": "WORKCENTER C/ SEVILLA",
"keyword": "DHL ServicePoint",
"address": {
"countryCode": "ES",
"zipCode": "28014",
"postalCode": "28014",
"city": "MADRID",
"street": "C/ SEVILLA",
"number": "4",
"isBusiness": true
},
"geoLocation": {
"latitude": 40.417446,
"longitude": -3.699818
},
"distance": 446,
"openingTimes": [
{
"timeFrom": "08:00:00.000",
"timeTo": "21:00:00.000",
"weekDay": 1
},
{
"timeFrom": "08:00:00.000",
"timeTo": "21:00:00.000",
"weekDay": 2
},
{
"timeFrom": "08:00:00.000",
"timeTo": "21:00:00.000",
"weekDay": 3
},
{
"timeFrom": "08:00:00.000",
"timeTo": "21:00:00.000",
"weekDay": 4
},
{
"timeFrom": "08:00:00.000",
"timeTo": "21:00:00.000",
"weekDay": 5
},
{
"timeFrom": "10:00:00.000",
"timeTo": "14:30:00.000",
"weekDay": 6
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 6
},
{
"timeFrom": "11:00:00.000",
"timeTo": "14:30:00.000",
"weekDay": 7

DHL API Documentation v1.0 50

 },
{
"timeFrom": "17:00:00.000",
"timeTo": "21:30:00.000",
"weekDay": 7
}
],
"closurePeriods": []
},
{
"id": "5017-ES-0002224",
"harmonisedId": "101",
"psfKey": "ES-0002224",
"shopType": "parcelShop",
"name": "INFINITY COMICS",
"keyword": "DHL ServicePoint",
"address": {
"countryCode": "ES",
"zipCode": "28013",
"postalCode": "28013",
"city": "MADRID",
"street": "C/ HILERAS",
"number": "2",
"isBusiness": true
},
"geoLocation": {
"latitude": 40.416814,
"longitude": -3.708361
},
"distance": 505,
"openingTimes": [
{
"timeFrom": "11:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 1
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 1
},
{
"timeFrom": "11:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 2
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 2
},
{
"timeFrom": "11:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 3
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",

DHL API Documentation v1.0 51

 "weekDay": 3
},
{
"timeFrom": "11:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 5
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 5
},
{
"timeFrom": "11:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 6
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 6
}
],
"closurePeriods": []
}
]

Find specific parcel shop 200:

{
"id": "5017-ES-0000104",
"harmonisedId": "101",
"psfKey": "ES-0000104",
"shopType": "parcelShop",
"name": "FOLDER PLAZA DEL ANGEL",
"keyword": "DHL ServicePoint",
"address": {
"countryCode": "ES",
"zipCode": "28012",
"postalCode": "28012",
"city": "MADRID",
"street": "C/ PLAZA DEL ANGEL",
"number": "16",
"isBusiness": true
},
"geoLocation": {
"latitude": 40.414381,
"longitude": -3.702893
},
"openingTimes": [
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 1
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 1

DHL API Documentation v1.0 52

 },
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 2
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 2
},
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 3
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 3
},
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 4
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 4
},
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 5
},
{
"timeFrom": "17:00:00.000",
"timeTo": "20:30:00.000",
"weekDay": 5
},
{
"timeFrom": "10:00:00.000",
"timeTo": "14:00:00.000",
"weekDay": 6
},
{
"timeFrom": "16:30:00.000",
"timeTo": "20:30:00.000",
"weekDay": 6
}
],
"closurePeriods": []
}

DHL API Documentation v1.0 53

6.1.3 Testing
These test cases with positive outcomes are merely suggestions and it is not an extensive test
set, e.g. tests with a negative outcome should also be taken into scope. Please extend with test
cases which are suitable for your line of business or wishes.

Suggested Test Cases Expected Result

Place a request limit to 3 for Three parcel shops are returned in the given place by the
specific country code and place Find the nearest parcel shop location endpoint

Place a request with the ID of a The given parcel shop is returned by the Find the
parcel shop information for a specific parcel shop location endpoint.

DHL API Documentation v1.0 54

7 Track & Trace

DHL API Documentation v1.0 55

7.1 Intro

With the Track & Trace endpoint a shipment can be tracked throughout the delivery process.

The most important information from a business perspective will be discussed.

Preconditions

 Authentication token. See documentation on Authentication and authorization endpoint.

A token is only needed if you need to retrieve the tracker code through the label service.
See documentation on Labels endpoints.

 The tracker code and optional the postal code of the receiver.

The tracker code is a return value when creating the label. See documentation on Labels
endpoints.

DHL API Documentation v1.0 56

7.2 Services

7.2.1 Track & Trace

The Track & Trace endpoint is called with at least the tracker code, that is provided in the
response of the Create label endpoint when the label has successfully been created.

A call to the T&T endpoint will result in a chain of events (technically an array), where each
event falls into a category of the whereabouts of a shipment. A category holds a status which
gives a more detailed description of what might be the exact current state of the shipment.
Endpoints for the translation of these statusfields can be found in the API gateway under
Translations.

Status category Description

CUSTOMS The shipment is being processed by customs
DATA RECEIVED The shipment is registrered
DELIVERED Delivered at door or DHL ServicePoint
EXCEPTION Something in the process went wrong, delay is expected
INTERVENTION An interventation occured in the delivery process
IN DELIVERY The parcel is in transit
LEG Usually the trace of a domestic delivery will start with some LEG
events. It means that the shipment is registered.
PROBLEM Same as exception
UNDERWAY The parcel is being sorted
UNKNOWN The status of the parcel is unknown

For more extensive information (shipment details) in the track & trace response the postal code
of the receiver can be added in the request.

 https://api-gw.dhlparcel.nl/track-trace?key=3SBPB0000094346+9999BB

Delivery date

Initially there is no planned delivery date, but it can be calculated by deriving the transit time
set for the country of origin and destination through the Transit-times endpoint.

Based on the country codes of origin, destination and the postal code, the transit time in days is
given as a result by the endpoint. To calculate the planned delivery date simply add the transit
time days to the shipment date.

As soon as a parcel has left the sorting center the planned delivery timeframe
('plannedDeliveryTimeframe') should be available in the next event.

DHL API Documentation v1.0 57

 This planned delivery timeframe can change or might not be available in the last event due to
for example problems with the receiver's address. The shipment gets marked with category
PROBLEM or INTERVENTION and the shipment will need to be re-planned.

The fact that, and when, a parcel actually is delivered is communicated through the attribute
'deliveredAt' (at top level in the json response).

7.2.2 Environments and testing

Enviroments

Description URL

Track & Trace https://api-gw.dhlparcel.nl/track-trace

7.2.2.1 Examples - request code

curl -X GET "https://api-gw.dhlparcel.nl/track-trace?key=3SBPB0000094346%2B9999AA" -H
"accept: application/json"

7.2.2.2 Responses (success)

Response 200:

Response 200:

[
{
"barcode": "3SBPB0000094346",
"date": "2017-11-28T23:00:00.000Z",
"events": [
{
"category": "LEG",
"leg": {
"accountId": "5880133",
"debtorNumber": "5880133",
"destinationFacility": "ARM",
"destinationServiceArea": "ARM",
"number": "7451930615",
"network": "DAY_DEFINITE",
"originFacility": "MAA",
"originServiceArea": "MAA",
"reference": "60832634"
},
"localTimestamp": "2017-11-29T00:00:00.000+01:00",
"status": "LEG_CREATED",
"timestamp": "2017-11-28T23:00:00.000Z",
"type": "LEG_EVENT"
},
{
"category": "LEG",

DHL API Documentation v1.0 58

 "leg": {
"network": "DAY_DEFINITE"
},
"localTimestamp": "2017-11-29T00:00:00.000+01:00",
"status": "LEG_REFERENCE_ADDED",
"timestamp": "2017-11-28T23:00:00.000Z",
"type": "LEG_EVENT"
},
{
"category": "LEG",
"leg": {
"network": "DAY_DEFINITE",
"reference": "60832634"
},
"localTimestamp": "2017-11-29T00:00:00.000+01:00",
"status": "LEG_REFERENCE_ADDED",
"timestamp": "2017-11-28T23:00:00.000Z",
"type": "LEG_EVENT"
},
{
"category": "LEG",
"leg": {
"network": "DAY_DEFINITE",
"reference": "3SDSP004644834"
},
"localTimestamp": "2017-11-29T00:00:00.000+01:00",
"status": "LEG_REFERENCE_ADDED",
"timestamp": "2017-11-28T23:00:00.000Z",
"type": "LEG_EVENT"
},
{
"category": "DATA_RECEIVED",
"localTimestamp": "2017-11-29T21:56:54.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "PRENOTIFICATION_RECEIVED",
"timestamp": "2017-11-29T20:56:54.000Z",
"type": "PIECE_EVENT"
},
{
"category": "LEG",
"leg": {
"accountId": "79807100",
"network": "ECOMMERCE"
},
"localTimestamp": "2017-11-29T21:57:07.000+01:00",
"status": "LEG_CREATED",
"timestamp": "2017-11-29T20:57:07.000Z",
"type": "LEG_EVENT"
},
{
"category": "UNDERWAY",
"facility": "RXD",
"height": 14,
"length": 18,
"localTimestamp": "2017-11-29T23:50:00.000+01:00",
"leg": {
"network": "DAY_DEFINITE"
},
"powerOfAttorney": false,
"remarks": "",

DHL API Documentation v1.0 59

 "route": "0",
"scannedManual": false,
"serviceArea": "RXD",
"status": "DEPART_FACILITY",
"stopNumber": 0,
"timestamp": "2017-11-29T22:50:00.000Z",
"weight": 0.2,
"width": 14,
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "DD/RXD",
"localTimestamp": "2017-11-29T23:50:00.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "PARCEL_SORTED_AT_HUB",
"timestamp": "2017-11-29T22:50:00.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"localTimestamp": "2017-11-30T00:11:27.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-01T14:00:00.000+01:00/2017-12-
01T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-11-30T14:00:00.000+01:00/2017-11-
30T18:00:00.000+01:00",
"status": "INFORMATION_ON_DELIVERY_TRANSMITTED",
"timestamp": "2017-11-29T23:11:27.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARM",
"height": 14,
"length": 18,
"localTimestamp": "2017-11-30T03:55:00.000+01:00",
"leg": {
"network": "DAY_DEFINITE"
},
"plannedDeliveryTimeframe": "2017-11-30T08:00:00.000+01:00/2017-11-
30T18:00:00.000+01:00",
"powerOfAttorney": false,
"remarks": "",
"route": "0",
"scannedManual": false,
"serviceArea": "ARM",
"status": "ARRIVED_AT_DELIVERY_FACILITY",
"stopNumber": 0,
"timestamp": "2017-11-30T02:55:00.000Z",
"weight": 0.2,
"width": 14,
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARNPAK",
"localTimestamp": "2017-11-30T04:42:41.000+01:00",

DHL API Documentation v1.0 60

 "leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-01T14:00:00.000+01:00/2017-12-
01T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-11-30T14:00:00.000+01:00/2017-11-
30T18:00:00.000+01:00",
"route": "1",
"status": "DELIVERY_PLANNED_IN_ROUTE",
"timestamp": "2017-11-30T03:42:41.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARM",
"height": 14,
"length": 18,
"localTimestamp": "2017-11-30T08:04:00.000+01:00",
"leg": {
"network": "DAY_DEFINITE"
},
"plannedDeliveryTimeframe": "2017-11-30T08:00:00.000+01:00/2017-11-
30T18:00:00.000+01:00",
"powerOfAttorney": false,
"remarks": "DHL Parcel Arnhem Zuid",
"route": "512150",
"scannedManual": true,
"serviceArea": "ARM",
"status": "IN_ROUTE_THIRD_PARTY",
"stopNumber": 1,
"timestamp": "2017-11-30T07:04:00.000Z",
"weight": 0.2,
"width": 14,
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARNPAK",
"localTimestamp": "2017-11-30T08:05:15.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-01T14:00:00.000+01:00/2017-12-
01T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-11-30T14:00:00.000+01:00/2017-11-
30T18:00:00.000+01:00",
"route": "2",
"status": "DELIVERY_PLANNED_IN_ROUTE",
"timestamp": "2017-11-30T07:05:15.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARM",
"height": 14,
"length": 18,
"localTimestamp": "2017-11-30T08:46:00.000+01:00",
"leg": {
"network": "DAY_DEFINITE"
},
"plannedDeliveryTimeframe": "2017-11-30T08:00:00.000+01:00/2017-11-
30T18:00:00.000+01:00",

DHL API Documentation v1.0 61

 "powerOfAttorney": false,
"remarks": "DHL Parcel Arnhem Zuid",
"route": "512150",
"scannedManual": true,
"serviceArea": "ARM",
"status": "FORWARD_DESTINATION",
"stopNumber": 1,
"timestamp": "2017-11-30T07:46:00.000Z",
"weight": 0.2,
"width": 14,
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ETTPAK",
"localTimestamp": "2017-11-30T09:11:09.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"route": "2",
"status": "PARCEL_ARRIVED_AT_LOCAL_DEPOT",
"timestamp": "2017-11-30T08:11:09.000Z",
"type": "PIECE_EVENT"
},
{
"category": "PROBLEM",
"facility": "ARNPAK",
"localTimestamp": "2017-11-30T09:11:10.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-01T14:00:00.000+01:00/2017-12-
01T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-11-30T14:00:00.000+01:00/2017-11-
30T18:00:00.000+01:00",
"route": "2",
"status": "MISSORT",
"timestamp": "2017-11-30T08:11:10.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ETTPAK",
"localTimestamp": "2017-11-30T09:11:40.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"route": "2",
"status": "PARCEL_ARRIVED_AT_LOCAL_DEPOT",
"timestamp": "2017-11-30T08:11:40.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "PI",
"localTimestamp": "2017-12-01T20:55:13.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "PARCEL_SCANNED_AT_RETURN_HUB",
"timestamp": "2017-12-01T19:55:13.000Z",
"type": "PIECE_EVENT"

DHL API Documentation v1.0 62

 },
{
"category": "UNDERWAY",
"facility": "PI",
"localTimestamp": "2017-12-03T17:42:26.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "DEPOT_SCAN",
"timestamp": "2017-12-03T16:42:26.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "PI",
"localTimestamp": "2017-12-05T21:58:56.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "DEPOT_SCAN",
"timestamp": "2017-12-05T20:58:56.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "EC&gt;144",
"localTimestamp": "2017-12-06T18:04:40.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "PARCEL_SORTED_AT_HUB",
"timestamp": "2017-12-06T17:04:40.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"localTimestamp": "2017-12-06T18:07:37.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-08T14:00:00.000+01:00/2017-12-
08T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-12-07T14:00:00.000+01:00/2017-12-
07T18:00:00.000+01:00",
"status": "INFORMATION_ON_DELIVERY_TRANSMITTED",
"timestamp": "2017-12-06T17:07:37.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T04:14:46.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-08T14:00:00.000+01:00/2017-12-
08T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-12-07T14:00:00.000+01:00/2017-12-
07T18:00:00.000+01:00",
"route": "1",
"status": "DELIVERY_PLANNED_IN_ROUTE",
"timestamp": "2017-12-07T03:14:46.000Z",

DHL API Documentation v1.0 63

 "type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T08:14:50.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"route": "1",
"status": "PARCEL_ARRIVED_AT_LOCAL_DEPOT",
"timestamp": "2017-12-07T07:14:50.000Z",
"type": "PIECE_EVENT"
},
{
"category": "IN_DELIVERY",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T09:47:23.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-08T14:00:00.000+01:00/2017-12-
08T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-12-07T14:00:00.000+01:00/2017-12-
07T18:00:00.000+01:00",
"route": "1",
"status": "PARCEL_SCANNED_INTO_HAND-TERMINAL",
"timestamp": "2017-12-07T08:47:23.000Z",
"type": "PIECE_EVENT"
},
{
"category": "IN_DELIVERY",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T10:15:18.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-08T14:00:00.000+01:00/2017-12-
08T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-12-07T14:00:00.000+01:00/2017-12-
07T18:00:00.000+01:00",
"route": "1",
"status": "OUT_FOR_DELIVERY",
"timestamp": "2017-12-07T09:15:18.000Z",
"type": "PIECE_EVENT"
},
{
"category": "IN_DELIVERY",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T10:15:18.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"route": "1",
"status": "PARCEL_HANDED_OVER_TO_COURIER",
"timestamp": "2017-12-07T09:15:18.000Z",
"type": "PIECE_EVENT"
},
{
"category": "DELIVERED",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T16:58:41.000+01:00",

DHL API Documentation v1.0 64

 "leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-08T14:00:00.000+01:00/2017-12-
08T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-12-07T14:00:00.000+01:00/2017-12-
07T18:00:00.000+01:00",
"route": "1",
"status": "DELIVERED",
"timestamp": "2017-12-07T15:58:41.000Z",
"type": "PIECE_EVENT"
}
],
"type": "SHIPMENT",
"deliveredAt": "2017-12-07T16:58:41.000+01:00",
"id": "5a1f1f5f014129d859716df6"
}
]

7.2.3 Testing
These test cases with positive outcomes are merely suggestions and it is not an extensive test
set, e.g. tests with a negative outcome should also be taken into scope. Please extend with test
cases which are suitable for your line of business or wishes.

Suggested Test Cases Expected Result

Place a request with Track and trace info is shown for given tracker code
tracker code

Place a request with Track and trace info is shown for given tracker code and the
tracker code and zipCode of the address details
receiver

DHL API Documentation v1.0 65

8 FAQ

DHL API Documentation v1.0 66

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

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

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

3. 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, [

DHL API Documentation v1.0 67

 "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.eyJqdGkiOiJhNzAxN2EzZi1jMGYzLTQ3ZTAtOGQzNC1mMmZhMDFjYT
lkY2EiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb25JZCI6I
mE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzUwNywiZXhwIjoxNTExODY4
NDA4LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyI
wODUwMDAwMSJdfQ.Qs79I-LW0ES4mO8hObOiZXvuuipBQ_-eJ7pd-10rrSQ"

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

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

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

DHL API Documentation v1.0 68

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

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

DHL API Documentation v1.0 69

9 APPENDIX

DHL API Documentation v1.0 70

 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

BOUW Delivery to construction site

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

NBB No neighbour delivery

PS Delivery to the specified DHL Parcelshop or DHL Parcelstation

RECAP Additional proof of delivery

PERS_NOTE Email to the receiver (for MDP Business app only)

REFERENCE Reference on label

REFERENCE2 Extra reference label

ADD_RETURN_LABELPrint extra label for return shipment (for MDP Business app only)
S Saturday delivery

SSN Undisclosed sender

DHL API Documentation v1.0 71

BP Mailbox delivery

NO_TRACK_TRACE No track and trace for shipment

DHL API Documentation v1.0 72