Documentation REST

Adrescheck Nationaal

Summary

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

Method

The following methods are defined within the Adrescheck Nationaal.

Method
Description
https://api.postnl.nl/address/national/v1/validate
API that validates national 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

Use of services

Calling a service

A service is called by sending a message to a service endpoint. The message contains a header with security information (API-key) and the content type. The body contains the service method and related parameters.

Below you can see examples of the header and body, within Postman (an API tool to visualize APIs). Please note: the content used is purely for illustration purposes.

Example header (paste the API in “{{apikey}}”:

Adrescheck Nationaal - API key

Example body:

Adrescheck Nationaal - Example body

Each message that is received by the API is authenticated and authorized. The authorization mechanism determines if the user has access to the requested service.

After processing the request, the service will return a message with a response. The message contains a body with the information.

Parameter specification / field order

For each API, the parameters of a service are specified. Also, the behavior of these parameters are detailed. It is important to maintain the exact order of the fields as specified in the documentation tab. Changing the order of fields will result in unspecified errors returned back at the client.

Security information

Each service is secured with an API-key. You can find your API-key in the API Manager. The API manager is secured with a username and password. If you don’t have credentials for API manager yet, please fill in the form on this link.

Call details

Preview the API call buildup below. 

Method: https://api.postnl.nl/address/national/v1/validate

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

Input

{
    "PostalCode": "2132WT", 
    "City": " ",
    "Street": " ",
    "HouseNumber": "42",
    "Addition": "A"
}

Output

[
  {
    "City": "HOOFDDORP",
    "PostalCode": "2132WT",
    "Street": "Siriusdreef",
    "HouseNumber":42,
    "Addition": "A",
    "FormattedAddress": [
      "Siriusdreef 42 A",
      "2132WT HOOFDDORP"
    ]
  }
]

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

Input

{
    "PostalCode": "2132WT", 
    "City": " ",
    "Street": " ",
    "HouseNumber": "44444",
    "Addition": " "
}

Output

[
  {
      []
    ]
  }
]

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 Addition 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 + Addition

1. existing Postalcode + Housenumber, in the scenario that all these combinations contain an Addition.

All adresses that are known are returned, including subnumbers (for example the Addition “A” is given while only “A01”and “A02” exist).
If the given Addition is not found, all Addresses with Additions are returned for the user to choose from.

Input = Postalcode + Housenumber + Addition

2. non-existing Postalcode + Housenumber with an Adddition. In those cases that only addresses including an Addition exist.

Error

Input = Postalcode + Housenumber + Addition

3. existing Postalcode + Housenumber. In those cases that Addresses with and without known Additions exist.

All adresses that are known are returned, including subnumbers (for example the Addition “A” is given while only  “A01”and “A02” exist).
If the given Addition is not found, all Addresses with Additions are returned for the user to choose from.

Input = Postalcode + Housenumber + Addition

4. non-existing Postalcode + Housenumber. In those cases that Addresses with and without known Additions exist.

Error

Input = Postalcode + Housenumber + Addition

5. existing Postalcode + Housenumber. In those cases that no known Additions exist.

All adresses that are known are returned, including subnumbers (for example the Addition “A” is given while only “A01”and “A02” exist).
If the given Addition is not found, all Addresses with Additions are returned for the user to choose from.

Input = Postalcode + Housenumber + Addition

6. non-existing Postalcode + Housenumber with no known Additions

Error

Input = Street + Housenumber + Addition + City

1. existing Street + existing City + Housenumber. In those cases that only addresses including an Addition exist.

All adresses that are known are returned, including subnumbers (for example the Addition “A” is given while only “A01”and “A02” exist).
If the given Addition is not found, all Addresses with Additions are returned for the user to choose from.

Input = Street + Housenumber + Addition + City

2. existing Street + non-existing City + Housenumber.  In those cases that only addresses including an Addition exist.

Error

Input = Street + Housenumber + Addition + City

3. existing Street + existing City + Housenumber. In those cases that Addresses with and without known Additions exist.

All adresses that are known are returned, including subnumbers (for example the Addition “A” is given while only “A01”and “A02” exist).
If the given Addition is not found, all Addresses with Additions are returned for the user to choose from.

Input = Street + Housenumber + Addition + City

4. existing Street + non-existing City + Housenumber. In those cases that Addresses with and without known Additions exist.

Error

Input = Street + Housenumber + Addition + City

5. existing Street + existing City + Housenumber. In those cases that no known Additions exist.

All adresses that are known are returned, including subnumbers (for example the Addition “A” is given while only  “A01”and “A02” exist).
If the given Addition is not found, all Addresses with Additions are returned for the user to choose from.

Input = Street + Housenumber + Addition + City

6. existing Street + non-existing City + Housenumber with no known Additions.

Error

Input = Street + Housenumber + Addition + City

7. non-existing Street + existing City + Housenumber. In those cases that only addresses including an Addition exist.

All adresses that are known are returned, including subnumbers (for example the Addition “A” is given while only “A01”and “A02” exist).
If the given Addition is not found, all Addresses with Additions are returned for the user to choose from.

Input = Street + Housenumber + Addition + City

8. non-existing Street + non-existing City + Housenumber. In those cases that only addresses including an Addition exist.

Error

Input = Street + Housenumber + Addition + City

9. non-existing Street + existing City + Housenumber. In those cases that Addresses with and without known Additions exist.

If possible suggestions

Input = Street + Housenumber + Addition + City

10. non-existing Street + non-existing City + Housenumber. In those cases that Addresses with and without known Additions exist.

Error

Input = Street + Housenumber + Addition + City

11. non-existing Street + existing City + Housenumber. In those cases that no known Additions exist.

If possible suggestions

Requests

The following input parameters should be used

AttributeMandatoryFormatDescriptionExample
CountryString [2]The ISO2 country codesNL
StreetString [0-95]The streetname of the delivery addressSiriusdreef
HouseNumberString [0-35]The housenumber of the delivery address42
AdditionString [0-35]Housenumber extensionA
PostalCodeString [4-10]Zipcode of the address2132WT
CityString [0-35]City of the addressHoofddorp


The following output parameters are returned:

AttributeFormatDescriptionExample
StreetString [0-95]The streetname of the delivery addressSiriusdreef
HouseNumberString [0-35]The housenumber of the delivery address42
AdditionString [0-35]Housenumber extensionA
PostalCodeString [4-10]Zipcode of the address2132WT
CityString [0-35]City of the address HOOFDDORP
FormattedAddress3 Strings [0-95]Full formatted addressSiriusdreef 42 A 2132WT HOOFDDORP