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

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

AttributeMandatoryFormatDescriptionExample
postalcodeMString [4-10]Zipcode of the delivery address2132WT
housenumberMString [0-35]The housenumber of the delivery address42
housenumberadditionOString [0-35]Housenumber extensionA

The following output parameters are returned:
AttributeFormatDescriptionExample
cityString [0-35]City of the address HOOFDDORP
postalCodeString [4-10]Zipcode of the address2132WT
streetNameString [0-35]The streetname of the delivery addressSiriusdreef
houseNumberString [4-10]The housenumber of the delivery address42
houseNumberAdditionString [0-35]Housenumber extensionA
FormattedAddress3 Strings [0-95]Full formatted addressSiriusdreef 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"]
    }
]