API documentation
Checkout Postalcode Check v1
Summary
Use this API to validate and enrich the Dutch address data that is entered in your webshop or CRM. Validations can only be done with input parameters PostalCode+HouseNumber.
Methods and endpoints
| Method | Endpoint |
| POST | https://api.postnl.nl/shipment/checkout/v1/postalcodecheck |
| GET | https://api.postnl.nl/shipment/checkout/v1/postalcodecheck |
Required headers
| Key | Value |
| Content-Type | Application/json |
| apikey | <your apikey> |
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 [6] | A / a / a2 |
Output parameters
| Fieldname | Description of attribute | Format [length] |
| city | City of requested address | String [1-35] |
| postalCode | Postalcode of requested address | String [6] |
| streetName | Street of requested address | String [1-95] |
| houseNumber | Housenumber of requested address | Number [1-5] |
| houseNumberAddition | Housenumber addition of requested address if applicable | String [6] or null |
| formattedAddress | Full formatted address according to PostNL standard | Array with 2 strings |
Example request & response
Examples of all possible requests can be found in the Postman collections.
| Request | Response |
| {
"postalcode": "1507TN", "housenumber": "6", "housenumberaddition": "" } | [ { "city": "ZAANDAM", "postalCode": "1507TN", "streetName": "Wals", "houseNumber": 6, "formattedAddress": [ "Wals 6 ", "1507TN ZAANDAM" ] } ] |
Possible error codes
| Error code | Error message |
| 200 | JSON response with requested data. |
| 200 | Address not found. Example: [] |
| 4xx | Error on customer-side. Example: "errors": [ { "status": "400", "title": "Bad Request", "detail": "PostalCode has the wrong format. It should be: 1234AB" } ] } |
| 500 | Error on PostNL side. |