Shippingstatus

Documentation

When parcels go through the PostNL distribution process, they pass certain checkpoints. In this process different scans are made; the information that is derived from these scans is valuable information about where the parcel is located in the distribution process. With the ShippingStatus API we are able to share these statuses with our customers.

Why use the Shippingstatus API

• The current status and the complete status can be requested.  With the Detail boolean in the request (true) gives you an overview of all the statuses that are given to the parcel throughout the distribution process.

• With the method ‘updatedshipments' you can retrieve (all) the updated statuses for a particular customer number.

• The statuses about the parcels are restricted to a customer number in combination with the customer code. Only if the customer data and the parcels match, the information is disclosed.

Get started

Request your (Sandbox) API Key and start using the API.
As soon as you have an API key, it is recommended to run our Postman collections. Here you can find code examples of the various services and products we offer. This makes implementing the APIs much easier.

 

Start using the API

Development

On this page you will find all the necessary information for implementing this API.
Please check the Guidelines for useful information.
Descriptions, formats and examples of the API attributes are also very useful to look at.

Methods

Call details

Versioning

Guidelines

Code examples

Request Barcode (current status): 

curl -L -X GET "https://api-sandbox.postnl.nl/shipment/v2/
status/barcode/3SDEVC987633330?detail=false&
language=NL" -H "apikey: ***"  -H "
Host: api-sandbox.postnl.nl"


Response:

{
  "CurrentStatus": {
    "Shipment": {
      "MainBarcode": "3SDEVC987633330",
      "Barcode": "3SDEVC987633330",
      "ShipmentAmount": "1",
      "ShipmentCounter": "1",
      "Customer": {
        "CustomerCode": "DEVC",
        "CustomerNumber": "11223344",
        "Name": "Testaccount API PNP"
      },
      "ProductCode": "003085",
      "ProductDescription": "Standaard Zending",
      "Reference": "foobar",
      "Dimension": {
        "Height": {1400},
        "Length": {2000},
        "Volume": {3000},
        "Weight": {4300},
        "Width": {1500}
      },
      "Address": [
        {
          "AddressType": "01",
          "Building": {},
          "City": "Utrecht",
          "CompanyName": {},
          "CountryCode": "NL",
          "DepartmentName": {},
          "District": {},
          "FirstName": "Ben",
          "Floor": {},
          "HouseNumber": "42",
          "HouseNumberSuffix": {},
          "LastName": "Cavens",
          "Region": {},
          "Remark": {},
          "Street": "Awesome street",
          "Zipcode": "3532VA"
        },
        {
          "AddressType": "02",
          "Building": {},
          "City": "Hoofddorp",
          "CompanyName": {},
          "CountryCode": "NL",
          "DepartmentName": {},
          "District": {},
          "FirstName": "Ben",
          "Floor": {},
          "HouseNumber": "42",
          "HouseNumberSuffix": {},
          "LastName": "Cavens",
          "Region": {},
          "Remark": {},
          "Street": "Siriusdreef",
          "Zipcode": "2132WT"
        }
      ],
      "Status": {
        "TimeStamp": "10-09-2022 16:20:27",
        "StatusCode": "1",
        "StatusDescription": "Zending voorgemeld",
        "PhaseCode": "1",
        "PhaseDescription": "Collectie"
      }
    }
  }
}
Request barcode (complete status; detail=true): 

curl -L -X GET "https://api-sandbox.postnl.nl/shipment/v2/
status/barcode/3SDEVC987633330?detail=true&
language=NL" -H "apikey: ***"  -H "
Host: api-sandbox.postnl.nl"

Response:

{
  "CompleteStatus": {
    "Shipment": {
      "MainBarcode": "3SDEVC987633330",
      "Barcode": "3SDEVC987633330",
      "ShipmentAmount": "1",
      "ShipmentCounter": "1",
      "Customer": {
        "CustomerCode": "DEVC",
        "CustomerNumber": "11223344",
        "Name": "Testaccount API PNP"
      },
      "ProductCode": "003085",
      "ProductDescription": "Standaard Zending",
      "Reference": "foobar",
      "Dimension": {
        "Height": {1400},
        "Length": {2000},
        "Volume": {3000},
        "Weight": {4300},
        "Width": {1500}
      },
      "Address": [
        {
          "AddressType": "01",
          "Building": {},
          "City": "Utrecht",
          "CompanyName": {},
          "CountryCode": "NL",
          "DepartmentName": {},
          "District": {},
          "FirstName": "Ben",
          "Floor": {},
          "HouseNumber": "42",
          "HouseNumberSuffix": {},
          "LastName": "Cavens",
          "Region": {},
          "Remark": {},
          "Street": "Awesome street",
          "Zipcode": "3532VA"
        },
        {
          "AddressType": "02",
          "Building": {},
          "City": "Hoofddorp",
          "CompanyName": {},
          "CountryCode": "NL",
          "DepartmentName": {},
          "District": {},
          "FirstName": "Ben",
          "Floor": {},
          "HouseNumber": "42",
          "HouseNumberSuffix": {},
          "LastName": "Cavens",
          "Region": {},
          "Remark": {},
          "Street": "Siriusdreef",
          "Zipcode": "2132WT"
        }
      ],
      "Event": [
        {
          "Code": "A01",
          "Description": "Zending wordt verwacht, maar zit nog niet in sorteerproces",
          "DestinationLocationCode": {},
          "LocationCode": "888888",
          "RouteCode": {},
          "RouteName": {},
          "TimeStamp": "10-09-2022 16:20:27"
        }
         ],
      "Status": {
        "TimeStamp": "10-09-2022 16:20:27",
        "StatusCode": "1",
        "StatusDescription": "Zending voorgemeld",
        "PhaseCode": "1",
        "PhaseDescription": "Collectie"
      },
      "OldStatus": [        
        {
          "TimeStamp": "10-09-2022 16:20:27",
          "StatusCode": "1",
          "StatusDescription": "Zending voorgemeld",
          "PhaseCode": "1",
          "PhaseDescription": "Collectie"
        },        
        {
          "TimeStamp": "09-09-2022 03:30:00",
          "StatusCode": "14",
          "StatusDescription": "Voorgemeld: definitief niet aangenomen",
          "PhaseCode": "1",
          "PhaseDescription": "Collectie"
        },
        {
          "TimeStamp": "09-09-2022  07:00:00",
          "StatusCode": "99",
          "StatusDescription": "Niet van toepassing",
          "PhaseCode": "99",
          "PhaseDescription": "Niet van toepassing"
        },      
        {
          "TimeStamp": "09-09-2022  03:30:00",
          "StatusCode": "13",
          "StatusDescription": "Voorgemeld: nog niet aangenomen",
          "PhaseCode": "1",
          "PhaseDescription": "Collectie"
        },
        {
          "TimeStamp": "19-12-2018 13:03:06",
          "StatusCode": "1",
          "StatusDescription": "Zending voorgemeld",
          "PhaseCode": "1",
          "PhaseDescription": "Collectie"
        }
      ]
    }
  }
}
Request reference: 

curl -L -X GET "https://api-sandbox.postnl.nl/shipment/v2/
status/reference/REF12564367567788?customerCode=
DEVC&customerNumber=11223344"
 -H "apikey: ***" -H "Host: api-sandbox.postnl.nl"
Request signature: 

curl -L -X GET "https://api-sandbox.postnl.nl/shipment/
v2/status/signature/3SDEVC904775316
" -H "apikey: ***"  -H "Host: api-sandbox.postnl.nl"

Response:

{
  "Signature": {
    "Barcode": "3SDEVC904775316",
    "SignatureDate": "2019-02-24T09:25:01.000+01:00",
    "SignatureImage": "[BASE64 STRING]"
  }
}
Request updated shipments: 

curl -L -X GET "https://api-sandbox.postnl.nl/shipment/
v2/status/11223344/updatedshipments?period=
2022-01-25T10:00:00&period=2022-01-25T10:12:00"
 -H "apikey: ***" -H "Host: api-sandbox.postnl.nl"

Response: 

[{
    "Barcode": "3SDEVC987554824",
    "CreationDate": "2022-01-25",
    "CustomerNumber": "11223344",
    "CustomerCode": "DEVC",
    "Status": {
        "Timestamp": "2022-01-25T10:16:40",
        "StatusCode": "1",
        "StatusDescription": "Zending voorgemeld",
        "PhaseCode": "1",
        "PhaseDescription": "Collectie"
    }
},
{
    "Barcode": "3SDEVC987173551",
    "CreationDate": "2022-01-23",
    "CustomerNumber": "11223344",
    "CustomerCode": "DEVC",
    "Status": {
        "Timestamp": "2022-01-23T14:26:43",
        "StatusCode": "11",
        "StatusDescription": "Zending afgeleverd",
        "PhaseCode": "4",
        "PhaseDescription": "Afgeleverd"
    }
},
{
    "Barcode": "3SDEVC987022147",
    "CreationDate": "2022-02-21",
    "CustomerNumber": "11223344",
    "CustomerCode": "DEVC",
    "Status": {
        "Timestamp": "2022-01-25T13:14:41",
        "StatusCode": "11",
        "StatusDescription": "Zending afgeleverd",
        "PhaseCode": "4",
        "PhaseDescription": "Afgeleverd"
    }
},
{
    "Barcode": "3SDEVC987443181",
    "CreationDate": "2022-01-24",
    "CustomerNumber": "11223344",
    "CustomerCode": "DEVC",
    "Status": {
        "Timestamp": "2022-01-24T15:15:01",
        "StatusCode": "11",
        "StatusDescription": "Zending afgeleverd",
        "PhaseCode": "4",
        "PhaseDescription": "Afgeleverd"
    }
},
{
    "Barcode": "3SDEVC987528402",
    "CreationDate": "2022-01-24",
    "CustomerNumber": "11223344",
    "CustomerCode": "DEVC",
    "Status": {
        "Timestamp": "2022-01-24T10:59:10",
        "StatusCode": "1",
        "StatusDescription": "Zending voorgemeld",
        "PhaseCode": "1",
        "PhaseDescription": "Collectie"
    }
}]

Request

/v2/status/barcode/{barcode}


ParameterMandatoryFormatDescription Example
apikey MString [32]Authenticate using your API key.
R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX
barcodeMString [13-15]Barcode of the shipment. This is a unique value.3SDEVC172649258
detailOBoolean [true/false]Option to include old statuses in the response.
Default value: false
false
languageOString [2]Language of the returned shipment descriptions. Possible values EN, CN, DU, FR and NL.
Default values: NL
EN
maxDaysOString [2]Limit the number of days that will be searched (decrease this amount for better performance).
2

Response CurrentStatus

Without details /old statuses

Parameter  DescriptionExample
Addresses  List of Addresses 
Amounts  List of 0 ore more Amount types. An amount represents a value of a shipment. 
Barcode  Barcode of the Shipment3SABCD6659149
DeliveryDate  The desired delivery date and time as indicated by the receiver.
This field is only available for Extra@Home products.
2016-04-20T00:00:00
Dimension  Dimension information of a Shipment 
Expectation  ExpectationType2016-04-20T00:00:00
Groups  List of Group information of a Shipment 
Productcode  Product code of the Shipment003052
ProductOptions  List of 0 or more ProductOption types. 
Reference  Your own reference of a shipment2016014567
Status  Status information of a Shipment. See the Status Codes document for an overview of possible statuses. 
Warnings  List of 0 or more Warnings. 

Address type

Parameter  DescriptionExample
AddressType  Type of the address. This is a code. You can find the possible values at the Guidelines.02
Building  Building name of the addressAA
City  City of the addressHoofddorp
CompanyName  The company name of the addressPostNL
CountryCode  The ISO2 country codesNL
DepartmentName  Send to specific department of a company.IT
District  Area/District of the addressBeukenhorst
Doorcode  Door code of the address123
FirstName  The person's first namePeter
Floor  The specific floor of a company4
HouseNumber  The house number of the address42
HouseNumberSuffix  The house number extension of the addressA
LastName  The person's last name of the addressde Ruiter
Region  The region (for instance, the province)Noord-Holland
RegistrationDate  The registration date of the address. If no registration date is entered, a default value will be shown: 01-01-0001 00:00:0001-01-0001 00:00:00
Remark  Remark of the addressNo doorbell
Street  The streetname of the addressSiriusdreef
Zipcode  Zipcode of the address2132WT

Amount type

Parameter  DescriptionExample
AccountName  Name of bank account owner C. de Ruiter 
AmountType  Amount type. This is a code. Possible values are: 01 = Cash on delivery (COD) value.· 02 = Insured01
Currency  Currency code according ISO 4217. E.g. EUR EUR
Reference  Personal payment reference1234-5678
TransactionNumber  Transaction number1234
Value  Money value in EUR10.00

Dimension type

Parameter  DescriptionExample
Height  Height of the shipment in milimeters (mm).1400
Length  Length of the shipment in milimeters (mm).

2000

Volume  Volume of the shipment in centimeters (cm3).

30000

Weight  Weight of the shipment in grams 

4300

Width  Length of Width of the shipment in milimeters (mm). 1500

Group type

Parameter  DescriptionExample
GroupType  Group sort that determines the type of group that is indicated. This is a code. Possible values: 01 = Collection request 03 = Multiple parcels in one shipment (multi-colli) 04 = Single parcel in one shipment03
MainBarcode  Main barcode for the shipment (in case of multi-colli shipments)3SABCD6659149
ShipmentAmount   Total number of colli in the shipment (in case of multi-colli shipments)4
ShipmentCounter  Sequence number of the collo within the complete shipment (e.g. collo 2 of 4)2

ProductOption type

Parameter  DescriptionExample
Characteristic  The characteristic of the ProductOption. 6
Option  The product option code for this ProductOption. 118

Status type

Parameter  DescriptionExample
PhaseCode  Code of the phase4
PhaseDescription  Description of the phaseAfgeleverd (delivered)
StatusCode  Code of the status11
StatusDescription  Description of the status. Zending afgeleverd. (shipment is delivered)
StatusTimeStamp  Timestamp of the status06-06-2016 18:00:41

Warning type

Parameter  DescriptionExample
Code   Warning code  2
Description  Warning descriptionDe ColloWebservice heeft geen Colli gevonden (No collo found)

Response CompleteStatus

See the Currentstatus (without details/old statuses) above for information about the parameters. Additional to this fields the following parameters will appear:

Parameter  DescriptionExample
Event  Collection of old Statuses that have occurred for this parcel
Expectation  Collection of old Statuses that have occurred for this parcel 
OldStatuses  Collection of old Statuses that have occurred for this parcel 

Expectation type

Parameter  DescriptionExample
ETAFrom  Estimated earliest time of arrival. Only shown when PostNL has calculated this time.2016-04-22T14:30:00
ETATo  Estimated latest time of arrival. Only shown when PostNL has calculated this time.2016-04-22T16:30:00

Events type

Parameter  DescriptionExample
Code  Event sort code, e.g: A01.A01
Description  Event sort description, e.g. Zending is voorgemeld. (shipment is confirmed)Zending is aangemeld maar nog niet ontvangen door PostNL
DestinationLocationCode  Location code of the destination888888
LocationCode  Location code156789
RouteCode  Route code310
RouteName  Route name310 Sittard Vrangendael
TimeStamp  Timestamp of the event20-4-2016 0:39

CompleteStatus ResponseOldStatus type

Attribute  DescriptionExample
Code  Code of the phase7
Description  Description of the phaseZending in distributieproces
(Shipment in distribution process)
PhaseCode  Code of the status4
PhaseDescription  Description of the statusAfgeleverd  (Delivered)
TimeStamp  Timestamp of the status05-06-2016 18:00:00

Request

/v2/status/reference/{referenceId}


ParameterMandatoryFormatDescription Example
apikey MString [32]Authenticate using your API key.
R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX
customerCodeMString [1-4]Customer code as known at PostNL Pakketten.DEVC

customerNumberMInteger [1-8]Customer number as known at PostNL Pakketten.11223344
referenceIdMString [0-35]Your own reference of the shipment.
detailOBoolean [true/false]Option to include old statuses in the response.
Default value: false
false
languageOString [2]Language of the returned shipment descriptions. Possible values EN, CN, DU, FR and NL.
Default value: NL
EN
maxDaysOString [2]Limit the number of days that will be searched (decrease this amount for better performance).
2

Request GetSignature


ParameterMandatoryFormatDescription Example
apikey MString [32]Authenticate using your API key.
R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX
barcodeMString [13-15]Barcode of the shipment. This is a unique value.3SDEVC172649258

Response GetSignature

SignatureResponse type

Attribute  DescriptionExample
Signature  List of GetSignatureResponseSignature 
Warning  List of warning codes 

GetSignatureResponseSignature type

Attribute  DescriptionExample
Barcode  Barcode of the shipment3SABCD6659149
SignatureDate  Date of the signature2016-06-04T10:03:51+02:00
SignatureImage  Image contents of the signature. The image is always returned as a GIF image and is base64 encoded.  

Warning type

Attribute  DescriptionExample
Code   Warning code  02
Description  Warning descriptionDe HandtekeningWebservice heeft geen handtekening gevonden (no signature found)

Request Updatedshipments

/v2/status/{customernumber}/updatedshipments


ParameterMandatoryFormatDescription Example
apikey MString [32]Authenticate using your API key.
R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX
customernumberMInteger [1-8]Customer number as known at PostNL Pakketten.11223344
periodOArray[string]

Optional array which defines a specific period in which to return updated shipments. Please use the following format: YYYY-MM-DDTHH:MM:SS. If only one variable is provided, it is interpreted as ‘period from’ up until the current datetime. If you provide two periods, the first is interpreted as ‘period from’, the second as ‘period to’ (e.g. /updatedshipments?period=2019-01-14T10:00:00&period=2019-01-15T10:00:00).
NOTE: The maximum time range period is 48 hours. The default is 2 hours.


2019-01-14T10:00:00

Response Updatedshipments

See CurrentStatus 

Attribute  DescriptionExample
barcode  Barcode of the Shipment3SDEVC172649258
creationdate  The creationdate the shipment 2019-02-25
customerNumber  Customer number as known at PostNL Pakketten.11223344
customerCode  Customer code as known at PostNL Pakketten.DEVC
Status  Status information of a Shipment. See the Status Codes document for an overview of possible statuses.
Warnings  List of 0 or more Warnings.

Status type

Parameter  DescriptionExample
PhaseCode  Code of the phase4
PhaseDescription  Description of the phaseAfgeleverd (delivered)
StatusCode  Code of the status11
StatusDescription  Description of the status. Zending afgeleverd. (shipment is delivered)
StatusTimeStamp  Timestamp of the status06-06-2016 18:00:41