Documentation

Labelling webservice

Summary

Name: Labelling webservice.
Reason to Call: Create a label and send a confirmation to PostNL (optional).
Input: Information about the shipment.
Output: One or more shipping labels.

Note: When using the labelling service (GenerateLabel method), the Confirming service does no longer need to be integrated in your system, for it is included into this service.

Methods

The following methods are defined within the Labelling WebService.

Methods	Description
GenerateLabel	Generation of a label, followed by the confirmation of that parcel.
GenerateLabelWithoutConfirm	Generation of a label. This method doesn’t confirm the shipment. Confirming has to be done using the Confirming WebService.

Methods	SoapAction
GenerateLabel	http://postnl.nl/cif/services/LabellingWebService/ILabellingWebService/GenerateLabel
GenerateLabelWithoutConfirm	http://postnl.nl/cif/services/LabellingWebService/ILabellingWebService/GenerateLabelWithoutConfirm

The two methods work exactly the same and have the same request and response format except for the use of endpoint.
With the Confirm boolean in the request (true of false), you can determine if you want to confirm the shipment in the same call or not.

Call details

Interface version	2_2*
Sandbox endpoint	https://api-sandbox.postnl.nl/shipment/v2_2/label
Sandbox wsdl	https://api-sandbox.postnl.nl/shipment/v2_2/label/soap.wsdl
Sandbox swagger	https://api-sandbox.postnl.nl/shipment/v2_2/label/swagger.json
Production endpoint	https://api.postnl.nl/shipment/v2_2/label
Production wsdl	https://api.postnl.nl/shipment/v2_2/label/soap.wsdl
Production swagger	https://api.postnl.nl/shipment/v2_2/label/date/swagger.json

Versioning

REST:

API

Version

Release Date

Status

Release Notes

Schema Changes

Labelling

2_1

Jun 01, 2017

Supported

IN COMPARISON TO THE 2_0 SOAP VERSION,
the following fields have been added to the interface, in order to implement a commercial route to China:
- Shipment.Customs.Content.Content.EAN;
-Shipment Customs.Content.Content.ProductURL.
And the following fields have been added to the interface for Delivery on Demand (Mytime):

- DeliveryTimestampStart
- DeliveryTimestampEnd

NOTE: THIS PRODUCT NO LONGER EXIST.

N/A

2_2

Jan 25, 2019

Current version

The following fields have been added to the interface for shipments to the USA:

-Shipment.Customs.TrustedShipperID
-Shipment.Customs.ImporterReferenceCode
-Shipment.Customs.TransactionCode
-Shipment.Customs.TransactionDescription

-Shipment.CodingText (response)
A Codingtext have been added to the labels for mailbox parcels (brievenbuspakjes).

Yes

SOAP:

Version	Release Date	Status	Release Notes	Schema Changes
1_3	Dec 27, 2012	Not supported
1_4	Nov 8, 2013	Not supported	The following fields have been added to the interface: Shipment/Content Shipment/CostCenter Shipment/CustomerOrderNumber Shipment/Remark Shipment/ReturnReference Shipment/ReturnBarcode Amount/BIC Amount/IBAN The following fields have been removed from the interface: Amount/AccountNr To comply with SEPA regulation, the bank account details must be entered in IBAN format. The COD card has been changed to print the IBAN bank account number.	Yes
1_5	Feb 27, 2014	Not supported	Different namespace Note: due to changes in the backend the Label in the box (return label) functionality is only available from version 1_6 or later. The following fields have been added to the interface: Shipment\ProductOption\Option Shipment\ProductOption\Characteristic Shipment\DeliveryDate Shipment\DeliveryAddress	Yes
1_6	Aug 14, 2014	Supported	Different namespace	Yes
1_7	Nov 14, 2014	Supported	The following field has been added to the interface: Shipment.DownPartnerLocation	Yes
1_8	Jan 12, 2015	Not supported	The following fields have been added to the interface: - Shipment.IDNumber - Shipment.IDType - Shipment.IDExpiration - Shipment.ReceiverDateOfBirth The field StreetHouseNrExt is now usable for locations in NL, BE and DE.	Yes
1_9	Apr 24, 2015	Not supported	The request now includes a field for adding a signature to the labels generated by the service. This field is optional, so no change is required to use the new version of the service. Shipment validation errors now include an error code in addition to the error message.	Yes
2_0	Aug 14, 2015	Supported	Multiple shipments can now be sent in one request to the labelling service. 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. 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 new MergedLabels response field. If you want to send only one shipment, you have to specify the Shipments element containing one Shipment.	Yes
2_1	July 15, 2017	Supported	PostNL has implemented a commercial route to China. In order to do this, the following fields have been added to the interface: - Shipment.Customs.Content.Content.EAN - Shipment Customs.Content.Content.ProductURL The Shipment.Customs.Content element can occur up to 10 times instead of 5. - DeliveryTimestampStart (Delivery on Demand label) - DeliveryTimestampEnd (Delivery on Demand label)	Yes
2_2	Jan 25, 2019	Current version	The following fields have been added to the interface for shipments to the USA: -Shipment.Customs.TrustedShipperID -Shipment.Customs.ImporterReferenceCode -Shipment.Customs.TransactionCode -Shipment.Customs.TransactionDescription -Shipment.CodingText (response) A Codingtext have been added to the labels for mailbox parcels (brievenbuspakjes).	Yes

Guidelines

Shipping labels
The label that are send to you is not suited for scaling, for the measures of the label are carefully designed to ease the parcel through our process.

Confirmation
This API contains the possibility to create a label and the PostNL confirmation. This service sends the confirmation to the PostNL systems and upon receiving the confirmation, the service sends back a filled in label to print and to stick on the parcel.

With the Confirm boolean in the request (true of false), you can determine if you want to confirm the shipment in the same call or not.

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.

Request size

The total request can have a maximum size of 200KB. Larger requests will not be accepted by the server for performance reasons. Requests that exceed this limit will not return a label, but a HTTP 404 error.

Destination EU / Rest of World

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.

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 mandatory; using both fields is also allowed. 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. The conversion is only made for NL, BE and DE addresses.

Multi-collo

Each request contains a single parcel. This parcel can be (part of) a single shipment or can be part of a multi-collo shipment. Each parcel in a multi-collo shipment must be sent in a separate request towards the API.

For shipments within the Netherlands, multi collo shipments can be created. Using the API, this can be done as follows:

-Create a separate request per parcel to retrieve a label or to confirm the shipment (or both at once)

-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).

-Every parcel in the multi collo shipment has to have its own, unique barcode.

For Extra@Home and Cargo shipments, the requests cannot be done separately for multicollo shipments. Multi collo shipments must be confirmed in one joint request.

Multiple shipments
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.

Multiple label printing
It is possible to generate multiple labels at once, and have these labels printed on a single A4-sheet.

In order to use this functionality, you must select a different PrinterType. The PrinterType chosen determines the starting position of the label that is generated first. Below are the four printertypes that will produce an A4 sheet with multiple labels

GraphicFile|PDF|MergeA
GraphicFile|PDF|MergeB
GraphicFile|PDF|MergeC
GraphicFile|PDF|MergeD

In the figure below, the label starting position is shown for each type.

MergeA MergeB

MergeC MergeD

When a Merge type is chosen, the labels that follow are automatically printed on the next position. Note that four labels can be printed at once using this method, so you are always able to fill a complete A4 sheet.

Limitations
The following applies to the merge functionality described above:

MergeA-D cannot be used for labels which are not 10x15 cm
MergeA-D cannot be used for combilabels
MergeA-D cannot be used for COD-products, due to the COD-card being printed.

You can request up to four labels at once.

Printertypes
A printer type must be specified in the request. The API is capable of generating a wide range of output format. See the printer types below for the possible values. Please choose the type that fits best with your local printing situation.

Zebra|Generic ZPL II 200, 300 and 600 dpi *

* It is not recommended to send .pdf files/labels directly to a Zebra printer If you want to send it directly to your Zebra printer, please use .gif files or the native (generic) zpl printer type.

Label types
The Label type helps you to determine what document is returned. In most cases, only a Label is returned. The following label types are possible:

Labeltype	Description
Label (A6)	normal shipping label for all shipments except for Parcels Non-EU
BusPakjeExtra (A6)	shipping label for parcels that fit in a mailbox
CODcard (Kabinet (21 x 10,16 cm)	COD card as required for Dutch domestic COD shipments
CN23 form (A5)	customs form for Parcels Non-EU shipments
CP71 form (A5)	customs form for Parcels Non-EU shipments
Commercialinvoice (A4)	commercial invoice for Parcels Non-EU shipments
Return Label (A6)	normal shipping label for reverse logistics

Productcode 4945:
ShipmentType parameter Gift or Documents: CN23 / CP71
ShipmentType parameter Commercial Goods, Commercial Sample or Returned Goods: CN23/ CP71/ CommercialInvoice

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
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.

Request GenerateLabel and GenerateLabelWithoutConfirm

CustomerType

Attribute	Mandatory	Format	Description	Example
Address	O-M	Address type	See Address type (XmlElement is Address) Address 02 is mandatory. It can either be placed in the Customer segment or in the Shipment segment. Note that if you put it in the Shipment segment, it should go into all Shipment segments.
CollectionLocation	M	String	Code of delivery location at PostNL Pakketten	123456
ContactPerson	O	String	Name of customer contact person	Janssen
CustomerCode	M	String [1-4]	Customer code as known at PostNL Pakketten	ABCD
CustomerNumber	M	Integer [1-8]	Customer number as known at PostNL Pakketten	1234567
Email	O	String [0-50]	E-mail address of customer	janssen@company.com
Name	O	String [0-35]	Customer name	Janssen

LabelSignature type

Attribute

Mandatory

Format

Description

Example

Base64

GIF image of the signature, max size: 280x60 mm (1058x226 pixels). As a base64 encoded string. This can be used to automatically sign the customs forms. The value of this element can have a maximum size of 65536 characters.

Larger requests will not be accepted by the server for performance reasons. Requests that exceed this limit will not return a validation error, but a HTTP 404 error.

Message type

Attribute	Mandatory	Format	Description	Example
MessageID	M	String [1-12]	ID of the message	1
MessageTimeStamp	M	Datetime [19]	Date/time of sending the message. Format: dd-mm-yyyy hh:mm:ss	29-06-2016 12:00:00
Printertype	M	String [1-35]	Printer type that will be used to process the label, e.g. Zebra printer or PDF See Guidelines for the available printer types.	GraphicFile\|PDF

Shipments type

Attribute	Mandatory	Format	Description	Example
Shipment	M	Shipment type	List of 1 or more ShipmentType elements of a shipment. At least one shipment type is required. Shipments for validation or confirmation.

Shipment type

Attribute	Mandatory	Format	Description	Example
Addresses	M	Address type	List of 1 or more Address type elements At least 1 address type is mandatory
Amounts	0-M	Amount type	List of 0 or more AmountType elements. An amount represents a value of the shipment. Amount type 01 mandatory for COD-shipments, Amount type 02 mandatory for domestic insured shipments. Amount type 04 mandatory for Commercial route China (productcode 4992) Amount type 12 mandatory for Inco terms DDP Commercial route China (productcode 4992)
Barcode	M	String [11-15]	Barcode of the shipment. This is a unique value	3SABCD6659149
CollectionTimeStampEnd	O	Datetime [19]	Ending date/time of the collection of the shipment	04-06-2016 17:00:00
CollectionTimeStampStart	O	Datetime [19]	Starting date/time of the collection of the shipment	04-06-2016 19:00:00
Contacts	O-M	Contact type	One or more ContactType elements belonging to a shipment Mandatory in some cases. Please refer to the Guidelines
Content	O-M	String [0-35] *	Content of the shipment Mandatory for Extra@Home shipments	Media player
CostCenter	O	String [0-35]	Cost center of the shipment. This value will appear on your invoice	SX-GT-66
CustomerOrderNumber	O	String [0-35]	Order number of the customer.	8689242390
Customs	O-M	Customs type	The Customs type is mandatory for Parcels Non-EU shipments and not allowed for any other shipment types.
DeliveryAddress	O-M	Integer [2]	Delivery address specification. This field is mandatory when AddressType on the Address is 09.	02
DeliveryTimestampEnd	O-M	Datetime [19]	Timestamp of the delivery used for Delivery on Demand (MyTime) Mandatory for Delivery on Demand shipments THIS PRODUCT NO LONGER EXIST	04-06-2017 18:00:00
DeliveryTimestampStart	O-M	Datetime [19]	Timestamp of the delivery used for Delivery on Demand (MyTime) Mandatory for Delivery on Demand shipments THIS PRODUCT NO LONGER EXIST	04-06-2017 16:00:00
DeliveryDate	O-M	datetime [19]	Mandatory when using Mailbox Parcels (for generation of the coding rule) and delivery options like Evening/Morning/Sameday delivery etc.	30-06-2016 12:00:00
Dimension	M	Dimension type	Dimension of a shipment. See the dimension type.
DownPartnerBarcode	O-M	String [0-35]	Barcode of the downstream network partner of PostNL Pakketten.	CD123456785NL
DownPartnerID	O-M	String [0-50]	Identification of the downstream network partner of PostNL Pakketten. Mandatory for Pickup at PostNl Location Belgium. Use the data from the Location API response; attribute RetailNetworkID	PNPBE-01
DownPartnerLocation	O-M	String [0-10]	Identification of the location of the downstream network partner of PostNL Pakketten.	BE0Q82
Groups	O-M	Group type	List of 0 or more Group types with data, grouping multiple shipments together. Mandatory for multicollo shipments. Please see Guidelines (Multiple shipments) for more information.
IDExpiration	O-M	Date [10]	Expiration date of the ID document. Mandatory for ID Check products	05-06-2020
IDNumber	O-M	String [0-20]	Document number of the ID document Mandatory for ID Check products	4261103214
IDType	O-M	Integer [2]	Type of the ID document. Mandatory for ID Check products. See Products for possible values	03
ProductCodeCollect	O	Integer [4]	Second product code of a shipment	3153
ProductCodeDelivery	M	Integer [4]	Product code of the shipment	3085
ProductOptions	O-M	ProductOption type	Product options for the shipment, mandatory for certain products, see the Products page of this webservice
ReceiverDateOfBirth	O-M	Date [10]	Date of birth Mandatory for Age check products	10-12-1980
Reference	O-M	String [0-35] *	Your own reference of the shipment. Mandatory for Extra@Home shipments; for E@H this is used to create your order number, so this should be unique for each request.	2016014567
ReferenceCollect	O	String [0-35]	Additional reference of the collect order of the shipment.	6659150
Remark	O	String [0-35]	Remark of the shipment.	Fragile
ReturnBarcode	O-M	String [11-15]	Return barcode of the shipment. PostNL will provide you with a separate customer code specifically for generating the returnBarcode. Note: It is not possible to generate Label in the box labels with the 1.4 and 1.5 version. Please upgrade to the newest API version (or at least > 1.5) . Mandatory for Label in the Box (return label) shipments.	3SABCD7762162
ReturnReference	O	String [0-35]	Return reference of the shipment.	112233

* To be sure that all the characters are visible on the label don’t use more than 20 characters.

Address type

Attribute	Mandatory	Format	Description	Example
AddressType	M	Integer [2]	Type of the address. This is a code. You can find the possible values at Guidelines	02
Area	O	String [0-35]	Area of the address	Beukenhorst
Buildingname	O	String [0-35]	Building name of the address	AA
City	M	String [0-35] *	City of the address	Hoofddorp
CompanyName	O-M	String [0-35] *	This field has a dependency with the field Name. One of both fields must be filled mandatory; using both fields is also allowed. Mandatory when AddressType is 09.	PostNL
Countrycode	M	String [2]	The ISO2 country codes	NL
Department	O	String [0-35]	Send to specific department of a company.	IT
Doorcode	O	String [0-35]	Door code of address	123
FirstName	O	String [0-35] *	Remark: please add FirstName and Name (lastname) of the receiver to improve the parcel tracking experience of your customer.	Peter
Floor	O	String [0-35]	Send to specific floor of a company.	4
HouseNr	O-M	String [0-35]	Mandatory for shipments to Benelux. Max. length is 5 characters (only for Benelux addresses). For Benelux addresses, this field should always be numeric.	42
HouseNrExt	O	NL= String [0-6] Outside of NL= String [0-35]	House number extension	A
Name	O-M	String [0-35] *	Last name of person. This field has a dependency with the field CompanyName. One of both fields must be filled mandatory; using both fields is also allowed. Remark: please add FirstName and Name (lastname) of the receiver to improve the parcel tracking experience of your customer.	de Ruiter
Region	O	String [0-35]	Region	Noord-Holland
Remark	O	String [0-35]	Remark of the shipment	Fragile
Street	O-M	String [0-95] *	This field has a dependency with the field StreetHouseNrExt. One of both fields must be filled mandatory; using both fields is also allowed.	Siriusdreef
StreetHouseNrExt	O-M	String [0-95]	Combination of Street, HouseNr and HouseNrExt. The field StreetHouseNrExt is only usable for locations in NL, BE and DE. Please see Guidelines for the explanation.	Siriusdreef 42 A
Zipcode	O-M	String [0-10]	Zipcode of the address. Mandatory for shipments to Benelux Max length (NL) 6 characters, (BE;LU) 4 numeric characters.	2132WT

* It may happen that not all the characters will be shown on the label.

Amount type

Attribute	Mandatory	Format	Description	Example
AccountName	O	String [0-35]	Name of bank account owner	C. de Ruiter
AmountType	M	Integer [2]	Amount type. This is a code. Possible values are: 02 = Insured value 04 mandatory for Commercial route China. 12 mandatory for Inco terms DDP Commercial route China.	01
BIC	O-M	String [8-11]	BIC number, optional for COD shipments (mandatory for bank account number other than originating in The Netherlands)	RABONL2UXXX
Currency	O	String [3]	Currency code according ISO 4217. E.g. EUR	EUR
IBAN	O- M	String [15-31]	IBAN bank account number, mandatory for COD shipments. Dutch IBAN numbers are 18 characters	NL00RABO0123456789
Reference	O	String [0-35]	Personal payment reference	1234-5678
TransactionNumber	O	String [0-35]	Transaction number	1234
Value	O-M	Decimal [0-9]	Money value in EUR (unless value Currency is specified for another currency). Value format (N6.2): #####0.00 (2 digits behind decimal dot) Mandatory for COD, Insured products (with the exception of certain productcodes with a standard insured amount) and Commercial route China. For COD the Eurosign (€) is always required.		10.00

Contact type

Attribute	Mandatory	Format	Description	Example
ContactType	M	Integer [2]	Type of the contact. This is a code. You can find the possible values at Guidelines	01
Email	O-M	String [0-50]	Email address of the contact. Mandatory in some cases. Please see Guidelines	receiver@gmail.com
SMSNr	O-M	String [10-17]	Mobile phone number of the contact. Mandatory in some cases.	0612345678
TelNr	O-M	String [10-17]	Phone number of the contact.	0612345678

Customs type

Attribute	Mandatory	Format	Description	Example
Certificate	O-M	Boolean [true/false]	Possible values are true/false (no capitals allowed) Fill in if applicable, for specific items a export certificate is obliged, as proof that the item complies to the sanity regulations, more information. Mandatory for Parcel shipments in the category type Commercial Goods, Commercial Sample and Returned Goods (Certificate, Invoice or License; at least 1 out of 3 must be selected)	true
CertificateNr	O-M	String [0-35]	Mandatory when Certificate is true.	NR112233
Content	M	Content type	This section is mandatory (minimum once, maximum 5)
Currency	M	String [3]	Currency code, only EUR, GBD, USD and CNY are allowed.	EUR

HandleAsNonDeliverable	M	Boolean [true/false]	Determines what to do when the Parcel shipment cannot be delivered the first time (if this is set to true, the parcel shipment will be returned after the first failed attempt)	false
Invoice	O-M	Boolean [true/false]	Possible values are true/false (no capitals allowed) Fill in the invoice number of the shipment. For a faster customs clearing process apply the invoice on the outside of the shipment. Mandatory for Parcel shipments in the category type Commercial Goods, Commercial Sample and Returned Goods (Certificate, Invoice or License; at least 1 out of 3 must be selected)	true
InvoiceNr	O-M	String [0-35]	Mandatory when Invoice is true.	22334455
License	O-M	Boolean [true/false]	Possible values are true/false (no capitals allowed) Fill in if applicable. Mandatory for Parcel shipments in the category type Commercial Goods, Commercial Sample and Returned Goods (Certificate, Invoice or License; at least 1 out of 3 must be selected)	true
LicenseNr	O-M	String [0-35]	Mandatory when License is true	11223344

ShipmentType	M	String [1-35]	Type of shipment, possible values: Gift, Documents, Commercial Goods, Commercial Sample, Returned Goods	Commercial Goods
TrustedShipperID	O	String [0-50]	Use only when available. Depending on the destination with this ID the customs process can be faster. Only fill in this customs reference number if the sender is registrated as Trusted Shipper in the country of destination	1234
ImporterReferenceCode	O	String [0-50]	Fill in a Tax Code or VAT number or Importer code. Depending on the destination with this reference the customs process can be faster	567
TransactionCode	O-M	String [0-50]	Code and accompanying description according to UPU List 136: “Item nature indication codes” (link). Most common codes are shown below for your reference. TransactionCode / TransactionDecription 11 Sale of goods 21 Returned goods 31 Gift 32 Commercial sample 91 Documents	11
TransactionDescription	O-M	String [0-50]	Transaction description See TransactionCode description above	Sale of goods

Content type

Attribute	Mandatory	Format	Description	Example
Description	M	String [1-35]	Clear description of the content of the item in English (description of goods)	Powdered milk
Quantity	M	Integer [1-4]	Fill in the total of the item(s)	2
Weight	M	Integer [1-20]	Fill in the weight of the item(s) in gram (gr)	2600
Value	M	Decimal [1-9]	Fill in the value of the item(s)	20.00
HSTariffNr	M	String [6]	Specify every item with the standard HS commodity code (HS-code), more information	100878
CountryOfOrigin	M	String [2]	Fill in the code of the country where the item was produced (ISO-code), more information	NL

Dimension type

Attribute	Mandatory	Format	Description	Example
Weight	M	Integer [0-20]	Weight of the shipment in grams Approximate weight suffices	4300
Length	O	Integer [0-20]	The longest side of the shipment in millimeters (mm).	700
Width	O	Integer [0-20]	The second longest side of the shipment in millimeters (mm).	500
Height	O	Integer [0-20]	The shortest side of the shipment in millimeters (mm).	300
Volume	O-M	Integer [0-20]	Volume of the shipment in centimeters (cm3). Mandatory for E@H-products	30000

Note: Length, Width, Height values are about the order of the size and need to be filled in from the longest to the shortest value. For example: shipment’s official height is 700mm, width 500mm, length 300m. The longest side (highest value) of 700mm needs to be entered at Length. Width value becomes 500mm, Height value: 300mm (the lowest). Entering the dimensions in the wrong order may result in incorrect shipping labels and longer delivery times. The maximum dimensions can be found in your PostNL contract.

Group type

Attribute	Mandatory	Format	Description	Example
GroupCount	O-M	Integer [0-3]	Total number of colli in the shipment (in case of multicolli shipments) Mandatory for multicollo shipments	4
GroupSequence	O-M	Integer [0-3]	Sequence number of the collo within the complete shipment (e.g. collo 2 of 4) Mandatory for multicollo shipments	2
GroupType	O-M	Integer [2]	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 (multicolli) 04 = Single parcel in one shipment	03
MainBarcode	O-M	String [11-15]	Main barcode for the shipment (in case of multicolli shipments) Mandatory for multicollo shipments	3SABCD6659149

ProductOption type

Attribute	Mandatory	Format	Description	Example
Characteristic	O-M	Integer [3]	The characteristic of the ProductOption. Mandatory for some products, please see the Products page	118
Option	O-M	Integer [3]	The product option code for this ProductOption. Mandatory for some products, please see the Products page	006

Example

POST https://api-sandbox.postnl.nl/shipment/v2_1/label HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://postnl.nl/cif/services/LabellingWebService/ILabellingWebService/GenerateLabel"
apikey: **********
Content-Length: 2635
Connection: Keep-Alive 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:lab="http://postnl.nl/cif/services/LabellingWebService/" 
xmlns:tpp="http://postnl.nl/cif/domain/LabellingWebService/">
  <soapenv:Body>
     <lab:GenerateLabel>
           <tpp:Customer>
                <tpp:Address>
                       <tpp:AddressType>02</tpp:AddressType>
                       <tpp:City>Hoofddorp</tpp:City>
                       <tpp:CompanyName>PostNL</tpp:CompanyName>
                       <tpp:Countrycode>NL</tpp:Countrycode>
                       <tpp:FirstName>Frank</tpp:FirstName>
                       <tpp:HouseNr>42</tpp:HouseNr>
                       <tpp:HouseNrExt>A</tpp:HouseNrExt>
                       <tpp:Name>Peeters</tpp:Name>
                       <tpp:Street>Siriusdreef</tpp:Street>
                       <tpp:Zipcode>2132WT</tpp:Zipcode>
                   </tpp:Address>
                  <tpp:CollectionLocation>123456</tpp:CollectionLocation>
                  <tpp:CustomerCode>DEVC</tpp:CustomerCode>
                  <tpp:CustomerNumber>11223344</tpp:CustomerNumber>
         </tpp:Customer>
             <tpp:Message>
             <tpp:MessageID>1</tpp:MessageID>
             <tpp:MessageTimeStamp>29-06-2016 12:00:00</tpp:MessageTimeStamp>
             <tpp:Printertype>GraphicFile|PDF</tpp:Printertype>
        </tpp:Message>
              <tpp:Shipments>
                  <tpp:Shipment>
                    <tpp:Addresses>
                      <tpp:Address>
                           <tpp:AddressType>01</tpp:AddressType>
                           <tpp:City>Utrecht</tpp:City>
                           <tpp:CompanyName>PostNL</tpp:CompanyName>
                           <tpp:Countrycode>NL</tpp:Countrycode>
                           <tpp:FirstName>Peter</tpp:FirstName>
                           <tpp:HouseNr>137</tpp:HouseNr>
                           <tpp:HouseNrExt/>
                           <tpp:Name>de Ruiter</tpp:Name>
                           <tpp:Street>Oldenburgerstraat</tpp:Street>
                           <tpp:Zipcode>3573SJ</tpp:Zipcode>
                     </tpp:Address>
                      </tpp:Addresses>
                      <tpp:Barcode>3SABCD6659149</tpp:Barcode>
                          <tpp:Contacts>
                            <tpp:Contact>
                            <tpp:ContactType>01</tpp:ContactType>
                            <tpp:Email>receiver@gmail.com</tpp:Email>
                            <tpp:SMSNr>0612345678</tpp:SMSNr>
                              </tpp:Contact>
                            </tpp:Contacts>
                         <tpp:Dimension>
                       <tpp:Weight>4300</tpp:Weight>
                         </tpp:Dimension>
                   <tpp:ProductCodeDelivery>3085</tpp:ProductCodeDelivery>
                      </tpp:Shipment>
                  </tpp:Shipments>
             </lab:GenerateLabel>
       </soapenv:Body>
</soapenv:Envelope>

Response Generate label and GenerateLabelWithoutConfirm

ResponseShipment type

Attribute	Description	Example
Barcode	Barcode of the shipment	3SABCD6659149
CodingText	CodingText used for mailbox parcels. If you are using GenerateLabelWithoutConfirm, please use this value in the Confirming request when confirming the shipment.	#2426A3A#03#0306#
DownPartnerBarcode	Barcode downstream network partner. This value will be generated for Combilabel shipments	EA123456785NL
DownPartnerID	Identification downstream network partner. This value will be generated for Combilabel shipments.	EURODIS
Labels	The list with the generated labels.
ProductCodeDelivery	Product code of the shipment. This value can be changed by the label generation process.	3085
Warnings	List of warnings

Label type

Attribute	Description	Example
Content	Base64 encoded binary label See Guidelines
Contenttype	Content type of the label, e.g. zebra of pdf. See Guidelines Note: It is not recommended to send .PDF files/labels directly to a Zebra printer. See Guidelines	PDF
Labeltype	Type of the label See Guidelines	Label

Warning type

Attribute	Description	Example
Code	Warning code	1003
Description	Warning description	Validation failed for shipment

Example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GenerateLabelResponse>
xmlns="http://postnl.nl/cif/services/LabellingWebService/"
xmlns:a="http://postnl.nl/cif/domain/LabellingWebService/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <a:MergedLabels i:nil="true"/>
      <a:ResponseShipments>
        <a:ResponseShipment>
          <a:Barcode>3SABCD6659149</a:Barcode>
          <a:DownPartnerBarcode i:nil="true"/>
          <a:DownPartnerID i:nil="true"/>
          <a:DownPartnerLocation i:nil="true"/>
          <a:Labels>
            <a:Label>
              <a:Content>JVBERi0xL[TRUNCATED BASE64 STRING]</a:Content>
              <a:Contenttype i:nil="true"/>
              <a:Labeltype>Label</a:Labeltype>
            </a:Label>
          </a:Labels>
          <a:ProductCodeDelivery>3085</a:ProductCodeDelivery>
          <a:Warnings i:nil="true"/>
        </a:ResponseShipment>
      </a:ResponseShipments>
    </GenerateLabelResponse>
  </s:Body>
</s:Envelope>