Postnl.nl

Documentation

Bedrijfscheck Nationaal

Summary

Bedrijfscheck Nationaal is a combination of search-Method for finding companies and detail-Methods for retrieving detailed information. These are stackable, for instance when an end user selects the correct company from the initial search input and wishes to drill down on company details.

In case the (1) kvknumber plus branchnumber or (2) postnlkey is known on beforehand, detailed information is direct available via a request through Method 5 and Method 6.

Methods

Bedrijfscheck Nationaal defines the following methods:

nr

Endpoints

Description

1

https://api.postnl.nl/company/search/v3/companysearch

companysearch: returns basic information about organizations, based on official numerical references

2

https://api.postnl.nl/company/search/v3/companynameandaddress


companynameandaddress: returns basic information about organizations, based on a name and optional address components

3

https://api.postnl.nl/company/search/v3/companyaddress


companyaddress: returns basic information about organizations, based on address components

4

https://api.postnl.nl/company/search/v3/companyphone


companyphone: returns basic information about organizations, based on a general telephone number

5

https://api.postnl.nl/company/detail/v3/companydetails

companydetails: returns detailed information about organizations, based on official numerical reference or postnlkey

6

https://api.postnl.nl/company/detail/v3/companydetailsextra

companydetailsextra: returns detailed information about organizations, including relations per responsibility, based on official numerical reference or postnlkey

7

https://api.postnl.nl/company/v1/authorizedsignatory

companyauthorization: returns specific information about signing authorities, based on official numerical reference or postnlkey

8

https://api.postnl.nl/company/v1/cocextract


companyextract: [available  soon] returns the extract of chamber of commerce, based on official numerical reference or postnlkey

Call details

  • Bedrijfscheck Nationaal uses the GET method.
  • Use strings with all input parameters.
  • Consider field input capital insensitive and field names capital sensitive.
  • Search Methods provide 1000 results or less, where pagination returns <= 50 results per call.
  • Detail Methods return <= 1 result.

Guidelines

Combining Methods, a regex example

Suppose your product owner / client wishes an input field that multiple inputs: kvknumber, some address component and a company name.
In this case REGEX might be of assistance:
    • Find word boundaries with \b in regex (source)

  • Identify real postal codes with regex [1-9][0-9]{3} ?(?!sa|sd|ss)[a-z]{2} (source)
  • Identify kvknumber / chamber fo commerce identifier with regex [0-9]{5,8}

Use your if/elses right for choosing the right and fastest method in each case:

  • Method 1 for kvknumber
  • Method 2 for company name with optional address component, like an easy recognizable ZIP code.
  • Method 3 for searching on ZIP code only
  • Method 4 for fuzzysearch

Input Parameters

The parameters you can use in the methods diver between the methods. In the companysearch method four combinations of mandatory (M) and optional (O) parameters are possible.

INPUT method 1 companysearch

Attribute

Mandatory / Optional

Description

Example

 

Comb 1

Comb 2

Comb 3

Comb 4

 

 

kvknumber

M

 O

M

 O

Chamber of Commerce (CoC) identification number.
maxLength: 8 **, ***

34117529 (OR 7 digit CoC identification number)

branchnumber

M

M

 O

CoC-location identification number.

maxLength: 12 **, ***
Dutch: vestigingsnummer

17063566 OR 000017063566 OR FU1003490558

rsin

 

 

 

M

Legal Entities and Partnerships Information Number.

maxLength: 9 **

1004784700 OR 001004784700

fuzzysearchOOOOFuzzy searching for a company by name, kvknumber, streetname and/or citynamePostNL Waldorpstraat

includeinactive

O

O

O

O

Default = 0. Set to 1 for excluding inactive organisations.

0

mainbranch

O

O

O

O

Default = 1. Set to 0 for excluding main branches.*
Dutch: hoofdvestiging

1

branch

O

O

O

O

Default = 1. Set to 0 for excluding branches.*
Dutch: nevenvestiging

1

maxresultsperpage

O

O

O

O

Default = 50. Set between 1 and 50.

50

requestedpage

O

O

O

O

Default is 1. Use requested pages for implementing pagination.

1

 

 

 

 

 

 

Example Request companysearch:

{
"kvknumber": "34117529",
"branchnumber": "17063566",
"rsin": "",
"includeinactive": "0",
"mainbranch": "1",
"branch": "1",
"maxresultsperpage": "50",
"requestedpage": "1"
}

* In case both branch & mainbranch are unintentionally disabled, the two zero’s add up to two ones and lead to a result set.

** Kvknumbers, branchnumbers and rsinnumbers without leading zero’s are acceptable input, and autocompleted with leading zero’s. Please note that branchnumbers starting with chars [A-Z] instead of leading zero’s need an exact input.

*** At least a kvkNumber or a branchNumber or a rsin is mandatory input.

INPUT method 2 companysearch

Attribute

Mandatory / Optional

Description

Example

companyname

O

Finds organizations by companyname, legalname and tradename ( max 255 alphanumerical chars ). Uses a mix of exact words, beginning of words and fuzzy matching. *, ***, ****

PostNL Data Solutions B.V., Data Sol, PostNL, …

FuzzysearchOFuzzy searching for a company by name, kvknumber, streetname, postalcode and/or city namePostNL Waldorpstraat

branchstreetname

O

location: street name (NEN, max 80 chars)

Prinses Beatrixlaan

branchhousenumber

O

location: house number (max 5 digits)

23

branchhousenumberaddition

O

location: house number addition (max 20 chars)

 

branchpostalcode

O

location: postal code ( [1-9][0-9]{3}[a-z]{2} , no spaces)

2595AK

branchcity

O

location: city (NEN, max 80 digits)

'S-GRAVENHAGE

includebranchaddress

O

Default = 1. Set to 0 for excluding search on branchaddress (often a visiting location)

1

includemailingaddress

O

Default = 1. Set to 0 for excluding search on mailingaddress (like a PO BOX)

1

includeinactive

O

Default = 0. Set to 1 for including inactive organisations

0

mainbranch

O

Default = 1. Set to 0 for excluding main branches. **
Dutch: hoofdvestiging

1

branch

O

Default = 1. Set to 0 for excluding branches. **
Dutch: nevenvestiging

1

maxresultsperpage

O

Default = 50. Set between 1 and 50.

50

requestedpage

O

Default is 1. Use requested pages for implementing pagination.

1

Example Request companynameandaddress:

{
"companyname": "Data Sol",
"branchstreetname": "Beatrixlaan",
"branchhousenumber": "",
"branchhousenumberaddition": "",
"branchpostalcode": "",
"branchcity": "Den Haag",
"includebranchaddress": "1",
"includemailingaddress": "1",
"includeinactive": "0",
"mainbranch": "1"
"branch": "1",
"maxresultsperpage": "50",
"requestedpage": "1"
}

* Method 2 returns a maximum of 1000 results. Inclusion of at least one address component, optimizes both responsetime and number of search results.

**In case both branch & mainbranch are unintentionally disabled, the two zero’s add up to two ones and lead to a result set.

*** Fuzzy matching orders the results by similarity, not alphabetically.

**** Examples of companyname and using optional address components to zoom in towards a single result:

Input

Output

Advise / tips

PostNL Data Solutions

1 result

 

Data Solutions

142 results

Be more precise, i.e. by adding a postal code: + ‘2595AK’

Data Sol

147 results

Be more precise, i.e. by excluding commercially inactive organisations

PostNL data

3 results

Be more precise, i.e. by adding a city

PostNL

> 600 results

Be more precise, i.e. by excluding ‘branches’ or by adding a city

dataqualitybrowser.nl

1 result

Tradenames are often filled with registered url’s

PastNL

33 results on PostNL

Beware of Typo’s.

océ

> 1000 results.

Use an address component i.e. ‘venlo’ to find Océ-Technologies

Oce

> 1000 results, starting with ‘Ocean’-like results

Be more precise, i.e. Océ-Technologies

Océtech

Ocatech

Be more precise, i.e. Océ-Technologies

oninklijke postnl NV + 2595AK

[ ]

Use 'koninklijke post' + 2595AK to find PostNL

stichting + amsterdam

> 1000 results

Use an additional address component to narrow down your search, or specify the company name, i.e. ‘waag.org’ or ‘stichting society’.

vis+scheveningen

754 ‘vis’ related results in ‘s-Gravenhage’

The city name accepts formal entries, like ”‘s-Gravenhage”. It also accepts most locally accepted variations, like “Den Haag” and “Scheveningen”.

Vis+Velp

32 results in both ‘Velp NB and Velp GLD’

Add provincial code to single out a city in case of Velp, Oosterhout and other cities that exist in multiple Dutch areas.

VVE + 2312JS

0 results

Add the name of this particular vve (for example ‘zijlroos’) OR try v.v.e. OR use ‘vve’ + cityname: ‘Leiden’

VVE + Leiden

> 1000 results

Be more precise, i.e. by adding a streetname

V.V.E. + Leiden

> 1000 results

Be more precise, i.e. by adding a streetname

Bank BV + ‘s- Gravenhage

> 1000 results

Be more precise, i.e. by extending a company name

Bank B.V. + ‘s- Gravenhage

> 1000 results

Be more precise, i.e. by extending a company name

INPUT method 3 companysearch

Attribute

Mandatory / Optional

Description

Example

branchstreetname

O

location: street name (NEN, max 80 chars)

Prinses Beatrixlaan *

branchhousenumber

O

location: house number (max 5 digits)

23 *

branchhousenumberaddition

O

location: house number addition (max 20 chars)

 

branchpostalcode

O

location: postal code ( [1-9][0-9]{3}[a-z]{2} , no spaces)

2595AK

branchcity

O

location: city (NEN, max 80 digits)

'S-GRAVENHAGE

includebranchaddress

O

Default = 1. Set to 0 for excluding search on branchaddress (often a visiting location)

1

includemailingaddress

O

Default = 1. Set to 0 for excluding search on  mailingaddress (like a PO BOX)

1

includeinactive

O

Default = 0. Set to 1 for including inactive organisations **

0

mainbranch

O

Default = 1. Set to 0 for excluding main branches. **
Dutch: hoofdvestiging

1

branch

O

Default = 1. Set to 0 for excluding branches. **
Dutch: nevenvestiging

1

maxresultsperpage

O

Default = 50. Set between 1 and 50.

50

requestedpage

O

Default is 1. Use requested pages for implementing pagination.

1

* At least the combination of 'kvknumber' and 'branchnumber', or 'postnlkey' is mandatory input. Methods 5 & 6 result in 1 output. Input of 'kvknumber' only is only accepted when this 'kvknumber' has no branch numbers registred to it. Some companies have multiple branch numbers. In that case input of 'branchnumber' is mandatory as well. Please note that only the combined input of 'kvknumber' and 'branchnumber' create a unique and solid id.
** 'kvknumber' and 'branchnumber' without leading zero’s are acceptable input, and autocompleted with leading zeroes. Please note that branch numbers starting with chars [A-Z] instead of leading zero’s need an exact input.
*** In case both branch & mainbranch are unintentionally disabled, the two zeroes are neglected.

GOOD PRACTICES

STACK Methods
* Use the postnlkey from the search call (Method 1 to 4) to get detailed information.
* To retrieve a single result, use (a) a combination of kvknumber + branchnumber, or (b) postnlkey. In case of (a), organizations that only have a kvknumber, use an empty branchnumber as input.

OUTPUT methods 5,6 and 7

The combination of kvknumber = 27124700 and branchnumber 17527368 returns the following output:

Method 1/4Method 5Method 6Method 7AttributeDescriptionExample
 totalPagesNumber of pages returned1
 requestedPageCurrent result page1
 resultCountnumber of organizations returned1
companyNameorganizational nameKoninklijke Postnl B.V.
kvkNumberCoC identification number 27124700
(8 digit)
postnlKeyPostNL identification number 1004364844
(12 digit)
branchNumberlocation: number 17527368
(12 digit)
 branchStreetNamelocation: street name Prinses Beatrixlaan
(NEN, max 80 chars)
 branchHouseNumberlocation: house number 23
(max 5 digits)
 branchHouseNumberAdditionlocation: house number addition (max 20 chars) 
 branchPostalCodelocation: postal code 2595AK
( [1-9][0-9]{3}[a-z]{2} , no spaces)
 branchCitylocation: city 'S-GRAVENHAGE
(NEN, max 80 digits)
   companyPhoneNumbermain phone number9000990
   companyMobilePhoneNumbermain mobile phone number 
  mailingStreetNamemailing: street name Prinses Beatrixlaan
(NEN, max 80 chars)
  mailingHouseNumbermailing: house number 23
(max 5 digits)
  mailingHouseNumberAdditionmailing: number addition  
(max 20 chars)
  mailingPostalCodemailing: postal code ( [1-9][0-9]{3}[a-z]{2} , no spaces)2595AK
  mailingCitymailing: city (NEN, max 80 digits)'S-GRAVENHAGE
rsinLegal Entities and Partnerships Information Number (9 digit)9291477
legalTypeCdlegal type (2 digit) *41
legalTypeDesclegal type description (length) *Besloten vennootschap gewone structuur
 registrationDatedate of registration at CoC1-1-1989
  foundingDatefounding date1-1-1989
  registrationReasonCdregistration reason code **31
  registrationReasonDescregistration reason description **Voortzetting
 bankruptIndBankrupt status: N
J (bankrupt) or 
N (not bankrupt)
 surceanceIndSurceance status: N
J (surceance) or 
N (no surceance)
commercialIndindicator commercially active: J
J (commercially active) or 
N (commercially inactive)
headOfficeIndindicator head office: H
H (head office, aka mainbranch) or
N (branch) or
NULL (empty: unknown)
 allowDmIndindicator direct marketing via mail allowed:J
J (allowed) or 
N (not allowed)

active

true (still registered at KVK) or false (not subscribed at KVK anymore)

true
 urlwebsite (max 255 chars)www.postnl.nl
 legalNamePartnerschip name Koninklijke Postnl B.V.
(maxLength = 132 chars) 
Dutch: Vennootschapsnaam
 tradeNamesArray with up to 10 alternative trade namesCENDRIS (Koninklijke TNT Post), CENDRIS (Koninklijke TNT Post), …
  xCoordinatex Coordinate82.933.668
  yCoordinatey Coordinate455.008.433
  longitudelongitude4.335.907
  latitudelatitude52.078.657
  cbiCdsarray with PostNL Company Activity Code (CBI is an extension of the CoC SBI-code, 4 or 5 digit)5310, 7490, 6832
  cbiDescriptionCBI / SBI Description 
  numberOfEmployeesamount of employees44704
  numberOfFteEmployeesamount of FTE employees44704
  numberOfAGWPamount of workspaces11176
  kvkPersonobject, 1st kvk registrant 
   functionCdkvk registrant function code ***0
   functionDesckvk registrant function description ***Onbekend
   initialskvk registrant initialsJ.J.P.
   prefixkvk registrant prefix 
   lastnamekvk registrant last nameBos
   genderkvk registrant genderM
   dmuPersonsarray, Decision Making Units 8
objects
   functionCddmu registrant function code1
   functionDescdmu registrant function descriptionAlgemeen directeur
   initialsdmu registrant initialsJ.J.P.
   prefixdmu registrant prefix 
   lastnamedmu registrant last nameBos
   genderdmu registrant genderM
   functionCddmu registrant function code6
   functionDescdmu registrant function descriptionIT-manager
   initialsdmu registrant initialsM.J.M.
   prefixdmu registrant prefix 
   lastnamedmu registrant last nameKrom
   genderdmu registrant genderM
   … and more
  mhicCompanyNameultimate parent company namePostNL N.V.
  mhicPostnlKeyultimate parent postnlKey1004387646
  m1CompanyNameparent company namePostNL Holding B.V.
  m1PostnlKeyparent postnlKey1004387313
authorizedPersons
apFunctionThe function of the authorized signatoryProcuratiehouder
apTypeThe type of authority from the authorized signatoryBeperkt bevoegd
apInitialsThe initials of the authorized signatoryR.D.
apPrefixThe prefix of the authorized signatoryvan der
apLastNameThe lastname of the authorized signatoryMolen
apGenderThe gender of the authorized signatory M
authorizedCompanies 
acKvkNumberKvk number of the authorized company34278934
acNameThe name of the authorized companyPost NL
acFunctionThe function of the authorized companyDirecteur
acStartDateStartdate when the company was authorized8-6-2008
acPersonFunctionThe function of the person that is authorized for the authorized companyProcuratiehouder
acPersonTypeThe type of authority from the person that is authorized for the authorized companyBeperkt bevoegd
acPersonInitialsThe initials of the person that is authorized for the authorized companyR.D.
acPersonPrefixThe prefix of the person that is authorized for the authorized companyvan der
acPersonLastNameThe prefix of the person that is authorized for the authorized companyMolen
acPersonGenderThe gender of the person that is authorized for the authorized companyM


* See this list (Dutch) for more examples oflegalTypeCd and legalTypeDesc.

** See this list(Dutch) for more examples ofregistrationReasonCd and registrationReasonDesc.

*** See this list(Dutch) for more examples of dmuPersons, functionCd and functionDesc.