API documentation
Klant in beeld
Summary
Use this API to get real-time information about all 7.8 million Dutch households to gain customer insights and increase your conversion rates through personalized and relevant communication.
Methods and endpoints
| Method | Endpoint |
| POST | https://api.postnl.nl/address/national/insight/v1/basic |
Required headers
| Header key | Header value | Mandatory/optional |
| apikey | Your apikey | Mandatory |
| Content-Type | application/json | Mandatory |
Input parameters
| Fieldname | Mandatory/optional | Format | Example |
| PostalCode | Mandatory | String [6] | 1234AB |
| HouseNumber | Mandatory | String or Number [1-5] | 123 (only numerical values allowed) |
| HouseNumberAddition | Optional | String [0-6] | A / a / a2 |
| Selection | Mandatory | List of strings | ["Segments", "LivingArea", "CommercialActivity"] |
Explanation of field ‘Selection’
With the Selection input field, you can select the fields you want to get.
This input field expects an array of strings, where each string contains the name of the output field you are interested in. There is an extra option: you can also select a full domain by using the name of the domain instead of listing all its corresponding fields. If you mistype or use a fieldname that is not listed, it will be ignored. Please be aware that an additional fee will be charged if more than 10 different fields are requested during the license period.
A requested field that has a classification, can also be extended with a language label, with NL or EN. The response will then return the label itself. For example: PropertyType will return the classified code ‘1'. PropertyTypeNL will return ‘Vrijstaande woning’ and PropertyTypeEN will return ‘Detached house'. So, a selection like [“Segments”, “PropertyType”] or [“SegmentsEN”, “PropertyTypeEN”] are equally valid. Another example is PlotArea, this is always a number (and isn't a classification), therefore PlotAreaNL is ignored. The last column in the below table specifies if the field can be extended with NL or EN.
Output parameters
The expected output depends on the fields you have selected, the Address domain is always returned.
You can find all output fields, including their descriptions and formatting in the downloadable documentation.
Example request & response
| Request | Response |
{ "PostalCode": "1234AB", "HouseNumber": "123", "HouseNumberAddition": "", "Selection": [ "Segment", "SegmentEN", "PropertyType", "PropertyTypeNL", "PropertyValuationClassificationEN", "AgeHeadOfHousehold", "NumberOfCarsInHouseholdEN", "LifestageEN", "GrossFamilyIncome", "GrossFamilyIncomeEN", "NumberOfPeopleWithIncomeFromWork", "WhizeSegment" ] } | [ { "Address": { "PostalCode": "1234AB", "HouseNumber": 123, "HouseNumberAddition": "" }, "Residence": { "PropertyType": 1, "PropertyTypeNL": "Vrijstaande woning", "PropertyValuationClassificationEN": "750.000+" }, "SocioDemographic": { "AgeHeadOfHousehold": 9, "Lifestage": 7, "LifestageEN": "Singles orcoupleswithoutchildren, 50-64" }, "SocioEconomic": { "GrossFamilyIncome": 5, "NumberOfPeopleWithIncomeFromWork": 2, "GrossFamilyIncomeEN": "Morethandoubletheaverage", "NumberOfCarsInHouseholdEN": "Twoor morecars" }, "Segments": { "Segment": "K", "SegmentEN": "K - Life ofLuxury" } } ] |
Possible error codes
| HTTP status code | Explenation of the response |
| 200 | JSON response with requested data. If no address if found, an empty list is returned. |
| 400 | Error on customer-side. E.g. when not enough parameters are given. |
| 500 | Error on PostNL side. |
Response labels
You can find all response labels, including their descriptions in the downloadable documentation.