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/shipment/checkout/v1/postalcodecheck | API that validates Dutch addresses in a general format (send any of a list of pre-defined fields) |
Unique Dutch addresses can be found based on the following input structure;
- Postalcode + HouseNumber + Addition (advised to include, although not all HouseNumber ranges include additions)
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.
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.
|
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).
|
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).
|
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 |
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 (lowerCamelCase) | 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"]
}
]