Postnl.nl

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

MethodEndpoint
GEThttps://api.postnl.nl/address/national/basic/v1/citystreetname
GEThttps://api.postnl.nl/address/national/basic/v1/postalcode

Required headers

KeyValue
Content-TypeApplication/json
apikey< your apikey >

Input parameters

For endpoint citystreetname:

FieldnameMandatory/optionalFormatExample
postalcodeMandatoryString [6]1234AB

For endpoint postalcode:

FieldnameMandatory/optionalFormatExample
postalcodeMandatoryString [6]1234AB
housenumberMandatoryNumber [1-5]123 (only numerical values allowed)

Output parameters

For endpoint citystreetname:

FieldnameDescription of attributeFormat [lenght]
cityCity of requested postalcodeString [1-35]
streetNameStreet of requested postalcodeString [1-95]

For endpoint postalcode:

FieldnameDescription of attributeFormat [length]
statusIndicator whether we found a matching result (values 0 or 1)String [1]
cityCity of requested addressString [1-35]
postalCodePostalcode of requested addressString [6]
streetNameStreet of requested addressString [1-95]
houseNumberHousenumber of requested addressNumber [1-5]
areaCodeAreacode of requested addressString [3-4]

Example request & response

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

RequestResponse
Params:
postalcode: 2242LE
Housenumber: 189

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

Possible error codes

Status codeStatus message
200JSON response with requested data.
200If 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"
        }
    ]
}

500Error on PostNL side.