You are on the documentation page of the DHL Parcel DE Pickup API of Post & Parcel Germany. In the following chapters we offer you:

• An Overview of the business functions covered via the API
• The technical documentation of the API
  • The User Guide contains topics of connection and authentication
  • Postman Collection
  • Open API Specification and code examples in Reference Docs
• Find further Use Cases, FAQ, and Support Contact in section Additional Information
• Latest Release Notes

Scope

Customers are enabled to place:

1. Pickup orders at predefined locations in Germany (pickup costs are included in the parcel price)
2. Pickup orders at any address in Germany (additional costs per pickup-order and -attempt)

Pickup orders at predefined locations require a corresponding configuration of the locations in the DHL systems - these have to be available in the Post & DHL Business Customer Portal (GKP). Please check all possible pickup locations and information before placing pickup orders.

Pickup orders at any address require a valid billingnumber/accountnumber which is configured in the customers GKP. In case the service "Label" (DHL brings the shipping-label) is used there must be a billingnumber/accountnumber in procedure 08 (DHL Retoure with pickup) configured int the customers GKP.

Prerequisites

To place pickup orders using the API Pickup, the following prerequisites must be fulfilled:

• a business customer contract with DHL Parcel Germany
• a user for the GKP with access rights for function "Pickup"
• Depending on the usecase at least one contractual agreed pickup place or a billingnumber/accountnumber which is configured for the GKP user

You can view which billing number is authorized for order pickups (more specifically which one is authorized for the function "Pickup" in Post & DHL Business Customer Portal) at the Post & DHL Business Customer Portal in the menu "My Files" following the tab "Pickups".

Using the API

Pickup types

Depending on the number and characteristics of parcels and the location where the pickup should take place, different services can be ordered via the pickup API

1. Parcel pickup at a predefined location
2. Parcel pickup at any address

Parcel pickup at a predefined location (costs are included in the parcel price)

Requires at least one pickup location for the used customer number (EKP) which is contracted with DHL and configured in the DHL GKP system.

Depending on the number or characteristics of parcels the pickup will take place as

• Parcel collection on request by the delivery driver (usually up to 10 parcels) 
• Singular collection as a planned pickup tour (for more than 10 parcels/day or bulky goods)

Parcel collection on request

For customers who do not have a regular (daily) pickup by DHL.

• Pickup location must be agreed with DHL sales
• Has to be ordered until 10pm the day before the pickup
• Possible pickup Monday-Saturday
• Pickup by the DHL delivery driver in the regular delivery tour
• Max. 10 parcels/day and location
• No bulky goods
• Costs are included in the parcel price
• Cannot be combined with additional pickup services (e.g. labelprint by DHL)
• Usually there is a pickup scan per parcel

In case there are more than 10 on demand pickup-orders per day/location, the pickup order is changed to a one-time pickup order.

Singular collection

For customers who do not have a regular (daily) pickup by DHL and want to order a pickup for more than 10 parcels, bulky goods, or who want the pickup for higher volumes in addition to their regular pickup

• Pickup location is agreed with DHL
• Pickup orders for the next day  possible Monday to Friday until 12am
• Execution has to be confirmed by DHL
• Execution with a separate pickup tour
• Execution usually possiible mo-fr, Saturday not in all regions
• Pickup of more than 10 parcels per location/day or bulky shipments. Shipments have to be in wheeled trays, swap bodies or on pallets.
• Cannot be combined with additional pickup services (e.g. labelprint by DHL)
• No pickup scan for each parcel

The one time pickup is just a request of a pickup to the DHL transport coordination - a pickup on the desired collection day is not automatically booked. The DHL transport coordination checks the availability and informs the customer via email (to the email address defined in the Post & DHL Business Customer Portal for the location). A further bilateral communication may be required.

Parcel pickup at any location in Germany (individual collection order (paid service))

Requires at least one billingnumber/accountnumber configured for the user in the Post & DHL Business Customer Portal.

• Pickup orders for the next working day have to be placed until 10 pm 
• Pickup up to 10 parcels or bulky goods per location/day
• Pickup possible mo-fr
• Pickup by the DHL delivery driver
• Pickup possible at any codeable address in Germany
• Chargeable, even if the pickup is not successful
• Additional, chargeable service "labelprint by DHL" possible
  • DHL prints and brings the transportation label
  • In case a pickup is not possible, the transportation label is put in the mailbox
  • A billingnumber/accountnumber in procedure 08 is required to book the service
• Cancellation for a next-day order possible until 10pm
• Pickup-scan for all parcels

Adresses

• Pick-up address: address, at which the shipment shall be picked up
• Target address (only if label printing is ordered): address the shipment shall be delivered to

Pick-ups cannot be ordered for the following pick-up addresses:

• large receiver addresses ("Grossempfaenger")
• Post Offices
• DHL Packstations
• DHL Parcel Shops

Please note: If a shipment is stored in a DHL Parcel Shop or a Packstation, a new delivery can be ordered via: https://www.dhl.de/nochmal-zustellen

Pickup dates

Individual collection orders and parcel collections on request:

• can be ordered & cancelled until 10 p.m. for the following working day
• can be ordered for up to 14 days in advance
• can be fulfilled Mondays to Saturdays from 8:00 am to 7:00 pm
• the booking of time windows is not available
• the pickup-timeframe is announced only on the pickup-day
• In case an email address is placed in the pickup order, the pickup-timeframe is announced per email on the pickup-day

Singular collections

• can be ordered Monday to Friday until 12am for the next working day (exception: Saturday)
• orders for Saturdays have to be placed on Thursday until 12am, in case a pickup is possible on Saturday in the ZIP code area
• availability is checked by the DHL transport coordination - customer is notified on the result
• can be ordered for up to 30 days in advance
• pickup-timeframes are not possible
• pickup usually in the morning, opening times will be taken into account where possible

Hint:

It is possible to put "asap" as pickup day in the API-request. In this case a pickup-order is placed for the next possible day. This day is delivered back in the API-response.

Services

Services are only possible for individual pickup orders at any address

Bulky goods

For the collection of bulky goods, the field "Comment on bulky goods" is a mandatory field and must be filled.

Please note: The definition of bulky goods is listed in the FAQs. Further details on DHL Paket's business customer products and services can be found at: www.dhl.de

Label printing

The shipping label can be created by DHL's label printing service. For that, a valid German destination address must also be specified in addition to the collection address.

Shipping number/tracking-id

If label printing by DHL was not ordered, the shipment must already have a valid shipping label for successful collection.

If no shipment number is provided when the order is placed, a shipment number from DHL's central number range will automatically be used.

Please note:

• When ordering pick-ups, always hand over the shipment number of the parcel; this makes it easier to identify the shipment that shall be picked up
• When using the service "labelprint by DHL", the tracking-number must be from a range provided by DHL and has to be of type Identcode (12 digits tracking-id)

Further information and recommendations

• A DHL product can have several billing numbers or participations, for example, to differentiate between locations, clients, or promotions. We recommend that shop software providers and marketplaces set up several fields for entering billing numbers or participations in these cases.
• If you, as a marketplace or shop software provider, do not want to connect all DHL products and services via the API, we recommend that you also integrate a direct call link to the Post & DHL Business Customer Portal, via which you can call up the "Pickup" function.

The following provides an overview on how to get access to the API.

• Technical Details on the API calls can be found in "API Specification".
• Further hints on API usage are given in the sections "Support" and "FAQ".

If you implemented the previous parcel pickup API, please notice the changes under Release Notes.

Get Access

How to register your DHL Parcel DE Pickup API and get your API subscription keys:

1. Click Get Access Button on top of this page and the create App form will open with the sandbox environment of the API being pre-selected.
2. If required, change selection to "DHL Parcel DE Pickup API"
3. When you have completed the form, click the Create App button.
4. You will now find your App under My Apps.
5. From the My Apps screen, click on the name of your app.
   The Details screen appears.
6. If you have access to more than one API, click the name of the relevant API.
   Note: The APIs are listed under the "Credentials" section.
7. Click the Show link below the asterisks that are hiding the Consumer Key.
   The Consumer Key appears.

Every call to the API requires a consumer key. This key needs to be specified in the request header (DHL-API-Key).

Please note that different keys are required for sandbox respectively production environment. Both can be requested via above procedure and copied from API credentials section.

Alternatively to "get access" you can go to My Apps on the portal website and click the + Create App button:

• The "Create App" form appears.
• Complete the Create App form and select the "DHL Parcel DE Pickup API".
  • You will find two entries of the API in the list: one for Sandbox, one for Production use.

Authentication

Sandbox

To create collection orders in the sandbox, you have the option of using our test suite with the following user data:

• Username: 2222222222_abr_0801
• Password: S8PjmLB!s2vrzWV3o
• Above given username and password must be provided via basic authentication (Basic Auth).

You can download the "Open API Specification" here: 

To create test collection orders only the following customer details can be used:

• Billingnumber for individual collection orders: 22222222220801
• Customernumber for pickup at requests and singular collections: 2222222222

Production

To use the "DHL Parcel DE Pickup API", you will first need an application created including the API in production mode.

In addition, the following access data for the webservice (API) must be specified:

• User: "User from Post & DHL Business Customer Portal (GKP)".
  (User must be authorized for pickups!)
• Password: "Password of above user".
• Your active business customers user and password values must be provided via basic authentication (Basic Auth).

When selecting the respective user, please also consider the duration of the validity of passwords:

• the password validity of a "user" is" 90 days
• the password validity of a "system user" is" 365 days

It is not possible to log on to the Post & DHL Business Customer Portal (GKP) with a "system user".

 Requirements for production

• A valid business customer contract with DHL Parcel
• A valid user for the Post & DHL Business Customer Portal (GKP) with access rights for function "Pickup"
• Depending on the use case at least one prearranged pickup location or configured billingnumber/accountnumber for the GKP-user 

Please provide the Post & DHL Business Customer Portal (GKP) user name in lower case letters only.

Hints:

• For pickups at any location: In the GKP you can look up which billingnumbers/accountnumber are available for a user

Please note:

• Pickup orders can only be placed for German addresses
• Pickup costs for prearranged locations are included in the parcel price, therefore they have to be contracted in advance
• Pickup-orders for any location (not prearranged) are billed even if they are not successful  

We recommend:

• A billingnumber/accountnumber in procedure 08 for pickups at any address. This enables the option to use the service "Labelprint by DHL".
• A GKP user with role "systemuser" - for such users a password changes is only required once a year (personal user: 3 month)
• For pickups at prearranged locations: Please check all available pickup locations and the information for these in the GKP. For this a GKP user is required with access rights for "Pickup" and in addition "Settings"

Status Codes and Error Codes

The following table lists the possible status codes for the execution information of pick-ups:

Response Codes

We recommend using the Postman software to test our APIs. Postman is a collaboration platform for API development and testing. Post & DHL Germany provides you a comprehensive Postman collection for every single API. You can download the complete API collection, import it into your Postman work space and get started quickly on your integration with our APIs.

The following steps must be performed to test the API beforehand:

You must request access to the sandbox environment to obtain an API key (dhl-api-key).
You can find detailed instructions on how to do this under Get Access.

Setting up the Postman Test Collection

• Download the Postman test collection from the download section.
• Import the Postman Test Collection (see official documentation of the Postman learning platform)
• Replace the value of the variable "dhl-api-key" with your personal API key.

Please also see our step-by-step instructions on how to use the Postman Test Collection.