Documentation

Shippingstatus webservice

Summary

  • Name: Shippingstatus Webservice.
  • Reason to Call: Receive status information about the shipments.
  • Input: Customernumber, barcode or reference.
  • Output: Status information about the shipment(s).

Methods

REST (Get) Description
/v2/status/barcode/{barcode}Returns the statuses for a particular barcode
/v2/status/reference/{referenceID}Get status by customer reference
/v2/status/signature/{barcode}Returns the signature image for a specific shipment.
/v2/status/{customernumber}/updatedshipmentsReturns the updated statuses for a particular customer number

* Status_Codes
**Event_Codes

Call details

Interface version v2*
Sandbox endpointhttps://api-sandbox.postnl.nl/shipment/v2/status
Sandbox swaggerhttps://api-sandbox.postnl.nl/shipment/v2/status/swagger.json
Production endpointhttps://api.postnl.nl/shipment/v2/status
Production swaggerhttps://api.postnl.nl/shipment/v2/status/swagger.json

*The v2 version is only available in REST. For information about the old Shippingstatus SOAP version(s) please check the following page.

Versioning

REST:

APIVersionRelease DateStatusRelease NotesSchema Changes
Shippingstatus1_6Jun 01, 2017Supported

IN COMPARISON TO THE 1_5 SOAP VERSION;
the following fields have been added to the interface;
CurrentStatusResponseShipment/DeliveryDate, CurrentStatusResponseShipment/Expectation,
CompleteStatusResponseShipment/DeliveryDate and CompleteStatusResponseShipment/Expectation.

N/A
 2Feb 12, 2018Current version

A new method has ben added to the interface;
/v2/status/{customernumber}/updatedshipments. This method returns the updated statuses for a particular customer number.

 The following fields have been added to the interface;
maxDays
language

Yes
 

Guidelines

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.
  • Limit the number of days that will be searched for better performance with the parameter 'maxDays'.
  • Only set the parameter 'Detail'on true (boolean), 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.
* From January 15, 2019 the method '/updatedshipments' has been introduced. With this method you can retrieve (all) the updated statuses for a particular customer number. 

Security policy
The statuses about your parcels are restricted to your company (customercode and customernumber). 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.

GetSignature response 
This method returns 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 parcels. As the status we return  is a near to real-time status, it is recommended to communicate this status as soon as possible to your customers.

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

Error codes
Error codes have been specified in the Error codes section. 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

/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

Example

CURL: 
curl -X GET "https://api-sandbox.postnl.nl/shipment/v2/status/barcode/
3SDEVC172649258?detail=false&language=EN&maxDays=2"
 -H "accept: application/json" -H "apikey: R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX"


Request URL: 
https://api-sandbox.postnl.nl/shipment/v2/status/barcode/3SDEVC172649258
?detail=false&language=EN&maxDays=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+02:00
Dimension  Dimension information of a Shipment 
Expectation  ExpectationType2016-04-20T00:00:00+02: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)

Example

{
  "CurrentStatus": {
    "Shipment": {
      "MainBarcode": "3SDEVC172649258",
      "Barcode": "3SDEVC172649258",
      "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-01-2019 16:20:27",
        "StatusCode": "1",
        "StatusDescription": "Zending voorgemeld",
        "PhaseCode": "1",
        "PhaseDescription": "Collectie"
      }
    }
  }
}

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+02:00
ETATo  Estimated latest time of arrival. Only shown when PostNL has calculated this time.2016-04-22T16:30:00+02:00

Events type

Parameter  DescriptionExample
Code  Event sort code, e.g: 01A.01A
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

Example

{
  "CompleteStatus": {
    "Shipment": {
      "MainBarcode": "3SDEVC172649258",
      "Barcode": "3SDEVC172649258",
      "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-01-2019 16:20:27"
        }
         ],
      "Status": {
        "TimeStamp": "10-01-2019 16:20:27",
        "StatusCode": "1",
        "StatusDescription": "Zending voorgemeld",
        "PhaseCode": "1",
        "PhaseDescription": "Collectie"
      },
      "OldStatus": [        
        {
          "TimeStamp": "10-01-2019 16:20:27",
          "StatusCode": "1",
          "StatusDescription": "Zending voorgemeld",
          "PhaseCode": "1",
          "PhaseDescription": "Collectie"
        },        
        {
          "TimeStamp": "29-12-2018 03:30:00",
          "StatusCode": "14",
          "StatusDescription": "Voorgemeld: definitief niet aangenomen",
          "PhaseCode": "1",
          "PhaseDescription": "Collectie"
        },
        {
          "TimeStamp": "22-12-2018 07:00:00",
          "StatusCode": "99",
          "StatusDescription": "Niet van toepassing",
          "PhaseCode": "99",
          "PhaseDescription": "Niet van toepassing"
        },      
        {
          "TimeStamp": "20-12-2018 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

/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

Example

CURL: 
curl -X GET "https://api-sandbox.postnl.nl/shipment/v2/status/reference/
1045968?detail=false&language=EN&maxDays=2"
 -H "accept: application/json" -H "apikey: R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX"

Request URL: 
https://api-sandbox.postnl.nl/shipment/v2/status/reference/Reference=1045968&
customerCode=DEVC&customerNumber=11223344&detail=false

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

Example

CURL: 
curl -X GET "https://api-sandbox.postnl.nl/shipment/v2/status/signature/
3SDEVC172649258"
 -H "accept: application/json" -H "apikey: R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX"

Request URL:
https://api-sandbox.postnl.nl/shipment/v2/status/signature/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)

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

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).2019-01-14T10:00:00

Example

CURL: 
curl -X GET "https://api-sandbox.postnl.nl/shipment/v2/status/11223344/updatedshipments?
period=2019-01-14T10%3A00%3A00&period=2019-01-15T10%3A00%3A00"
 -H "accept: application/json" -H "apikey: R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX"

Request URL:
https://api-sandbox.postnl.nl/shipment/v2/status/11223344/updatedshipments?
period=2019-01-14T10%3A00%3A00&period=2019-01-15T10%3A00%3A00

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

Example

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