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 by copying the endpoint.
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.
Error handling
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.
Street, HouseNr and HouseNrExt
The element StreetHouseNrExt is a combination of Street, HouseNr and HouseNrExt. This field has a dependency with the field Street. One of both fields must be filled mandator.
This field can be used in case the values of Street, HouseNr and HouseNrExt can’t be mapped separately before calling the API.
The API will calculate a split of street name, house number and extension for you, and will afterwards use the split values. This might result in incorrect behavior for which PostNL can’t be held liable. Content in this field must be in the described order or otherwise the conversion will not work and place all values in the Street field.
Multiple shipment (Multi-collo)
Multiple shipments can be sent in one request. To this end the Shipment field has been replaced by a Shipments field, which contains a list of Shipment elements. The response has also been modified. Instead of a ResponseShipment element, the response now consists of a GenerateLabelResponse element, which has a ResponseShipments field containing multiple ResponseShipment elements.
A maximum of four Shipment elements can be included in the Shipments field. When sending multiple signature images, keep in mind that the maximum size for the entire request is 200 KB.
You can use this functionality with the GraphicFile|PDF|Merge printer types to generate one label document containing multiple labels. These "merged label" documents can be found in the MergedLabels response field.
If you want to send only one shipment, you have to specify the Shipments element containing one Shipment.
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.
Pickup Basic and Plus
Pickup plus products consist of two Shipments, the collection order and the delivery order. Both orders must be placed in a separate Shipment in the request. This means that a request for a pickup plus product will contain two Shipment segments. You can find more information at the Products page (Pickup service).
Destination EU / Rest of World
When separating Shipping/ Labelling and confirming for combilabel product codes, there are some fields from the response that need to match with the Confirming request. These fields concern the network partner data. The following fields from the Shipping or Labelling response need to be matched with the Confirming request:
• Barcode
• DownPartnerBarcode
• DownPartnerID
• ProductCodeDelivery
The Customs type is mandatory for ‘Parcels non-EU” (Rest of World) shipments and recommended for shipments with destination EU and not allowed for any other shipment types.
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.