API documentation
Adrescheck Internationaal v1
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.
Summary
Use this API to validate and enrich international address data that is entered in your webshop or CRM.
Methods and endpoints
| Method | Endpoint |
| POST | https://api.postnl.nl/address/international/v1/validate |
Required headers
| Key | Value |
| Content-Type | Application/json |
| apikey | <your apikey> |
Input parameters
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 |
Output parameters
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 |
Example request & response
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" ] } |
Possible error codes
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. |