Postnl.nl

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

Required headers

KeyValue
Content-TypeApplication/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.