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 and
    • Method 3 for searching on ZIP code only.

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

 

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

34117529 (OR 7 digit CoC identification number)

branchnumber

M

M

 

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

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 companynameandaddress

Attribute

Mandatory / Optional

Description

Example

companyname

M

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, …

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

Find additional streetname related examples in the next section, Method 3 Companyaddress.

INPUT method 3 companyaddress

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

Example companyaddress:

{
     "branchstreetname": "Prinses",
     "branchhousenumber": "23",
     "branchhousenumberaddition": "",
     "branchpostalcode": "",
     "branchcity": "'S-GRAVENHAGE",
     "includebranchaddress": "1",
     "includemailingaddress": "1",
     "includeinactive": "0",
     "mainbranch": "1",
     "branch": "1",
     "maxresultsperpage": "50",
     "requestedpage": "1"
}

* Use branchstreetname + branchhousenumber also for finding PO BOXes, for instance ‘Postbus’ + ‘3090’.

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

GOOD PRACTICES:

NARROW and WIDE SEARCH:
* All companysearch Methods are designed to quickly identify a unique organization within a shortlist. This shortlist is based on an end user’s search parameters. This does not withhold users to do a slower ‘wide’ search, like searching by input of postal code only. Other ‘wide’ searches – like searching only by housenumber, housenumberaddition or branchcity – return an empty result set and an error.

ADDRESS:
* Include companyaddress searches with input combinations like postal code + house number, streetname + housenumber and streetname + city.
* Note that streetnames can have different formats: NEN and Official. NEN is the shortened version of Official. About 4% of the NEN formats differ from the Official formats.
In case of street names, this product is initially build based upon NEN address formats. One of the NEN-protocols abbreviates street names to a maximum of 24 characters. In those cases it transforms suffixes like “straat”, “laan” and “weg” into respectively “str”, “ln” and “wg”. Shorter street names are written in full. The same goes for prefixes like “Burgemeester” (EN: “mayor”) that might be shortened to “Burg”.
Both Method 2 and Method 3 allow more fuzzy input of street names, resolving many official streetname formats as well, extending the search of NEN-formats of streetnames:

Input

Output

Advise / tips

Prof d Blécourtstraat

1 result

No tips ( NEN == Official, Professor d Blécourtstraat )

Blécourtstraat

1 result

No tips ( NEN == Official, Professor d Blécourtstraat )

Prof de Blécourtstraat

1 result

No tips ( NEN == Official, Professor d Blécourtstraat )

Professor d Blécourtstraat

1 result

No tips ( NEN == Official, Professor d Blécourtstraat )

Prof d Blécourtstr

1 result

No tips ( NEN == Official, Professor d Blécourtstraat )

Blécourtstr

1 result

No tips ( NEN == Official, Professor d Blécourtstraat )

Prof de Blécourtstr

1 result

No tips ( NEN == Official, Professor d Blécourtstraat )

Professor d Blécourtstr

1 result

No tips ( NEN == Officieel, Professor d Blécourtstraat )

Prod d becourstraat

0 results

Correct the typo

Meester Cornelius G Cremerpad

1 result

No tips (NEN = Mr Cornelius G Cremerpad, Official = Meester Cornelius G. Cremerpad)

Mr Cornelius G. Cremerpad

1 result

No tips (NEN = Mr Cornelius G Cremerpad, Official = Meester Cornelius G. Cremerpad)

Meester C G Cremerpad

0 results

Shorten the input to the main name ‘Cremerpad’ (NEN = Mr Cornelius G Cremerpad, Official = Meester Cornelius G. Cremerpad)

Meester Cornelius G. Cremerpd

1 result

No tips (NEN = Mr Cornelius G Cremerpad, Official = Meester Cornelius G. Cremerpad)

Meester Cornelius G. Cremerpad

1 result

No tips (NEN = Mr Cornelius G Cremerpad, Official = Meester Cornelius G. Cremerpad)

Cremerpad

1 result

No tips (NEN = Mr Cornelius G Cremerpad, Official = Meester Cornelius G. Cremerpad

See this list(Dutch) for more streetname examples.

INPUT method 4 companyphone

Attribute

Mandatory / Optional

Description

Example

phonenumber

M

10 digits and tolerating additional brackets andhyphenand aminus sign.

0882363747, (088)2363747, 088-2363747 or 088 2363 747

includeinactive

O

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

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

{
     "phonenumber": "0882363747",
     "includeinactive": "0",
     "mainbranch": "1",
     "branch": "1",
     "maxresultsperpage": "",
     "requestedpage": "1"
}

* In case both branch & mainbranch are unintentionally disabled, the two zero’s are neglected.


OUTPUT method 1 to 4

The Methods 1 to 4 deliver the same output structure. Using companysearch for example ( Method 1) and Combination 1, with kvknumber = 34117529 returns the following output:

Attribute

Description

Example

totalPages:

Number of pages returned

1

requestedPage:

Current result page

1

resultCount:

number of organizations returned

1

companyName

organizational name

PostNL Data Solutions B.V.

kvkNumber

CoC identification number (8 digit)

34117529

postnlKey

PostNL identification number (12 digit)

1004784700

branchNumber

location: number (12 digit)

000017063566

branchStreetName

location: street name (NEN, max 80 chars)

Prinses Beatrixlaan

branchHouseNumber

location: house number (max 5 digits)

23

branchHouseNumberAddition

location: house number addition (max 20 chars)

branchPostalCode

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

2595AK

branchCity

location: city (NEN, max 80 digits)

'S-GRAVENHAGE

rsin

Legal Entities and Partnerships Information Number (9 digit)

808307770

legalTypeCdlegal type code *41

legalTypeDesc

legal type description*

Besloten vennootschap gewone structuur

commercialInd

indicator commercially active: :
J (commercially active) or
N (commercially inactive)

J

headOfficeInd

indicator head office:
H (head office, aka mainbranch) or

N (branch) or

NULL (empty: unknown)

H

allowDmInd

indicator direct marketing via mail allowed:

J (allowed) or
N (not allowed)

N

url

main website (max 255 chars)

www.cendris.nl

legalName

Partnerschip name
(maxLength = 132 chars)
Dutch: Vennootschapsnaam

PostNL Data Solutions B.V.

tradeNames

Array with up to 10 alternative trade names (each tradename consists of max 255 chars).
Note that organizations might have additional tradenames as well.

[ CENDRIS, Customer Information ,Omnidata Tracking & Tracing, PostNL Data Solutions B.V.]

INPUT methods 5, 6 and 7

Input of the methods that provide detailed information:

Attribute

Mandatory / Optional depending of Method and Combination

 

Companydetails

companydetailsextra 

companyauthorization

companyextract

 

Method 5

Method 6

Method 7

Method 8 [ coming soon ]

Comb 1

Comb 2

Comb 1

Comb 2

Comb 1

Comb 2

Comb 1

Comb 2

kvknumber

M

 

M

 

M

 

M

 

branchnumber

M

 

M

 

O

 

O

 

postnlkey

 

M

 

M

 

M

 

M


Example:

{
     "kvknumber": "",
     "branchnumber": "",
     "postnlkey": "1004784700"
}

* 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)
 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.