Overview 

This chapter explains first steps of the system functionality by operational examples:

• get-status-for-public-user
• d-get-piece-detail
• d-get-signature

You will find more technical information in chapter "How to test the API".

Operations

Shipment tracking API for public use ("public" query)

• The public shipment tracking API already provides by design a smaller data scope that corresponds to shipment tracking for private customers.
• In the future, however, users will need to add the recipients postal code in order to display the data for "City/Town" and the warehouse address of the retail outlet/Packstation.
• In case of online returns, the senders postal code must be used.
• Important information:
  • It is only possible to add the postal code when conducting a query using the shipment number (no references)
  • It is only possible to add the postal code when conducting a single request for one shipment (multiple queries by adding the postal code are not possible)
• Should these data be required, it is necessary to transmit the postal code as an API call parameter  
• We recommend implementation of this by CW 25

Shipment tracking API for business customers ("business" query)

• If shipment data are restricted, fields in the API response that contain personal data remain empty
• To fully display these data, it is necessary to transmit the recipients postal code as an API call parameter
• In the case of online returns, the senders postal code must be used
• Important information:
  • It is only possible to add the postal code when conducting a query using the shipment number (no references)
  • It is only possible to add the postal code when conducting a single request for one shipment (multiple queries by adding the postal code are not possible)
• The postal code can thus be preventively transmitted directly with the first request to ensure that all data are included in the first response

Private customer

• get-status-for-public-user:
  Query of the current shipment status for public use

Business customers

• d-get-piece-detail:
  Combined call-up of shipment status and route
• d-get-signature:
  Query for the signature of the recipient or substitute recipient (proof of delivery / POD)

General

No statistical data about the shipment of packages is provided via the shipment tracking API.

If several consignment numbers / reference numbers are queried, the result is returned in the form of a list.
If a shipment cannot be clearly identified (e.g. if a shipment number is not assigned twice within one year), the shipment results are also returned in the form of a list.

In order to restrict the result set from the outset, the attributes zip-code and from-date/to-date should be given when calling for a detailed search query.

Important information about the parameters

All functions have the following query parameters in common:

• User ID appname
  ID with which the customer authenticates himself for using the interface
• Password password
  The password associated with the user ID
• Language code (ISO Language Code) language-code
  The language code defines the language that is selected for the presentation of results. The following codes are currently possible:
  en for English
  de for German

All functions have an identical response behavior:

Important: The attributes with the note "are no longer available!" should no longer be used for a client-side evaluation, since they will no longer be contained in the answer in the future!

Rights and Authentication

As a business customer of DHL you can use all functions. However, the individual functions are linked to rights that are assigned separately. If a function is not enabled for you, a corresponding error message will be sent when you call it. In this case, please contact your DHL customer advisor, who will check the authorization for your business customer account and have it extended accordingly.

Each time you call up the shipment tracking API, you must authenticate yourself as the user or the program using a user ID and password (see query parameters). Please note that the permissions to query shipments in the DHL shipment tracking area for business customers are linked to your DHL customer number (EKP) or to the shipment number range assigned to your business customer account. This ensures that access to the shipment status of third-party shipments is excluded.

For calls without a DHL business customer contract, you can only access the shipment tracking API area for public use ("public" query).

get-status-for-public-user

The "get-status-for-public-user" function provides information as it is currently displayed in the DHL public shipment tracking area ( www.dhl.de ).

The following special features apply to the "get-status-for-public-user" operation:

• The shipment query is possible via a shipment number or reference. Up to 15 consignment numbers or references can be transferred per call.
  The individual numbers must be separated from each other by a semicolon. If several consignment numbers or shipment references are included in the query, there will be several elements in the response accordingly.
   
• If a shipment cannot be clearly identified (e.g. if a shipment number is not assigned twice within one year), the shipment results are returned in the form of a list. In order to restrict the result set from the outset, the attribute "zip-code" should be given when calling.
   
• In order to display the data for "Location" and the warehouse address of the branch/Packstation, the recipient's postal code must be provided. In case of online returns, the sender's zip code must be provided . Personal data will not be provided.
   
• Important instructions:
  • The zip code only works when querying the shipment number ( no references)
  • The post code only works with one request for a shipment (collective queries with post code are not possible)
     
• The number format is checked on the DHL side. If the structure does not correspond to a valid shipment number format, the shipment search for this shipment is aborted.

Sample Data

Request

https://api-eu.dhl.com/parcel/de/tracking/v0/shipments?xml=

<data
                request="get-status-for-public-user"
                appname="Benutzerkennung"
                password="Passwort"
                language-code="de">
                <data
                               piece-code="961001046136"
                               piece-customer-reference=""
                               date-from="YYYY-MM-DD"
                               date-to="YYYY-MM-DD"
                               zip-code="12345"
                />
</data>

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data request-id="379d9788-5a8e-49dd-9f7e-d30e17746c2a">
<data name="piece-status-public-list"
    code="0"
    _piece-code="0231234
    _zip-code="32584">
    <data name="piece-status-public"
        piece-identifier="231234"
        _build-time="2012-06-06 18:18:10.000607"
        piece-id="3b048653-aaa9-485b-b0dd-d16e068230e9"
        leitcode=""
        searched-piece-code="0231234"
        piece-status="0"
        identifier-type="2"
        recipient-name="Hr. Hannes Testler"
        recipient-id="1"
        recipient-id-text="Empfänger (orig.)"
        pan-recipient-name=" "
        street-name=""
        house-number=""
        city-name=""
        last-event-timestamp="11.03.2012 11:59"
        shipment-type=""
        status-next=""
        status="Die Sendung wurde ausgeliefert."
        error-status="0"
        delivery-event-flag="1"
        upu=""
        international-flag="0"
        piece-code="0231234"
        ice="DLVRD"
        ric="ACCPT"
        division="DPEED"
        dest-country="de"
        origin-country="de"
        product-code="00"
        product-name="DHL PAKET"
        searched-ref-no="034234"
        standard-event-code="ZU"
        pan-recipient-street=""
        pan-recipient-city=""
        event-country="de"
        event-location=""
        shipment-length="0.0"
        shipment-width="0.0"
        shipment-height="0.0"
        shipment-weight="0.2" />
    </data>
</data>

I/O Reference "get-status-for-public-users"

Request parameter

The following attributes can be passed via the <data> element:

Bei einer optionalen Zeitraumabfrage sind folgende Parameter zu definieren:

Response Parameter

The attributes of a response have the following meaning:

Important: The attributes with the note Is no longer available! should no longer be used for a client-side evaluation, as they will no longer be included in the answer in the future!

Attachment: ICE Event RIC Kombinationen_11_2023.csv

d-get-piece-detail

The "d-get-piece-detail" function retrieves all information about a shipment via a query. This is done by combining the query of the shipment status and the query of the shipment progress (events list).

The following special features apply to the "d-get-piece-detail" operation:

• The function can be accessed with a shipment number and a shipment reference.
   
• Up to 20 shipment numbers or references can be transferred per request. The individual numbers must be separated from each other by a semicolon. If there are several consignment numbers or references in the query, there will be several elements in the response accordingly.
   
• The number format is checked on the DHL side. If the structure does not correspond to a valid shipment number format, the shipment search for this shipment is aborted.
   
• If a shipment cannot be clearly identified (e.g. if a shipment number is not assigned twice within one year), the shipment results are returned in the form of a list. In order to restrict the result set from the outset , the attribute "zip-code" should be given when calling.
   
• Important instructions:
  • The zip code only works when querying the shipment number ( no references).
  • The post code only works for individual queries, i.e. with one request per shipment (collective queries with zip code are not possible.
     
• In order to define a query for a certain period of time, the beginning (from-date) and the end (to-date) of the period of the search can be specified .

Sample Data

Request

https://api-eu.dhl.com/parcel/de/tracking/v0/shipments?xml=

<?xml version="1.0" encoding="UTF-8" ?>
<data appname="userid"
         password="password"
request="d-get-piece-detail"
         language-code="iso-language-code" - de or en
zip code= zip code
piece-code="tracking number"
or
piece-customer-reference="Shipment reference"
or
         from date="20 23 -0 1 -01"
to-date="20 23 -0 3 - 31 ">
</data>

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data name="pieceshipmentlist"
	request-id="379d9788-5a8e-49dd-9f7e-d30e17746c2a"
	code="0">
	<data name="pieceshipment"
		error-status="0"
		piece-id="3b048653-aaa9-485b-b0dd-d16e068230e9"
		shipment-code=""
		piece-identifier="26633445"
		identifier-type="1"
		piece-code="266334453"
		event-location=""
		event-country="DE"
		status-liste=""
		status-timestamp="16.03.2012 15:29"
		status="Die Sendung wurde erfolgreich zugestellt."
		short-status="Zustellung erfolgreich"
		recipient-name="TestMustermann"
		recipient-street="Am Musterhaus 5"
		recipient-city="23221 Testmannsdorf"
		pan-recipient-name="TestMustermann"
		pan-recipient-street="Am Musterhaus 5"
		pan-recipient-city="23221 Testmannsdorf"
		pan-recipient-address="Am Musterhaus 5 23221 Testmannsdorf"
		shipper-name="VersandhausHeileWelt"
		shipper-street="Testerstraße 111"
		shipper-city="53113 Meindorf"
		shipper-address="Testerstraße 111 53113 Meindorf"
		product-code="00"
		product-key=""
		product-name="DHLPAKET"
		delivery-event-flag="1"
		recipient-id="2"
		recipient-id-text="Ehegatte"
		upu=""
		shipment-length="0.0"
		shipment-width="0.0"
		shipment-height="0.0"
		shipment-weight="0.2"
		international-flag="0"
		division="DPEED"
		ice="DLVRD"
		ric="ACCPT"
		standard-event-code="ZU"
		dest-country="DE"
		origin-country="DE"
		searched-piece-code="26633445"
		searched-ref-nr=""
		piece-customer-reference="034234"
		shipment-customer-reference="111234"
		leitcode="" />
	<data name="pieceeventlist"
		piece-identifier="2343265"
		_build-time="2012-10-06 18:18:10.000607"
		piece-id="3b048653-aaa9-485b-b0dd-d16e068230e9"
		leitcode="34634543453">
		<data name="pieceevent"
			event-timestamp="14.03.2012 00:00"
			event-status=
                        "Die Sendung wurde im Start-Paketzentrum bearbeitet."
			event-text=
                        "Die Sendung wurde im Start-Paketzentrum bearbeitet."
			ice="LDTMV"
			ric="MVMTV"
			event-location="Saulheim"
			event-country="Deutschland"
			standard-event-code="AA"/>
			  .
			  .
			  .
		<data name="pieceevent"
			event-timestamp="16.03.2012 15:29"
			event-status="Die Sendung wurde erfolgreich zugestellt."
			event-text=" Die Sendung wurde erfolgreich zugestellt."
			ice="DLVRD"
			ric="ACCPT"
			event-location="Bonn"
			event-country="Deutschland"
			standard-event-code="ZU"/>
	</data>
</data>

I/O Reference "d-get-piece-detail"

Request parameters

The following attributes can be passed via the <data> element:

The following parameters must be defined for an optional period query:

Response Parameter

The attributes of a response have the following meaning:

Important: The attributes with the note Is no longer used! should no longer be used for a client-side evaluation, as they will no longer be included in the answer in the future!

Attachment: ICE_Event_RIC_Kombinationen_11_2021.csv

d-get-signature

The "d-get-signature" function can retrieve the recipient's or substitute recipient's signature. The signatures are also known as POD = Proof of Delivery.

Of note here are the following particular features:

• Recipient signatures can only be retrieved via the tracking number.
• The signature itself is provided in the form of a GIF image format. Since this image format contains binary data and this would cause problems when transferred to XML, the data is converted byte-by-byte into hexadecimal notation.
• The accesses are typically very resource-intensive. It is advisable to only call up signatures for delivered shipments ( delivery-event-flag = 1 ) with dest-country = DE , since signatures are only available in the system for these shipments. The signatures may only be retrieved once. If you have already retrieved a signature, you should store it in your system for future reference.
• Please note the regulation of data minimization according to Art. 5 Para. 1c EU-DSGVO.
  The recipient's signature may only be downloaded as proof of delivery in disputed cases or if there are legal requirements.

Note:To display the signature as an image file, the character string must be converted to the gif image format. In this case, two characters of the image data from the response correspond to a hexadecimal code. For example, a value FF corresponds to 255 decimal, so the ASCII character for code no. 255 is the correct interpretation. The transformation of all characters provides the valid image.

Sample Data

Request

https://api-eu.dhl.com/parcel/de/tracking/v0/shipments?xml=

<?xml version="1.0" encoding="UTF-8" ?>
<data appname="userid"
         password="password"
request="d-get-signature
         zip code= zip code
piece-code="tracking number"
         date-from="20 23 -0 1 - 0 1"
date-to="20 23 -0 3 - 31 ">
</data>

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data name="signaturelist"
	code="0"
	request-id="379d9788-5a8e-49dd-9f7e-d30e17746c2a">
	<data name="signature"
		event-date="11.03.2012"
		mime-type="image/gif"
		image="4749463 ¿ 3b" />
</data>

Calling the "Track" function (DHL shipment tracking for private customers) via an HTTP direct call link.

Syntax description:

Technical description of the HTTP direct call link.
URL: https://www.dhl.de/en/privatkunden/pakete-empfangen/verfolgen.html

To test our API, you can download our test suite here.

You can obtain the well-known API tool Postman here: Postman API Platform | Sign Up for Free: 

To use it, the following steps have to be done:

• Request access to the sandbox environment and obtain an API key (see Get Access for more details)
   
• Import collection into Postman (see official documentation Postman Learning Platform )
   
• Add "Authorization" with base64 encoded "username:password"
   
• Replace the value of the variable "dhl-api-key" with your personal API key

Important and useful information

• It is currently not possible to use the "get-status-for-public-user" operation with the test-suite.Also, multiple shipment numbers in a request cannot be processed in the test-suite.
   
• The tracking API works exclusively with the GET method. Please consider this accordingly during development.
   
• The test suite works in the sandbox environment exclusively with the shipment numbers provided and stored by us:
  00340434161094042557 
  00340434161094038253
  00340434161094032954
  00340434161094027318 
  00340434161094022115
  00340434161094015902
   
• The data returned in the response are partly raw data, which may still have to be prepared for the end customer.

In order to be able to assign the abbreviations of the individual events precisely, or to enrich a self-explanatory explanation, we recommend that you download the table provided here with the various combinations in the current version.

Appendix: ICE_Event_RIC_Combinations_03_2023.csv

Why do I not receive information about the DASS Business functions for valid shipment numbers?

Since detailed information (address data) is made available via the business functions, business customers may only see the shipments that are relevant to them. A check is made here to see whether the shipment is in the customer's number range. If this is not the case, the shipment search is unsuccessful.

Why are shipments not marked as delivered after a long time, even though some have definitely been delivered already?

These shipments are exclusively international shipments. Depending on the destination country, sometimes a shipment can be in transit for more than 3 weeks. Added to this is the fact that some partner countries do not send us any feedback about the delivery. We are doing our best to gradually improve this exchange of communication, however.

When I submit a DASS query, why do I receive the message "The request sent by the client was syntactically incorrect ()."?

Check the request again carefully. The cause is usually a small typing error in the request itself. This may be a missing opening quotation mark or an unclosed element. Also check that you are using the right URL for the function call. A distinction is made between business and public.

You can request support in our Help Center. You can raise a ticket that allows you to request direct support from DHL Support. Please describe your enquiry in as much detail as possible and also send us reproducible extracts from the web service communication. We will try to help you with your problem as soon as possible during following times:

IT Customer Support & Integration Parcel

Business hours: Mo-Fr 8:00 am to 16:00 pm 

Conditions of Acceptance

This legal notice does not replace and/or modify the applicable "DHL Parcel General Terms and Conditions for Business Customers" available at https://www.dhl.de/de/geschaeftskunden/paket/rund-um-den-versand/agb.html or any other shipping service contracts applicable to your parcel shipments.

This Legal Notice does not replace and/or modify the applicable "DHL Parcel General Terms and Conditions for Residential Customers" available at https://www.dhl.de/de/privatkunden/information/agb.html or any other shipping service contracts applicable to your Parcel Shipments.

If you are acting as a third party software provider, vendor, marketplace operator or otherwise acting as a commercial agent on behalf of DHL and/or its affiliates, i.e., with the consent of DHL and/or its affiliates, you are required to advise the customer (i.e., the applicable shipper of the shipment) of the applicable shipping terms.

You may use the Services and/or data obtained through the DHL Paket DE Shipment Tracking API only for lawful contractual purposes and only in connection with your or the shipping customers' DHL shipments.

The following requirements and/or restrictions apply to the use of and/or access to the DHL Paket DE shipment tracking API:

• Use of access data for DHL shipment tracking (zt-identifier, password). In the case of shop software providers and marketplaces, it must be possible to enter this access data individually for each mail order company.
• Transfer of the access data in the XML request
• The number of queries per client must not exceed the following limits:
  • per day (between 12:00 a.m. and 11:59 p.m.) max. 1,000 queries with a total of 10,000 shipments
  • max. 3 requests per second
• The shipment status may not be queried again for shipments that have already been delivered..
• When integrating the DHL Paket logo in web applications, the logo specifications at https://www.dpdhl-brands.com/de/dhl/logo-and-claim must be observed.