To make use of the PostNL Pakketten API we offer a sandbox environment that is functionally identical with the live environment. Below you can find information about how to start.
Our web services are easy to use to meet your shipping needs. To get an idea of the PostNL Pakketten API’s, it is recommended to read the Instructions and take a look at the Documention page(s).
Get your API key
To make API requests you will need an API key for the sandbox environment. API keys are unique codes that identify you or your application each time you make a call to one of our API’s. After registration, you will be handed credentials within a working day.
The received API key can give you access to all the PostNL Pakketten API’s; barcode, labelling, confirming, shippingstatus, deliverydate, timeframe and location webservices. With the credentials you can run sample requests, use the simulators and/ or make a start developing your connection(s) to the PostNL Pakketten API’s.
Run sample requests
You can access the PostNL Pakketten API without writing any code. With the API key and the documentation on this website you can run sample requests, use the simulators and/ or start developing your connection(s) to the PostNL API.
The easiest way to test connectivity and experience the input and output responses from our API’s is to use an API testing tool like SOAPUI. You can find the SOAPaction url in the wsdl's of the webservices.
You can also use the simulators url’s to see how the webservice(s) work. You can find the simulators url’s at Call details on the Documentation pages of the webservices.
Connect to the services
To integrate the API’s into your website, e-commerce platform and/or backend application(s), you have to use a production account. After registration to become a PostNL customer you will be given personalized login credentials and receive further instructions.
Do you already have a PostNL Pakketten contract number and you don’t use the PostNL Pakketten API’s? Please contact your Account Manager or fill out this form.
Read the documentation
Get familiar with our API documentation. The detailed essential information common to all of our services. You need to be aware of these conventions before integrating any of our services.
Go to production
When you become a customer you receive a personal customer code/number and further information. The Sandbox environment must be used again in order to validate the implementation is finished without errors. IT support of PostNL Pakketten will validate your sandbox implementation.
IT support will approve the move to production and will provide you with credentials that can be used in the production environment. Then, the service endpoints can be renamed from their sandbox Uri to the production Uri and the implementation is complete.
You can implement a (customized) integration of PostNL API's based on your particular system, platform and software. Implementation requires expertise and resource. To ensure you integrate the webservices properly to your business system and/or webshop, it is recommended to be done by (a) qualfied developer(s).
What is the PostNL Pakketten API?
The PostNL API offers you, customer or software partner of PostNL Pakketten, a real-time, flexible and modern platform for shipping services. The platform offers these services as webservices that can be used by customers and external systems to fulfil shipping needs. PostNL Pakketten wishes to support her customers to realize a further integration into their supply chain with PostNL Pakketten applications.
The PostNL Pakketten API focuses on supporting customers that have built a dedicated shipping system to be used for shipping via PostNL. Using the PostNL API, real-time interaction is made possible and direct feedback and validation of information are key advantages of the PostNL API.
How does the PostNL Pakketten API work?
After registration via account management and IT support, customers will be connected to PostNL API. This connection consists of backend services, delivery options services and a track and trace service. Each service is described separately so customers can connect to these services and integrate this with other IT applications. Also, customers will be given login credentials which are personalized per customer.
The base endpoint of PostNl API is a publicly accessible internet address (Uri). The communication with the endpoint is secured and will be handled via HTTPS. The Uri also contains the requested functionality and version of the service.
Each service has an own version and is part of the endpoint Uri. This means that a set of used services contains different versions. A version changes when the interface specification changes. When introducing a new version, the old version will be maintained for a certain period. Sometimes an upgrade of a certain webservice is required. PostNL will give you a reasonable period of time to update.
Communication with PostNL API
Communication with PostNL API will occur over HTTPS. SSL 3.0 encryption will be used via a SSL certificate. The SOAP protocol is used to call the services and receive information of a service. SOAP 1.1 must be used to send and receive the messages. The content encoding is done in UTF-8 format.
Use of services
Calling a service
A service is called by sending a SOAP message to a service endpoint. The SOAP message contains a SOAP header with security information (username / password) and a SOAP body which contains the service method and related parameters.
Each message that is received by the API is authenticated and authorized. The authorization mechanism determines if the user has access to the requested service. The access is aligned with the services that have been agreed between PostNL Pakketten and the customer.
After processing the request, the service will return a SOAP message with a response. The SOAP message contains a SOAP body with information.
Parameter specification / field order
For each API, the parameters of a service are specified. Also, the behavior of these parameters are detailed, for example if a parameter is mandatory a [M] is shown. If the parameter is optional the description is [O].It is important to maintain the exact order of the fields as specified in the XSD. Changing the order of fields is not allowed and will result in unspecified errors returned back at the client.
Username / password
Each service is secured with a username and password. To enable this, the UserNameToken profile is used. This is part of the WS-Security specification. This profile has the possibility to send the username and password in the SOAP header of each message. There are no special security measures necessary in the HTTP header.
An example of a SOAP header is given below:
<wsse:Password>password (sha1 hash)</wsse:Password>
The password must be encrypted. The encryption must be done with the SHA1 algorithm.
The password must be encoded in UTF-8 first and must be hashed with the SHA1 algorithm. The hash must be sent in lower case.
To offer your customers an optimal choice in where and when they want to receive their parcels, you can implement the PostNL delivery options in the webshop checkout. There are several delivery options for both home delivery and pick up.
If you want to implement the PostNL delivery options, it is recommended to make use of all three frontend webservices; Deliverydate, Timeframe and Location.
You can find more information about the products and delivery options at the Products page of the labelling, confirming and barcode webservice. Here you can also find out which product codes and options can/ must be used for various products of PostNL. In case you also create labels and/or send confirmations by using the API(’s).