Documentation

Adrescheck Benelux

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

 

Input headers for API

Header key

Header value

Mandatory/optional

apikey

Your apikey

Mandatory

Content-Type

application/json

Mandatory

 

Input for API

Although only CountryIso is marked as mandatory, we require more input for a proper search. More input data allows us to give   

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

 


Expected output from API

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.