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	O	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
fuzzysearch	O	O	O	O	Fuzzy searching for a company by name, kvknumber, streetname and/or cityname	PostNL 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, …
Fuzzysearch	O	Fuzzy searching for a company by name, kvknumber, streetname, postalcode and/or city name	PostNL 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/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
✓	✓	✓	✓	kvkNumber	(8 digit)	27124700
✓	✓	✓	✓	postnlKey	PostNL identification number	1004364844
✓	✓	✓	✓	postnlKey	(12 digit)	1004364844
✓	✓	✓	✓	branchNumber	location: number	17527368
✓	✓	✓	✓	branchNumber	(12 digit)	17527368
✓	✓	✓		branchStreetName	location: street name	Prinses Beatrixlaan
✓	✓	✓		branchStreetName	(NEN, max 80 chars)	Prinses Beatrixlaan
✓	✓	✓		branchHouseNumber	location: house number	23
✓	✓	✓		branchHouseNumber	(max 5 digits)	23
✓	✓	✓		branchHouseNumberAddition	location: house number addition (max 20 chars)
✓	✓	✓		branchPostalCode	location: postal code	2595AK
✓	✓	✓		branchPostalCode	( [1-9][0-9]{3}[a-z]{2} , no spaces)	2595AK
✓	✓	✓		branchCity	location: city	'S-GRAVENHAGE
✓	✓	✓		branchCity	(NEN, max 80 digits)	'S-GRAVENHAGE
		✓		companyPhoneNumber	main phone number	9000990
		✓		companyMobilePhoneNumber	main mobile phone number
	✓	✓		mailingStreetName	mailing: street name	Prinses Beatrixlaan
	✓	✓		mailingStreetName	(NEN, max 80 chars)	Prinses Beatrixlaan
	✓	✓		mailingHouseNumber	mailing: house number	23
	✓	✓		mailingHouseNumber	(max 5 digits)	23
	✓	✓		mailingHouseNumberAddition	mailing: number addition
	✓	✓		mailingHouseNumberAddition	(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)
✓	✓			active	true (still registered at KVK) or false (not subscribed at KVK anymore)	true
✓	✓	✓		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
		✓		dmuPersons	objects	8
		✓		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.