Why use the Confirming API
Information of the parcels
The confirmation contains information about the sender and receiver, the destination (city and country) and any additional delivery services applicable.
Confirming parcels
Let PostNL know that the parcels are coming in the distribution process for a smoother process by matching the information and the labels.
Shipping or Labelling without confirm
Usually the confirming is sent along with creating a label. If you need more time to process the parcels after picking and packing and you don't want consumers to be able to trace the parcels already.
Get started
Documentation
View our exhaustive documentation.
Postman
All of our API's available as Postman collections.
Github
Find PostNL on Github.
Sandbox
Test your integration on our Sandbox environment.
Guidelines
Learn more about the Confirming API guidelines.
Confirmation
The Shipping and Labelling API contains the possibility to create a label and the PostNL confirmation. If you choose to use confirm the shipments after creating a label, you can use the Confirmation API.
Implementing the confirming functionality as early in your process as possible is highly suggestible. Our best practice is that you implement this service call directly after the generation of the shipping label.
We would like to stress the need for a suitable error handling implementation on your side. If somehow, an error is received at your end upon sending your confirmation, this means that we could not process the information correctly and the successful delivery of the parcel is in jeopardy. We strive to return the error message with as much detail as possible so you can take proper action in order to improve the information about the parcel and retry.
Error codes have been specified in the API Generic document. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in API.
This field can be used in case the values of Street, HouseNr and HouseNrExt can’t be mapped separately before calling the API.
Multiple shipment (Multi-collo)
A parcel can be (part of) a single shipment or can be part of a multi-collo shipment. At the Group type you can specify that a parcel is part of a multi-collo shipment.
For shipments within the Netherlands multi-collo shipments can be created. Using the API, this can be done as follows:
• Connect the parcels by using the Group type in each request. Mention the amount of parcels in the shipment (GroupCount), the number of the specific Parcel (GroupSequence) and the main barcode of the shipment (MainBarcode) and specify Multicollo as the GroupType (GroupType 03)
• Multi-collo is available for Dutch domestic (with exception of Mailbox / Brievenbuspakje products)
For Extra@Home and Cargo shipments, the requests cannot be done separately for multi-collo shipments. Multi-collo shipments must be confirmed in one joint request.
Address type
PostNL internal applications validate the receiver address. In case the spelling of addresses should be different according to our PostNL information, the address details will be corrected. This can be noticed in Track & Trace.
The API will not add address details. Street and City fields will only be printed when they are in the call towards the Shipping or Labelling API.
The element Address type is a code in the request. Possible values are:
Code | Description |
---|---|
01 | Receiver |
02 | Sender |
03 | Alternative sender address |
04 | Collection address |
08 | Return address* |
09 | Delivery address (for use with Pick up at PostNL location) |
* When using the ‘label in the box return label’, it is mandatory to use an Antwoordnummer in AddressType 08. This cannot be a regular address.
Remarks:
Within the CustomerType, only AddressType 02 can be used. This Type can also be placed in the ShipmentType.
Within the ShipmentType, at least ShipmentType with 01 is required.
Shipment type
The element Shipment type is a code in the request. Possbile values are:
Code | Description |
---|---|
01 | Receiver |
02 | Sender (if not in Customer/Address) |
03 | Alternative sender address |
04 | Collection address |
08 | Return address* |
09 | Delivery address (for use with Pickup at PostNL location) |
* When using the ‘label in the box return label’, it is mandatory to use a Antwoordnummer in AddressType 08. This cannot be a regular address.
The following rules apply:
If there is no Address specified with AddressType = 02, the data from Customer/Address will be added to the list as AddressType 02. If there is no Customer/Address, the message will be rejected.
An Address with AddressType = 02 can be specified. In this case, no Customer/Address has to be specified.
At least one other AddressType must be specified, other than AddressType 02. In most cases this will be AddressType 01, the receiver address.
Contact type has the elements Email, SMSNr and TelNr. These fields have a dependency with each other. At least one of these three fields must be filled mandatory for certain products/ product codes (e.g. Evening/Sameday delivery, Pickup at PostNL location). Two or three can be filled as well.
Code | Description |
01 | Receiver |
02 | Sender |
Remark: Please add the e-mail address of the receiver to improve the Mijn PostNL experience of your customer.