Best for:
- Validate postnumbers to ensure deliverability of shipments to the corresponding person at Packstation parcel lockers.
You are on the documentation page of the Parcel DE Postnumber API of Post & Paket Deutschland.
- An Overviewof the business functions covered via the API
- Thetechnical documentation of the API
- The User Guide contains topics of connection and authentication
- Open API Specification and code examples in Reference Docs
- Find further Use Cases, FAQ, Support Contact and a Postman Testsuite in section Additional Information
- Latest Release Notes
Scope
With DHL Parcel DE Postnumber API, we use postnumbers to identify registered customers. Postnumbers will be used to address the right account while creating a shipping label. Customers need to create an account and validate their identity with dhl.de or the Post & Paket app to receive shipments at the Packstation (which is a 24/7 locker service for receiving parcels unattended).
Shipments addressed to an incorrect postnumber will be refused from the Packstation locker during last mile delivery which may produce unnecessary cost and causes poor customer satisfaction.
Prerequisites
To use the API, the following prerequisites must be fulfilled:
- A valid business customer contract with DHL Paket GmbH
Using the API
The DHL Parcel DE Postnumber API enables you to:
- You can post customers prename, lastname and postnumbers
- API will respond with either status “true” (correct/shipping can be addressed to this name and postnumber combination) or “false” (not found)
- API users can build their individual rules based on the response (e.g. validating form inputs in ecommerce checkout processes)
The following provides an overview on how to get access to the API.
- Technical Details on the API calls can be found here: "Reference Docs".
- Further hints on API usage are given in the sections "Support" and "FAQ".
Get Access
Register your Parcel DE Postnumber API and get your API subscription keys:
To register your app 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 this API. Please check back regularly. If you require very urgent approval, please raise a request via the contact form.
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
You have the possibility to use our sandbox environment with different functional states of user data:
Username: "user-valid"
Password: "SandboxPasswort2023!"
Description: Valid Business Customer User
Username and password can be used in the Authenticatin API to obtain an Access Token.
The following curl command illustrates how to obtain a token and use the Postnumbers 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=lr8wTCJjcNnNL9HVYxQYTO6NGqlcGIGg&client_secret=hz0ofecvbAaEJxWF'
Once you have valid Access Token you can request the Postnumbers 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/account/postnumbers/v1/
Query information for a customer (with Access Token):
curl -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" https://api-sandbox.dhl.com/parcel/de/account/postnumber/v1/customers/871902603 --data '{"firstname" : "Max","lastname" : "Mustermann"}'
Valid Postnumbers in our Sandbox Environment are:
- Erika Mustermann with Postnumber 872467133
- Max Mustermann with Postnumber 871902603
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 (client_id) and an API secret (client_secret). 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 variables API key (client_id) and an API secret (client_secret) with your personal API key values.
Please also see our step-by-step instructions on how to use the Postman Test Collection.
Use Case Overview
Please refer to the following example requests:
Example Requests
Customer with Postnumber
POST /parcel/de/account/postnumber/v1/customers/871902603
Host: https://api-sandbox.dhl.com
Content-Type: application/json
Authorization: Bearer t0g1--EXAMPLE-TOKEN-qtqtm3
{
"firstname" : "Max",
"lastname" : "Mustermann"
}
Response:
{
"valid": true
}
Customer with invalid Postnumber
POST /parcel/de/account/postnumber/v1/customers/871902602
Host: https://api-sandbox.dhl.com
Content-Type: application/json
Authorization: Bearer t0g1--EXAMPLE-TOKEN-qtqtm3
{
"firstname" : "Max",
"lastname" : "Mustermann"
}
Response:
{
"valid": false
}
Customer with wrong prename
POST /parcel/de/account/postnumber/v1/customers/871902603
Host: https://api-sandbox.dhl.com
Content-Type: application/json
Authorization: Bearer t0g1--EXAMPLE-TOKEN-qtqtm3
{
"firstname" : "Mark",
"lastname" : "Mustermann"
}
Response:
{
"valid": false
}
Authentication
What kind of authentication is required to use the Postnumber API?
Please refer to section "Authentication".
Understanding API Response
Why does it return "false" even though the account is registered under the same name and correct postal code?
There can be several reasons for this:
• The customer is registered but has not yet booked the Packstation service or has not completed the identification process required for the Packstation service using an ID or address TAN.
• The spelling of the name differs from the spelling in the DHL customer account. Check if a different first name and/or last name is being used (some people have multiple first names and use them differently).
• The customer provided a nickname during registration for a DHL customer account or when entering the address in the validation form, e.g., "Loki" instead of "Hannelore" or "Rosi" instead of "Roswitha."
• Check if the first and last names are being used in the correct order.
• A title is provided (e.g., Dr., Prof., Graf) that was not provided during registration for a DHL customer account.
• The customer has provided only an abbreviation as the first name for addressing purposes (e.g., "H. Schmidt").
• The customer identified themselves with an ID card for the DHL customer account, and DHL has taken a different official last name than the one used by the customer in daily transactions (e.g., "Katrin Edle von Giesheim Halbertshausen zu Schreckstein" uses the name "Katrin von Giesheim" in daily transactions).
• Name change due to official measures (e.g., marriage, gender reassignment, unreasonable name) that has not been stored or updated in the DHL customer account.
What are the most common reasons for a "false" result?
The most common reasons are improper use of the customer account (multiple family members using the same account, addressing to a Packstation without being enabled for the service):
• The customer tries to use the Packstation account of a roommate/partner, etc., but orders under their own name.
• The customer is not (yet) a customer of DHL or has not yet booked the Packstation service. In this case, they still receive a postal code that, for example, serves direct addressing to a branch.
• Typo in the postal code.
What business logic does DHL recommend when the API returns "false"?
This depends on the sensitivity of the shipped goods. For general goods, we recommend using the API only for pre-validation and providing the end customer with a notification that the shipment may not be deliverable.
If applicable, offer your customers the option to bypass the validation and set up a warning message. You can also split the string of a name and query them against the API one by one.
Why doesn't DHL use "Fuzzy Logic" or similar to return "true" for names that are likely similar?
Some of our business customers have strict requirements for recipient identity verification because the delivery must not be delivered to third parties (content sensitive, subject to credit or identity checks). For this reason, we allow business customers to perform a precise validation before shipment and build their own business logic on top of it.
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 a.m. to 16 p.m.
Please note the terms of use here.
1.0.0
- Initial service for Postnumbers launched