Documentation REST

Adrescheck Internationaal

Summary

Simply use the API to check address data that is entered in your webshop or CRM.

Method

The following methods are defined within the Adrescheck Internationaal 

MethodDescription
https://api.postnl.nl/address/international/v1/validateAPI that validates international addresses in a general format (send any of a list of pre-defined fields).
https://api.postnl.nl/address/international/v1/labelformat

API that validates international addresses in a label format (send 3 strings in unspecified order).

Note: This API supports the POST method.

Call details

Preview the API call buildup below.

Method: https://api.postnl.nl/address/international/v1/validate

Guidelines

Adrescheck Internationaal is available in 2 different forms that differ on the input fields structure. The different methods provide an optimal way to implement the address verification in your tooling (webform, CRM etc).

The following methods are defined within the Adrescheck Internationaal

1. General format (send any of a list of pre-defined fields). This method requires input in a fixed address format (varies per country), a fixed order of pre-defined fields that make up an address.

2. Label format (send strings in unspecified order). This methods required input in any order of pre-defined fields. For instance, users can first type the City, then the HouseNumber etc.

Scenario's

Scenario 1; When given correct input, the output should in most cases be a single output with a high mailability score and a high result score nearing 100.

Please note; The input set-up does not differ per country, although the use of elements differs per country. 

Scenario 2; If a perfect match cannot be made, multiple suggestions are returned to help you (or the end-user) choose one. In those cases up to 20 best results will be returned, sorted based on the mailability score and result percentage.

In general, to receive optimum results, it is advised to provide as many details in the input.

Please note; Although delimiters are no mandatory, better suggestions can be made for input with element separators (comma or semicolon). 

Requests

AttributeMandatoryFormatDescriptionExample
City String [0-35]City of the address MILANO
Country String [3]The ISO country codesITA
PostalCode String [4-10]Zipcode of the address20138
Street String [0-95]The streetname of the delivery addressVIA GAUDENZIO FANTOLI
HouseNumber String [0-35]The housenumber of the delivery address6
Building String [0-95]Name of the building 
SubBuilding String [0-95]Name of the sub building 

Result:

AttributeFormatDescriptionExample
ResultNumberString [0-50]The number of results13
MailabilityScoreString [0-3]The certainty level that the address is mailable50
ResultPercentageString [0-3]The level of matching of the output and the input100
CountryString [0-95]The country spelled out completelyITALY
StreetString [0-95]The street name of the delivery address.VIA GAUDENZIO FANTOLI
HouseNumberString [0-35]The house number of the delivery address6
PostalCodeString [4-10]Zipcode of the address20138
CityString [0-35]City of the address MILANO
Province2 Strings [0-95]Province of the City, and City (repeated) 
FormattedAddress3 Strings [0-95]Full formatted addressVIA GAUDENZIO FANTOLI 6
20138 MILANO
ITALY

Example (scenario 1)

Request

{
    "City": "Milano",
    "Country": "ITA",
    "PostalCode": "20138",
    "Street" : "Via Gaudenzio Fantoli",
    "HouseNumber" : "6",
    "Building" : "",
    "SubBuilding" : ""
}

Response

[
  {
    "ResultNumber": 1,
    "MailabilityScore": 100,
    "ResultPercentage": 100,
    "Country": "ITALY",
    "Province": "",
    "City": "MILANO",
    "PostalCode": 20128,
    "Street": "VIA GAUDENZIO FANTOLI",
    "HouseNumber": 6,
    "FormattedAddress": [
      "VIA GAUDENZIO FANTOLI 6",
      "20138 MILANO",
      "ITALY"
   ]
]

Example (scenario 2)

Request

{
    "City": "Milano",
    "Country": "ITA",
    "PostalCode": "0000000",
    "Street" : "Via Gaudenzio Fantoli",
    "HouseNumber" : "6",
    "Building" : "",
    "SubBuilding" : ""
}

Response

[
  {
    "ResultNumber": 1,
    "MailabilityScore": 60,
    "ResultPercentage": 50,
    "Country": "ITALY",
    "Province": "",
    "City": "MILANO",
    "PostalCode": 20128,
    "Street": "VIA GAUDENZIO FANTOLI",
    "HouseNumber": 6,
    "FormattedAddress": [
      "VIA GAUDENZIO FANTOLI 6",
      "20138 MILANO",
      "ITALY"
    ]


  },


  {

    "ResultNumber": 2,
    "MailabilityScore": 40,
    "ResultPercentage": 30,
    "Country": "ITALY",
    "Province": "",
    "City": "MILANO",
    "PostalCode": 20128,
    "Street": "VIA GAUDENZIO FANTOLI",
    "HouseNumber": 12,
    "FormattedAddress": [
      "VIA GAUDENZIO FANTOLI 12",
      "20138 MILANO",
      "ITALY"
    ]

  }

]