Documentation

Checkout Postalcode Check

Summary

Simply use the API to check Dutch address data that is entered in your webshop checkout.

Method

The following method is defined within the Checkout Postalcode Check

Method	Description
https://api.postnl.nl/address/national/v1/validate	API that validates Dutch addresses in a general format (send any of a list of pre-defined fields)

Please note: You can opt to require users to fill in a complete address (with all pre-defined fields that make up an address) or choose to only use a smaller set of fields. It can be attractive to use one of these input structures instead of requiring users to fill out a complete address format to help increase conversion rate of the form.

Unique Dutch addresses can be found based on the following 2 input structures (next to presenting all pre-defined fields) that make use of fewer input fields;

Postalcode + HouseNumber + Addition (advised to include, although not all HouseNumber ranges include additions)
Street + HouseNumber + Addition (advised to include, although not all HouseNumber ranges include additions) + City

Note: This API supports the POST method

Call details

Preview the API call buildup below.

Method: https://api.postnl.nl/shipment/checkout/v1/postalcodecheck

Guidelines

The Checkout Postalcode Check provides an optimal way to implement the address verification in the webshop checkout.

General format (send any of a list of pre-defined fields). You can opt to require users to fill in a complete address (with all pre-defined fields that make up an address) or choose to choose a subset of fields. Unique Dutch addresses can be found based on the postalcode+housenumber+housenumberaddition (dependent on the existence of an housenumberaddition in the housenumber range). It can be attractive to use this subset instead of requiring users to fill out a complete address format. To reduce the amount of fields the single line method can be, depending on your preference, even more attractive.

Scenario’s
Scenario 1; When given a correct Postalcode, Housenumber and Addition combination was entered, the output should be a single output.

Scenario 2; When the housenumber is not found for a given Postalcode, an empty response is returned.

Besides these two, numerous combinations are possible. Below there are listed, including the expected outcome.

Input	Scenario	Expected outcome
Input = postalcode + housenumber	1. existing postalcode + housenumber	All addresses with the exact postalcode-housenumber combination are returned. If there are known addresses with housenumberaddition for this this combination they are returned as well.
Input = postalcode + housenumber	2. non-existing postalcode + housenumber	Error
Input = postalcode + housenumber	3. existing postalcode + non-existing housenumber	Error
Input = postalcode + housenumber + housenumberaddition	1. existing postalcode + housenumber, in the scenario that all these combinations contain an housenumberaddition.	All addresses that are known are returned, including subnumbers (for example the housenumberaddition “A” is given while only “A01”and “A02” exist). If the given housenumberaddition is not found, all addresses with housenumberaddition are returned for the user to choose from.
Input = postalcode + housenumber + housenumberaddition	2. non-existing postalcode + housenumber with an housenumberaddition. In those cases that only addresses including an housenumberaddition exist.	Error
Input = postalcode + housenumber + housenumberaddition	3. existing postalcode + housenumber. In those cases that addresses with and without known housenumberaddition exist.	All addresses that are known are returned, including subnumbers (for example the housenumberaddition “A” is given while only “A01”and “A02” exist). If the given housenumberaddition is not found, all Addresses with housenumberaddition are returned for the user to choose from.
Input = postalcode + housenumber + housenumberaddition	4. non-existing postalcode + housenumber. In those cases that addresses with and without known housenumberaddition exist.	Error
Input = postalcode + housenumber + housenumberaddition	5. existing postalcode + housenumber. In those cases that no known housenumberaddition exist.	All addresses that are known are returned, including subnumbers (for example the housenumberaddition “A” is given while only “A01”and “A02” exist). If the given housenumberaddition is not found, all Addresses with housenumberaddition are returned for the user to choose from.
Input = postalcode + housenumber + housenumberaddition	6. non-existing postalcode + housenumber with no known housenumberaddition	Error

Request

The following input parameters should be used

Attribute	Mandatory	Format	Description	Example
postalcode	M	String [4-10]	Zipcode of the delivery address	2132WT
housenumber	M	String [0-35]	The housenumber of the delivery address	42
housenumberaddition	O	String [0-35]	Housenumber extension	A

The following output parameters are returned:

Attribute	Format	Description	Example
city	String [0-35]	City of the address	HOOFDDORP
postalCode	String [4-10]	Zipcode of the address	2132WT
streetName	String [0-35]	The streetname of the delivery address	Siriusdreef
houseNumber	String [4-10]	The housenumber of the delivery address	42
houseNumberAddition	String [0-35]	Housenumber extension	A
FormattedAddress	3 Strings [0-95]	Full formatted address	Siriusdreef 42 A 2132WT HOOFDDORP

Example

Request

{
    "postalcode": "2132WT", 
    "houseNumber": "42",
    "addition": "A"
}

Response

[
   {
       "city": "HOOFDDORP",
       "postalCode": "2132WT",
       "streetName": "Siriusdreef",
       "houseNumber":42,
       "houseNumberAddition": "A",
       "formattedAddress": [
       "Siriusdreef 42 A",
       "2132WT HOOFDDORP"]
    }
]