Please note that we have replaced this API with a newer version (v3) that also supports an autocomplete functionality. If you are an existing customer, and haven’t been contacted by our support team yet, we kindly request you to get in touch with us so that we can support you in your transition to v3. If you are a new customer, we will only provide you with access to the newer v3 version of this API.
| Method | Endpoint |
| POST | https://api.postnl.nl/address/international/v1/validate |
| Key | Value |
| Content-Type | Application/json |
| apikey | <your apikey> |
Fieldname | Mandatory/optional | Format | Example |
Country | Mandatory | String [3] | BEL |
City | Optional | String [0-50] | Antwerpen |
PostalCode | Optional | String [0-16] | 2000 |
Street | Optional | String [0-50] | Oude Koornmarkt |
HouseNumber | Optional | String or Number [0-8] | 39 |
Building | Optional | String [0-50] | Unit 28D |
SubBuilding | Optional | String [0-50] | 3 high |
Fieldname | Description of attribute | Format [length] |
ResultNumber | The number of results (multiple addresses in the response is temporarily unavailable) | Number [0-5] |
MailabilityScore | Indication of certainty that the address is mailable | Number [0-3] |
ResultPercentage | Level of similarity between the input and output address data | Number [0-3] |
Country | Country of the address | String [0-95] |
Street | Street name of the address | String [0-95] |
HouseNumber | House number of the address | Number [0-35] |
PostalCode | Postal code of the address | String [4-10] |
City | City of the address | String [0-35] |
Province | Province of the city where the address is based in | String [0-95] |
FormattedAddress | The full address according to local/national formatting standards | Array of strings, dependent on formatting standards |
Request | Response |
{ "City": "Antwerpen", "Country": "BEL", "PostalCode": "2000", "Street" : "Oude Koornmarkt", "HouseNumber" : "39", "Building" : "", "SubBuilding" : "" } | { "ResultNumber": 1, "MailabilityScore": 100, "ResultPercentage": 100, "Country": "Belgium", "Street": "Oude Koornmarkt", "HouseNumber": 39, "PostalCode": "2000", "City": "Antwerpen", "Province": "Antwerpen", "FormattedAddress": [ "Oude Koornmarkt 39", "2000 Antwerpen", "Belgium" ] } |
Error code | Error message |
200 | JSON response with requested data. |
4xx | Error on customer-side. Example:
"code": 400, "message": "Invalid request", "errors": { "countryCode": "This value is not valid." } } |
500 | Error on PostNL side. |