Documentation REST

Shippingstatus webservice


  • Name: Shippingstatus Webservice.
  • Reason to Call: Receive status information about the shipments.
  • Input: Customer code, customer number, barcode or reference or timeframes in combination with status/phase codes.
  • Output: Status information about the shipment.


The following methods are defined within the Shippingstatus WebService.




Returns the statuses for a particular barcode

/v1_6/status/reference/{referenceId}Get status by reference id


Get status by 'kennisgeving' id

/v1_6/status/searchSearch shipments by reference, status or phase
/v1_6/status/signature/{barcode}Returns the statuses for a particular barcode

Call details


JSON Action (GET)

Interface Version


Sandbox endpoint

Sandbox Swagger

Production endpoint

Production Swagger

* If you already use the former SOAP API’s and/or you want to make use of the REST API’s, you can fill in theRequest for API keyform or contact your PostNL account manager to arrange this.




Release Date


Release Notes

Schema Changes



Juni 1, 2017


New additional methods:
CompleteStatusByReference, CurrentStatusByPhase,CurrentStatusByReference

and CurrentStatusByStatus (1.2)
Changed fields in CurrentStatus response:
Removed Shipments/Customer and Removed Shipments/ProductDescription (1.2)

Different namespaces (1.3)
Changed fields in CurrentStatus response:
Added Shipments/ProductOptions (1.3)
Changed fields in CompleteStatus response:
Added Shipments/ProductOptions (1.3)

Different namespaces (1.4)

The following fields have been added to the interface:
CurrentStatusResponseShipment/Warnings and CompleteStatusResponseShipment/Warnings (1.5)
GetSignature operation has been added to the interface (1.5)
Changes in response of an unknown Shipment (1.5)

The following fields have been added to the interface:
CurrentStatusResponseShipment/DeliveryDate, CurrentStatusResponseShipment/Expectation, 

CompleteStatusResponseShipment/DeliveryDate and
CompleteStatusResponseShipment/Expectation (1.6)



Use of the webservice
Please be aware that this service is meant for single requests about a parcel and not designed to update the status every single minute on all your parcels. This is important because the capacity of our network is limited. So, please ensure that this service is only called in useful intervals, and for relevant shipments only. PostNL suggests the following usage:

Only call ShippingStatus for an update when needed by a customer application or user.
Always use the CurrentStatus method to retrieve high level status of shipment.
Only use the CompleteStatus method when exceptions have occurred and more detailed statuses are needed.
Only call ShippingStatus after a shipment can have a status update (for example: request status in afternoon after delivery to PostNL, then it will have been sorted and delivered, giving useful information).
Stop calling ShippingStatus when the barcode is not found, or an error has occurred.

Security policy
The statuses about your parcels are restricted to your company (customer code and customer number). Our security policy is designed to identify which company is requesting the information and matches that information with the parcels sent by the company. Only if the company and the parcels match, the information is disclosed.

The requests of the methods are almost the same. There is only a difference  in the Shipment element type of the methods. For CurrentStatusByPhase and CurrentStatusByStatus you have to give some date information combined with the status- or phase code. And for GetSignature you only need the barcode of the shipment.

CurrentStatus,CurrentStatusByStatus and CurrentStatusByPhase,CurrentStatusByReference have the same response. The CompleteStatus and CompleteStatusByReference have four additional elements; Customer, Events, Old Statuses and Product Description.

The GetSignature response is different because this return a GIF image (base64 encoded). To retrieve a working image you need to convert and decode this string and mark the mime-type of the image as GIF.

Using the response information
You can use the response information of the webservice to inform your own customers proactively about the status of their parcel. As the status we return to you is a near to real-time status it is recommended that you communicate this status as soon as possible to your customers.

When the parcel requested is not found, the service returns a warning message.

Error codes
Error codes have been specified in the below PDF file. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in the API.


Request and Response codes

For explanation of the request and response codes, you can take a look at the Documentation page of this API. Here you can find all information about the attributes of the json call, like descriptions, formats and examples.

Swagger UI

Test the RESTful API's with JSON content type format with the below Swagger tooling. To easily test the API: Click at 'Expand Operations', fill in at least the requirerd parameters and click at the 'Try it Out!' button. You can find the response code under Response Messages.

You can also test this API's by using the following Swagger url: (expand the url with /swagger.json and click Explore)

ShippingStatus API

Receive status information about the shipments