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

O 

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 companysearch

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

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/4 Method 5 Method 6 Method 7 Attribute Description Example
✓ ✓ ✓   totalPages Number of pages returned 1
✓ ✓ ✓   requestedPage Current result page 1
✓ ✓ ✓   resultCount number of organizations returned 1
✓ ✓ ✓ ✓ companyName organizational name Koninklijke Postnl B.V.
✓ ✓ ✓ ✓ kvkNumber CoC identification number  27124700
(8 digit)
✓ ✓ ✓ ✓ postnlKey PostNL identification number  1004364844
(12 digit)
✓ ✓ ✓ ✓ branchNumber location: number  17527368
(12 digit)
✓ ✓ ✓   branchStreetName location: street name  Prinses Beatrixlaan
(NEN, max 80 chars)
✓ ✓ ✓   branchHouseNumber location: house number  23
(max 5 digits)
✓ ✓ ✓   branchHouseNumberAddition location: house number addition (max 20 chars)  
✓ ✓ ✓   branchPostalCode location: postal code  2595AK
( [1-9][0-9]{3}[a-z]{2} , no spaces)
✓ ✓ ✓   branchCity location: city  'S-GRAVENHAGE
(NEN, max 80 digits)
    ✓   companyPhoneNumber main phone number 9000990
    ✓   companyMobilePhoneNumber main mobile phone number  
  ✓ ✓   mailingStreetName mailing: street name  Prinses Beatrixlaan
(NEN, max 80 chars)
  ✓ ✓   mailingHouseNumber mailing: house number  23
(max 5 digits)
  ✓ ✓   mailingHouseNumberAddition mailing: number addition   
(max 20 chars)
  ✓ ✓   mailingPostalCode mailing: postal code ( [1-9][0-9]{3}[a-z]{2} , no spaces) 2595AK
  ✓ ✓   mailingCity mailing: city (NEN, max 80 digits) 'S-GRAVENHAGE
✓ ✓ ✓ ✓ rsin Legal Entities and Partnerships Information Number (9 digit) 9291477
✓ ✓ ✓ ✓ legalTypeCd legal type (2 digit) * 41
✓ ✓ ✓ ✓ legalTypeDesc legal type description (length) * Besloten vennootschap gewone structuur
  ✓ ✓ ✓ registrationDate date of registration at CoC 1-1-1989
  ✓ ✓   foundingDate founding date 1-1-1989
  ✓ ✓   registrationReasonCd registration reason code ** 31
  ✓ ✓   registrationReasonDesc registration reason description ** Voortzetting
  ✓ ✓ ✓ bankruptInd Bankrupt status:  N
J (bankrupt) or 
N (not bankrupt)
  ✓ ✓ ✓ surceanceInd Surceance status:  N
J (surceance) or 
N (no surceance)
✓ ✓ ✓ ✓ commercialInd indicator commercially active:  J
J (commercially active) or 
N (commercially inactive)
✓ ✓ ✓ ✓ headOfficeInd indicator head office:  H
H (head office, aka mainbranch) or
N (branch) or
NULL (empty: unknown)
✓ ✓ ✓   allowDmInd indicator direct marketing via mail allowed: J
J (allowed) or 
N (not allowed)
✓ ✓ ✓   url website (max 255 chars) www.postnl.nl
✓ ✓ ✓   legalName Partnerschip name  Koninklijke Postnl B.V.
(maxLength = 132 chars) 
Dutch: Vennootschapsnaam
✓ ✓ ✓   tradeNames Array with up to 10 alternative trade names CENDRIS (Koninklijke TNT Post), CENDRIS (Koninklijke TNT Post), …
  ✓ ✓   xCoordinate x Coordinate 82.933.668
  ✓ ✓   yCoordinate y Coordinate 455.008.433
  ✓ ✓   longitude longitude 4.335.907
  ✓ ✓   latitude latitude 52.078.657
  ✓ ✓   cbiCds array with PostNL Company Activity Code (CBI is an extension of the CoC SBI-code, 4 or 5 digit) 5310, 7490, 6832
  ✓ ✓   cbiDescription CBI / SBI Description  
  ✓ ✓   numberOfEmployees amount of employees 44704
  ✓ ✓   numberOfFteEmployees amount of FTE employees 44704
  ✓ ✓   numberOfAGWP amount of workspaces 11176
  ✓ ✓   kvkPerson object, 1st kvk registrant  
    ✓   functionCd kvk registrant function code *** 0
    ✓   functionDesc kvk registrant function description *** Onbekend
    ✓   initials kvk registrant initials J.J.P.
    ✓   prefix kvk registrant prefix  
    ✓   lastname kvk registrant last name Bos
    ✓   gender kvk registrant gender M
    ✓   dmuPersons array, Decision Making Units  8
objects
    ✓   functionCd dmu registrant function code 1
    ✓   functionDesc dmu registrant function description Algemeen directeur
    ✓   initials dmu registrant initials J.J.P.
    ✓   prefix dmu registrant prefix  
    ✓   lastname dmu registrant last name Bos
    ✓   gender dmu registrant gender M
    ✓   functionCd dmu registrant function code 6
    ✓   functionDesc dmu registrant function description IT-manager
    ✓   initials dmu registrant initials M.J.M.
    ✓   prefix dmu registrant prefix  
    ✓   lastname dmu registrant last name Krom
    ✓   gender dmu registrant gender M
    ✓   … … … and more
    ✓ ✓ mhicCompanyName ultimate parent company name PostNL N.V.
    ✓ ✓ mhicPostnlKey ultimate parent postnlKey 1004387646
    ✓ ✓ m1CompanyName parent company name PostNL Holding B.V.
    ✓ ✓ m1PostnlKey parent postnlKey 1004387313
✓ authorizedPersons
✓ apFunction The function of the authorized signatory Procuratiehouder
✓ apType The type of authority from the authorized signatory Beperkt bevoegd
✓ apInitials The initials of the authorized signatory R.D.
✓ apPrefix The prefix of the authorized signatory van der
✓ apLastName The lastname of the authorized signatory Molen
✓ apGender The gender of the authorized signatory  M
✓ authorizedCompanies  
✓ acKvkNumber Kvk number of the authorized company 34278934
✓ acName The name of the authorized company Post NL
✓ acFunction The function of the authorized company Directeur
✓ acStartDate Startdate when the company was authorized 8-6-2008
✓ acPersonFunction The function of the person that is authorized for the authorized company Procuratiehouder
✓ acPersonType The type of authority from the person that is authorized for the authorized company Beperkt bevoegd
✓ acPersonInitials The initials of the person that is authorized for the authorized company R.D.
✓ acPersonPrefix The prefix of the person that is authorized for the authorized company van der
✓ acPersonLastName The prefix of the person that is authorized for the authorized company Molen
✓ acPersonGender The gender of the person that is authorized for the authorized company M


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