Summary
Use this API to validate international address data that is entered in your webshop or CRM. Only Belgian, Dutch or Luxembourg addresses are supported in this API. To validate international addresses outside of the Benelux, please consider our ‘Adrescheck Internationaal’.
Methods and endpoints
Method | Endpoint |
POST | https://api.postnl.nl/address/benelux/v1/validate |
Required headers
Header key | Header value | Mandatory/optional |
apikey | Your apikey | Mandatory |
Content-Type | application/json | Mandatory |
Input parameters
Although only CountryIso is marked as mandatory, we require more input for a proper search.
Fieldname | Mandatory/optional | Format | Example |
CountryIso | Mandatory | String [2] or [3] | BE / 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 |
HouseNumberAddition | Optional | String [0-50] | A |
Output parameters
Fieldname | Description of attribute | Format [length] |
ResultNumber | The number of results | Number [0-3] |
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] |
FormattedAddress | The full address according to local/national formatting standards | Array of strings, dependent on formatting standards |
Street | Street name of the address | String [0-95] |
HouseNumber | House number of the address | Number [0-35] |
HouseNumberAddition | House number addition of the address | Number [0-35] or null |
PostalCode | Postal code of the address | String [0-20] |
City | City of the address | String [0-35] |
Country | Country of the address | String [0-95] |
CountryIso2 | ISO 3166-1 alpha-2 code of the country of the address | String [2] |
CountryIso3 | ISO 3166-1 alpha-3 code of the country of the address | String [3] |
Locality | Locality of the address | String [0-95] |
State | State of the address | String [0-95] |
Latitude | Latitudinal coordinate of address | Number [0-15] |
Longitude | Longitudinal coordinate of address | Number [0-15] |
Example request & response
Request | Response |
{ "City": "Antwerpen", "CountryIso": "BEL", "PostalCode": "2000", "Street": "Oude Koornmarkt", "HouseNumber": "39", "HouseNumberAddition": "", } | [ { "ResultNumber": 1, "MailabilityScore": 100, "ResultPercentage": 100, "FormattedAddress": [ "Oude Koornmarkt 39", "2000 Antwerpen", "Belgium" ], "Street": "Oude Koornmarkt", "HouseNumber": 39, "HouseNumberAddition": null, "PostalCode": "2000", "City": "Antwerpen", "Country": "Belgium", "CountryIso2": "BE", "CountryIso3": "BEL", "Locality": "Antwerpen", "State": "Antwerpen", "Latitude": 51.219850780832545, "Longitude": 4.400407410011705 } ] |
Possible error codes
Error code | Error message |
200 | JSON response with requested data. |
206 | Address not found. Example:
'errors': [ { 'status': '206', 'title': 'Address Not Found', 'detail': 'The requested address is not found in our database' } ] } |
4xx | Error on customer-side. Example:
"errors": [ { "status": "400", "title": "Bad Request", "detail": "Query must include valid CountryIso" } ] } |
5xx | Error on PostNL side. |