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)
   
   Pickup orders at agreed locations require a corresponding configuration of the locations in the DHL systems - these must be available in the Post & DHL Business Customer Portal (GKP). Please check all possible agreed pickup locations and information before placing pickup orders.
    
2. Pickup orders at any address in Germany (additional costs per pickup-order and -attempt)
   
   Pickup orders at any address in Germany (Einzelabholung  orders) require a valid billing number which is configured in the customers’ GKP. In case the service "Einzelabholung order with label printing" (DHL delivery person brings the shipping label with him/her to pickup) is used a billing number in procedure 08 (DHL Retoure with pickup) must be configured in the GKP.
3. Query all agreed pickup locations assigned to the user

   All pickup locations assigned to the user for “pickup orders at agreed pickup locations” can be queried.

4. Query details and state of a pickup order
   
   The user can query the details of an assigned pickup order. He also receives information about the current state of the entire pickup and, depending on the pickup type, the detailed pickup state for each shipment.

State of pickup (orderState):

State of shipments (shipmentState ):
 

Requirements

To place pickup orders using the API Pickup, the following requirements must be met:

• Business customer contract with DHL Paket GmbH
• At least one user for the Post & DHL Business Customer Portal (GKP) with access rights for function "Pickup"
• Depending on the use case, at least one contractually agreed pickup location, or a billing number configured for the GKP user

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. Shipment pickup at an agreed pickup location
2. Shipment pickup at any address in Germany

Shipment pickup at an agreed pickup location (costs are included in the parcel price)

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

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

• Bedarfsabholung by the delivery driver (usually up to 10 parcels) 
• Einmalige Abholung as a planned pickup tour (for more than 10 parcels/day or bulky goods)

Bedarfsabholung (Pickup at agreed pickup locations)

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 10:00 pm 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.  Einzelabholung order with label printing)
• Usually there is a pickup scan per parcel

In case there are more than 10 shipments per day/location, the pickup order is changed to a Einmalige Abholung order.

Einmalige Abholung (Pickup at agreed pickup locations)

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

• Pickup location must be agreed with DHL sales
• Pickup orders for the next day possible 
• Collection orders can be placed for the next day until 12:00 pm Monday to Friday
• Execution has to be confirmed by DHL
• Execution with a separate pickup tour
• Execution usually possible MO-FR, Saturday not in all regions
• Pickup of more than ten parcels per location/day or bulky shipments. Shipments must be in wheeled trays, swap bodies or on pallets.
• Cannot be combined with additional pickup services (e.g.  Einzelabholung order with label printing)
• No pickup scan for each parcel

The Einmalige Abholung is just a request of a pickup to the DHL transport coordination - a pickup on the desired collection day is not automatically booked. If an email was specified in the pickup order and the “sendPickupConfirmationEmail” notification was selected, the business customer will be informed of the result of this check by email.

A further bilateral communication may be required.

The status of a pickup can also be seen in the Post & DHL Business Customer Portal or by querying the API.

Shipment pickup at any address throughout Germany (Einzelabholung order (paid service))

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

• Pickup up to 10 parcels or bulky goods per location/day
• Pickup orders for the next working day have to be placed until 10:00 pm 
• Pickup possible Monday-Saturday
• 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. Einzelabholung order with label printing" possible
  • DHL prints and brings the transportation label
  • In case a pickup is not possible, the transportation label is put in the letterbox
  • A billingnumber n procedure 08 is required to book the service
• Cancellation for a next-day order possible until 10:00 pm
• Pickup-scan for all parcels
   

Adresses

• Pick-up location: 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 by the client via: https://www.dhl.de/nochmal-zustellen
 

Pickup dates

Shipment pickup at any address throughout Germany and Bedarfsabholung:

• can be ordered & cancelled until 10:00 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 6:00 pm
• the booking of time windows is not available
• the pickup-timeframe is announced only on the pickup-day
• If an email address and the notification type “sendPickupTimeWindowEmail” are selected in the pickup order, the collection period can be announced by email on the pickup day, if available

Einmalige Abholung

• can be ordered Mondays to Fridays until 12:00 pm for the next working day (exception: Saturday)
• orders for Saturdays have to be placed on Thursday until 12:00 pm latest if a pickup is possible on Saturday in the ZIP code area
• availability is checked by the DHL transport coordination - the customer can be informed about this by email or find out the state in the Post & DHL Business Customer Portal (GKP) and via API
• can be ordered for up to 14 days in advance
• pickup-timeframes are not possible
• pickup usually in the morning, opening times will be considered 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 shipment pickup at any address throughout Germany. 

Bulky goods

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

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:  https://www.dhl.de/en/geschaeftskunden/paket/leistungen-und-services/services/service-loesungen/sperrgut.html

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 pickup address.

Shipping number/tracking-id

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

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 " Einzelabholung order with label printing", the shipment number will be provided by DHL.

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

Use the "GetAccess" button (this will pre-populate this API if you create an app) or add the API to an existing app.

Approval is manual for the API production environment. You will receive a notice, once your APP has been approved.

Here you can find more help on how to register an app.

Authentication

Access Token

To access the API resources of the Post & Parcel Germany APIs, you must first verify yourself against our Authentication API. In exchange, you will receive the Access Token required for further requests. Please follow the instructions of the Authentication API (Post & Paket Deutschland) to get an Access Token.

Please note: You've been allready granted to use the Authentication API (Post & Parcel Germany) automatically, when you have access to this specific API. There is no further action required on your part.

Sandbox

To use the "DHL Parcel DE Pickup API", you will first need an application created including the API in sandbox mode, like described in Get Access.

You have the possibility to use our sandbox environment with following business customer user data:

Username: "user-valid"
Password: "SandboxPasswort2023!"
Description: Valid Business Customer User

Username and password can be used in the Authentication API to obtain an Access Token.

The following curl command illustrates how to obtain a token and use the Parcel DE Pickup API:

curl -k -i -X POST -H "accept: application/json" -H 'content-type: application/x-www-form-urlencoded' https://api-sandbox.dhl.com/parcel/de/account/auth/ropc/v1/token -d 'grant_type=password&username=user-valid&password=SandboxPasswort2023!&client_id=KH2iQ8YwGYtGs4XUBKaGaiyWBPEZnsRm&client_secret=V8yPDt8GlGlNMRCh'

Once you have valid Access Token you can request the Pickup API:
Try out basic access by querying the API version (without Access Token):

curl -H "accept: application/json" https://api-sandbox.dhl.com/parcel/de/shipping/pickup/v1/ Query information for your receivernames (with Access Token): curl -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json"  https://api-sandbox.dhl.com/parcel/de/shipping/returns/v1/locations

A detailed description of the Pickup API can be found in the "Open API Specification".
You can download the "Open API Specification" here.

Production

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

Your business customer username and password can be used in the Authentication API to obtain an Access Token.

When selecting the respective business customer user: For security reasons it is recommended to use a "system user", because it is not possible to log on to the Post & DHL Business Customer Portal with a "system user".

Important: DHL contract customers receive the access data for access to production from the Post & DHL Business Customer Portal via DHL Paket sales.

To determine the pickup locations, please use the /locations function via API call.

Hints:

• For shipment pickup at any address throughout Germany: In the GKP you can look up which billing numbers/account number are available for a user
• First call up the personal data in the menu (1.), then select "Pick up" (2.) 

Please note:

• Pickup orders can only be placed for German addresses
• Shipment pickup at any address throughout Germany are billed even if they are not successful. Pickup costs for agreed pickup locations are included in the parcel price, therefore they have to be contracted in advance.

We recommend:

• A billing number/account number in procedure 08 for pickup orders at any address throughout Germany (Einzelabholung orders). This enables the option to use the service "Einzelabholung order with label printing".
• 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"

Environments

The addressable API base URL/URI environments are:

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.