API documentation

Adrescheck Basis Nationaal v1

Summary

Use this API to validate and enrich the Dutch address data that is entered in your webshop or CRM. Validations can be done with either combination of input: PostalCode+HouseNumber or City+Street+Housenumber. The field ‘Addition’ is always optional. When using City+Street+HouseNumber, we use ‘approximate string matching’ also known as ‘Fuzzy search’. Therefore, typo's are allowed.

Methods and endpoints

Method	Endpoint
GET	https://api.postnl.nl/address/national/basic/v1/citystreetname
GET	https://api.postnl.nl/address/national/basic/v1/postalcode

Required headers

Key	Value
Content-Type	Application/json
apikey	< your apikey >

Input parameters

For endpoint citystreetname:

Fieldname	Mandatory/optional	Format	Example
postalcode	Mandatory	String [6]	1234AB

For endpoint postalcode:

Fieldname	Mandatory/optional	Format	Example
postalcode	Mandatory	String [6]	1234AB
housenumber	Mandatory	Number [1-5]	123 (only numerical values allowed)

Output parameters

For endpoint citystreetname:

Fieldname	Description of attribute	Format [lenght]
city	City of requested postalcode	String [1-35]
streetName	Street of requested postalcode	String [1-95]

For endpoint postalcode:

Fieldname	Description of attribute	Format [length]
status	Indicator whether we found a matching result (values 0 or 1)	String [1]
city	City of requested address	String [1-35]
postalCode	Postalcode of requested address	String [6]
streetName	Street of requested address	String [1-95]
houseNumber	Housenumber of requested address	Number [1-5]
areaCode	Areacode of requested address	String [3-4]

Example request & response

Examples of all possible requests can be found in the Postman collections.

Request	Response
Params: postalcode: 2242LE Housenumber: 189	[ { "status": "1", "streetName": "V Zuylen van Nijeveltstr", "houseNumber": "189", "postalCode": "2242LE", "city": "WASSENAAR", "areaCode": "070" } ]

Possible error codes

Status code	Status message
200	JSON response with requested data.
200	If no address was found, we return statusfield 0.
4xx	Error on customer-side. Example: { "errors": [ { "status": "400", "title": "Bad Request", "detail": "postalcode has the wrong format. It should be: 1234AB" } ] }
500	Error on PostNL side.