API documentation
Intro
Our JSON REST-API is easy to integrate and contains a logical structure of the methods.
An Application Programming Interface (API) is a computing interface which defines interactions between multiple software intermediaries.
It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, without developers having to know how the other software exactly works.
Representational State Transfer (for short REST) is a software architectural style that defines a set of constraints to be used for creating Web services. SOAP has been replaced with URLs for addressing and the HTTP methods (GET, POST, DELETE and PUT) for calling the service. Any programming language currently applicable to dynamically handle HTTP requests, in example with a cURL-library, is suitable for using REST.What's an API?
What's an REST API?
Requests
API-token
To make requests to the API-endpoints, you will need an API-token. For development purposes, you can use a development-token. With this you can do test-requests, which will return a number of fixed results, and will not use your production-limit. Never use a development-token in a production environment.
You may create multiple production token, this can be useful if you would like to use the same subscription on different websites. You can make distinction between multiple websites or apps and the total number of requests.
You may create API-tokens for both development- and production requests on your dashboard.
Authorization
You authorize the request by using a Bearer
-token (your API-key) in the Authorization
-header.
200
Success response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/me
{ "Customer": { "name": "My Company Ltd.", "planName": "Small", "dateCreated": "2020-02-02 02:02:02", "username": [], "planDescription": [] }, "ApiAccessToken": { "isDevelopment": "boolean", "description": "Development-token", "dateCreated": "2020-02-02 02:02:02", "dateExpiration": "2021-02-02 02:02:02" } }
HTTP/1.1 200 OK
Pagination
Some methods return more than one result and are paginated over multiple pages.
These requests will always include a Pagination
-object.
The maximum number of results per request depend on the purchased plan.
Response
-
FieldTypeDescription
Warning: Attempt to read property "components" on array in /builds/KBO-Data/KBO-Homepage/cache/volt/v2.76961bfc.php on line 223
Warning: Attempt to read property "schemas" on null in /builds/KBO-Data/KBO-Homepage/cache/volt/v2.76961bfc.php on line 223
Warning: Trying to access array offset on null in /builds/KBO-Data/KBO-Homepage/cache/volt/v2.76961bfc.php on line 223
Warning: Attempt to read property "properties" on null in /builds/KBO-Data/KBO-Homepage/cache/volt/v2.76961bfc.php on line 223
Warning: foreach() argument must be of type array|object, null given in /builds/KBO-Data/KBO-Homepage/cache/volt/v2.76961bfc.php on line 223
Headers
A number of API-related headers are included in the response headers of the request. They are useful to determine how many requests you have left for the current period and what type of key you're currently using.
The headers below are displayed in a request. Some values may depend on the type of key used (development- or production key). This details serves as an aid, and can also be seen visually on your dashboard.Example (headers)
Warning: Attempt to read property "components" on array in /builds/KBO-Data/KBO-Homepage/cache/volt/v2.76961bfc.php on line 256
Warning: Attempt to read property "headers" on null in /builds/KBO-Data/KBO-Homepage/cache/volt/v2.76961bfc.php on line 256
Warning: foreach() argument must be of type array|object, null given in /builds/KBO-Data/KBO-Homepage/cache/volt/v2.76961bfc.php on line 256
Description
Endpoints
All end-points must begin with one of the following protocol and domain name, depending on the implementation and key-type:
-
Protocol and domain nameTypeDescription
Warning: Attempt to read property "servers" on array in /builds/KBO-Data/KBO-Homepage/cache/volt/v2.76961bfc.php on line 310
Warning: foreach() argument must be of type array|object, null given in /builds/KBO-Data/KBO-Homepage/cache/volt/v2.76961bfc.php on line 310
Arguments prefixed with a (asterisk) are required, without these arguments the request will fail. Other arguments are optional.
To not publish any (old or incorrect) enterprise data on our website, we use fictional data in our examples.
Before you start with the implementation of our API, it is useful to have a clear picture of the data structure, below you fill find an image of the hierarchy of data and how they relate to each other.
As you can see, a denomination
, address
and activity
can be related to both an enterprise or an establishment. Unfortunately, there are not any fixed rules for this structure. So in example it will be possible that an enterprise does not have any registration addresses, however the establishment linked to the enterprise does. Vice versa is also possible. Therefore, it is always a good idea to check the establishments of the enterprises if you are looking for any specific data.
Endpoints overview
Enterprises
-
Retrieve enterprise details.
/enterprise/{enterpriseNumber} -
Retrieve all enterprise activities.
/enterprise/{enterpriseNumber}/activities -
Retrieve a specific enterprise address by type.
/enterprise/{enterpriseNumber}/address -
Retrieve contact information of the enterprise.
/enterprise/{enterpriseNumber}/contact -
Retrieve all enterprise denominations.
/enterprise/{enterpriseNumber}/denominations -
Retrieve a specific enterprise denomination.
/enterprise/{enterpriseNumber}/denomination/{language}/{type} -
Retrieve all enterprise establishments.
/enterprise/{enterpriseNumber}/establishments -
Retrieve short financial information of the enterprise.
/enterprise/{enterpriseNumber}/financial -
Retrieve NSSO (RSZ, LSS, ONSS) details of the enterprise.
/enterprise/{enterpriseNumber}/nsso -
Retrieve all official functions of the enterprise.
/enterprise/{enterpriseNumber}/roles Establishments
-
Retrieve establishment details.
/establishment/{establishmentNumber} -
Retrieve all establishment activities.
/establishment/{establishmentNumber}/activities -
Retrieve the address of the establishment address.
/establishment/{establishmentNumber}/address -
Retrieve contact information of the establishment.
/establishment/{establishmentNumber}/contact -
Retrieve all establishment denominations.
/establishment/{establishmentNumber}/denominations -
Retrieve a specific establishment denomination.
/establishment/{establishmentNumber}/denomination/{language} Denominations
-
Autocomplete company names (denominations)
/denominations Addresses
-
Search for multiple addresses.
/addresses Nace
-
Search for nace code
/naces -
Get NACE by version and code
/nace/{naceVersion}/{naceCode} Roles
-
Search for a role code (function title)
/roles -
Get a specific function title by code
/role/{roleCode} Juridical
-
Search for a juridical form
/juridical-forms -
Search for a juridical situation
/juridical-situations VAT
-
Verify VAT-number or enterprise number for internation transactions within the EU
/vat/{vatNumber} Customer
-
Get authorized customer information
/me
/enterprise/{enterpriseNumber}
Arguments and parameters
-
FieldTypeDescription
-
enterpriseNumber
integer
Number of the enterpriseExample:0417497106
Response
Successful response | Enterprise is found.
-
FieldTypeDescription
-
Enterprise
object
-
enterpriseNumber
string
The enterprise number as digits only.Example:0417497106
-
enterpriseNumberFormatted
string
The enterprise number as formatted human readable string.Example:0417.497.106
-
vatNumber
string
VAT numberExample:BE0417497106
-
status
integer
Example:1
-
active
boolean
Whether the registration status of the establishment is active or inactiveExample:1
-
type
string
The company type,natural
for natural person orentity
for legal entity.Possible values:natural
entity
Example:entity
-
typeDescription
object
-
nl
string
Dutch descriptionExample:Rechtspersoon
-
en
string
English descriptionExample:Legal entity
-
fr
string
French descriptionExample:Personne morale
-
de
string
German descriptionExample:Juristische Person
-
JuridicalForm
object
-
juridicalFormCode
string
Juridical Form codeExample:030
-
description
object
-
nl
string
Dutch description of the juridical formExample:Buitenlandse entiteit
-
fr
string
French description of the juridical formExample:Entité étrangère
-
de
string
German description of the juridical formExample:Ausländische Einheit
-
JuridicalSituation
object
-
juridicalSituationCode
string
Juridical Situation codeExample:000
-
description
object
-
nl
string
Dutch description of the juridical situationExample:Normale toestand
-
fr
string
French description of the juridical situationExample:Situation normale
-
de
string
German description of the juridical situationExample:Gewöhnlicher Zustand
-
dateStart
string
Example:2020-01-01
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/enterprise/{enterpriseNumber}
{ "Enterprise": { "enterpriseNumber": "0417497106", "enterpriseNumberFormatted": "0417.497.106", "vatNumber": "BE0417497106", "status": "1", "active": "1", "type": "entity", "typeDescription": { "nl": "Rechtspersoon", "en": "Legal entity", "fr": "Personne morale", "de": "Juristische Person" }, "JuridicalForm": { "juridicalFormCode": "030", "description": { "nl": "Buitenlandse entiteit", "fr": "Entit\u00e9 \u00e9trang\u00e8re", "de": "Ausl\u00e4ndische Einheit" } }, "JuridicalSituation": { "juridicalSituationCode": "000", "description": { "nl": "Normale toestand", "fr": "Situation normale", "de": "Gew\u00f6hnlicher Zustand" } }, "dateStart": "2020-01-01" } }
HTTP/1.1 200 OK
404
Enterprise not found
{ "exception": "RequestException", "error": "The `enterprise` item specified could not be found", "code": "-2" }
/enterprise/{enterpriseNumber}/activities
Arguments and parameters
-
FieldTypeDescription
-
enterpriseNumber
integer
Number of the enterpriseExample:0417497106
Response
Successful response | All activities from the enterprise.
-
FieldTypeDescription
-
[]
array
-
Activity
object
-
activityGroup
string
Possible values:BTW001
EDR001
OLK001
POR001
PPO001
RSZ001
SCO001
Example:BTW001
-
activityGroupDescription
object
-
nl
string
Dutch descriptionExample:BTW-activiteiten
-
fr
string
French descriptionExample:Activités TVA
-
en
string
English descriptionExample:VAT activities
-
de
string
German descriptionExample:MwSt.-Aktivitäten
-
classification
string
Possible values:ANCI
MAIN
SECO
Example:MAIN
-
classificationDescription
object
-
nl
string
Dutch descriptionExample:Hoofdactiviteit
-
fr
string
French descriptionExample:Activité principale
-
en
string
English descriptionExample:Main activity
-
de
string
German descriptionExample:Hauptaktivität
-
Nace
object
-
naceVersion
integer
Example:2008
-
naceCode
string
Example:474
-
description
object
-
nl
string
Dutch descriptionExample:Detailhandel in ICT-apparatuur in gespecialiseerde winkels
-
fr
string
French descriptionExample:Commerce de détail d'équipements de l'information et de la communication en magasin spécialisé
-
de
string
German descriptionExample:Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)
-
en
string
English descriptionExample:Retail sale of information and communication equipment in specialised stores
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/enterprise/{enterpriseNumber}/activities
[ { "Activity": { "activityGroup": "BTW001", "activityGroupDescription": { "nl": "BTW-activiteiten", "fr": "Activit\u00e9s TVA", "en": "VAT activities", "de": "MwSt.-Aktivit\u00e4ten" }, "classification": "MAIN", "classificationDescription": { "nl": "Hoofdactiviteit", "fr": "Activit\u00e9 principale", "en": "Main activity", "de": "Hauptaktivit\u00e4t" }, "Nace": { "naceVersion": "2008", "naceCode": "474", "description": { "nl": "Detailhandel in ICT-apparatuur in gespecialiseerde winkels", "fr": "Commerce de d\u00e9tail d'\u00e9quipements de l'information et de la communication en magasin sp\u00e9cialis\u00e9", "de": "Einzelhandel mit Ger\u00e4ten der Informations- und Kommunikationstechnik (in Verkaufsr\u00e4umen)", "en": "Retail sale of information and communication equipment in specialised stores" } } } } ]
HTTP/1.1 200 OK
404
Enterprise not found
{ "exception": "RequestException", "error": "The `enterprise` item specified could not be found", "code": "-2" }
/enterprise/{enterpriseNumber}/address
Arguments and parameters
-
FieldTypeDescription
-
enterpriseNumber
integer
Number of the enterpriseExample:0417497106
Response
Successful response | The specific address has been found.
-
FieldTypeDescription
-
Address
object
-
entityNumber
string
Example:0417497106
-
entityNumberFormatted
string
Example:0417.497.106
-
entityType
string
Possible values:enterprise
establishment
Example:enterprise
-
type
string
-Possible values:branch
establishment
active-establishment
legal-entity
Example:branch
-
typeDescription
object
-
street
object
Street of the registration -
nl
string
Dutch street translation of the registrationExample:Kerkstraat
-
fr
string
French street translation of the registrationExample:Rue de l'Église
-
addressNumber
string
Address street number of the registrationExample:1
-
addressAdditional
string
Additional address or street suffixExample:Unit 12, Floor 5
-
postOfficeBox
string
The post office box of the address, if applicableExample:Box 5
-
zipcode
string
Zipcode of the registrationExample:2000
-
city
object
City of the registration -
nl
string
Dutch city translation of the registrationExample:Brussel
-
fr
string
French city translation of the registrationExample:Bruxelles
-
countryCode
string
The ISO 3166-1 alpha-2 country code of the address.Example:fr
-
country
object
Translated name of the country code. -
nl
string
Dutch translation of the countryExample:Frankrijk
-
fr
string
French translation of the countryExample:France
-
en
string
English translation of the countryExample:France
-
de
string
German translation of the country -
dateRevoke
string
-
dateStart
string
Example:2020-01-01
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/enterprise/{enterpriseNumber}/address
{ "Address": { "entityNumber": "0417497106", "entityNumberFormatted": "0417.497.106", "entityType": "enterprise", "type": "branch", "typeDescription": { "nl": "Maatschappelijke zetel", "en": "Head office", "fr": "Si\u00e8ge social", "de": "Sitzes Adresse" }, "street": { "nl": "Kerkstraat", "fr": "Rue de l'\u00c9glise" }, "addressNumber": "1", "addressAdditional": "Unit 12, Floor 5", "postOfficeBox": "Box 5", "zipcode": "2000", "city": { "nl": "Brussel", "fr": "Bruxelles" }, "countryCode": "fr", "country": { "nl": "Frankrijk", "fr": "France", "en": "France", "de": "string" }, "dateRevoke": "string", "dateStart": "2020-01-01" } }
HTTP/1.1 200 OK
404
Enterprise not found
{ "exception": "RequestException", "error": "The `enterprise` item specified could not be found", "code": "-2" }
/enterprise/{enterpriseNumber}/contact
Large plan
Arguments and parameters
-
FieldTypeDescription
-
enterpriseNumber
integer
Number of the enterpriseExample:0417497106
Response
Succesful response | All contact information of the enterprise.
-
FieldTypeDescription
-
[]
array
-
Contact
object
-
enterpriseNumber
string
Example:0417497106
-
enterpriseNumberFormatted
string
Example:0417.497.106
-
typeCode
string
The type of contact informationPossible values:phone
email
website
Example:phone
-
value
string
The value of the contact type, could be a phone number, email adress or website, depending on thetypeCode
.Example:0032123456789
Example
200
Succesful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/enterprise/{enterpriseNumber}/contact
[ { "Contact": { "enterpriseNumber": "0417497106", "enterpriseNumberFormatted": "0417.497.106", "typeCode": "phone", "value": "0032123456789" } } ]
HTTP/1.1 200 OK
404
Enterprise not found
{ "exception": "RequestException", "error": "The `enterprise` item specified could not be found", "code": "-2" }
402
Larger plan required
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "code": "-31" }
/enterprise/{enterpriseNumber}/denominations
Arguments and parameters
-
FieldTypeDescription
-
enterpriseNumber
integer
Number of the enterpriseExample:0417497106
Response
Successful response | All denominations from the enterprise.
-
FieldTypeDescription
-
[]
array
-
Denomination
object
-
entityNumber
string
Example:0417497106
-
entityNumberFormatted
string
Example:0417.497.106
-
entityType
string
Possible values:enterprise
establishment
Example:enterprise
-
language
string
Possible values:unknown
nl
en
fr
de
Example:nl
-
value
string
The denomination nameExample:FaimMedia B.V.
-
type
string
The denomination typePossible values:social
abbreviation
commercial
Example:social
-
typeDescription
object
-
nl
string
Dutch translation of the type descriptionExample:Maatschappelijke naam
-
en
string
English translation of the type descriptionExample:Primary name
-
fr
string
French translation of the type descriptionExample:Dénomination sociale
-
de
string
German translation of the type descriptionExample:Primärname
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/enterprise/{enterpriseNumber}/denominations
[ { "Denomination": { "entityNumber": "0417497106", "entityNumberFormatted": "0417.497.106", "entityType": "enterprise", "language": "nl", "value": "FaimMedia B.V.", "type": "social", "typeDescription": { "nl": "Maatschappelijke naam", "en": "Primary name", "fr": "D\u00e9nomination sociale", "de": "Prim\u00e4rname" } } } ]
HTTP/1.1 200 OK
404
Enterprise not found
{ "exception": "RequestException", "error": "The `enterprise` item specified could not be found", "code": "-2" }
/enterprise/{enterpriseNumber}/denomination/{language}/{type}
Arguments and parameters
-
FieldTypeDescription
-
enterpriseNumber
integer
Number of the enterpriseExample:0417497106
-
language
string
The language code of the denomination. Some denominations may not have the language specified, use theunknown
value in this case.Possible values:unknown
nl
en
fr
de
Example:nl
-
type
string
The type of the denomination, see the response parameter for the type explaination.Possible values:social
abbreviation
commercial
Example:commercial
Response
Successful response | The denomination has been found.
-
FieldTypeDescription
-
Denomination
object
-
entityNumber
string
Example:0417497106
-
entityNumberFormatted
string
Example:0417.497.106
-
entityType
string
Possible values:enterprise
establishment
Example:enterprise
-
language
string
Possible values:unknown
nl
en
fr
de
Example:nl
-
value
string
The denomination nameExample:FaimMedia B.V.
-
type
string
The denomination typePossible values:social
abbreviation
commercial
Example:social
-
typeDescription
object
-
nl
string
Dutch translation of the type descriptionExample:Maatschappelijke naam
-
en
string
English translation of the type descriptionExample:Primary name
-
fr
string
French translation of the type descriptionExample:Dénomination sociale
-
de
string
German translation of the type descriptionExample:Primärname
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/enterprise/{enterpriseNumber}/denomination/{language}/{type}
{ "Denomination": { "entityNumber": "0417497106", "entityNumberFormatted": "0417.497.106", "entityType": "enterprise", "language": "nl", "value": "FaimMedia B.V.", "type": "social", "typeDescription": { "nl": "Maatschappelijke naam", "en": "Primary name", "fr": "D\u00e9nomination sociale", "de": "Prim\u00e4rname" } } }
HTTP/1.1 200 OK
404
Enterprise not found
{ "exception": "RequestException", "error": "The `enterprise` item specified could not be found", "code": "-2" }
/enterprise/{enterpriseNumber}/establishments
Arguments and parameters
-
FieldTypeDescription
-
enterpriseNumber
integer
Number of the enterpriseExample:0417497106
-
active
Large planstring
Choose if you also want to retrieve inactive establishments. The default is only active.Possible values:active
inactive
all
Example:active
Response
Successful response | All establishments from the enterprise.
-
FieldTypeDescription
-
[]
array
-
Establishment
object
-
enterpriseNumber
string
Example:0417497106
-
enterpriseNumberFormatted
string
Example:0417.497.106
-
establishmentNumber
string
The establishment number without punctuation marks.Example:2102217157
-
establishmentNumberFormatted
string
The estblishment number seperated by punctuation marks.Example:2102.217.157
-
active
boolean
Whether the registration status of the establishment is active or inactiveExample:1
-
dateStart
string
Example:2020-01-01
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/enterprise/{enterpriseNumber}/establishments
[ { "Establishment": { "enterpriseNumber": "0417497106", "enterpriseNumberFormatted": "0417.497.106", "establishmentNumber": "2102217157", "establishmentNumberFormatted": "2102.217.157", "active": "1", "dateStart": "2020-01-01" } } ]
HTTP/1.1 200 OK
402
Larger plan required for this parameter
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "parameter": "active", "code": "-31" }
404
Enterprise not found
{ "exception": "RequestException", "error": "The `enterprise` item specified could not be found", "code": "-2" }
/enterprise/{enterpriseNumber}/financial
Large plan
- Paid-in capital
- Annual assembly
- Financial start and end year
Please note:
- sole-proprietorships do not have published financial years, so this information will not be available
- not all enterprises are required to publicly share this information, so it will not always be available.
Arguments and parameters
-
FieldTypeDescription
-
enterpriseNumber
integer
Number of the enterpriseExample:0417497106
Response
Successful response | Financial information from the enterprise.
-
FieldTypeDescription
-
EnterpriseFinancial
object
-
enterpriseNumber
string
Example:0417497106
-
enterpriseNumberFormatted
string
Example:0417.497.106
-
capitalValue
integer
Placed capital according to statutesExample:100000
-
capitalValuta
string
The valuta of the placed capital, whileEUR
is the most common, this value can be anyISO-4217
code. It's also common for companies founded before the introduction of the Euro to have historical valuta, in example:BEF
,FRF
andNLG
. Most foreign companies have foreign valuta present.
Please visit wikipedia for an up-to-date ISO-4217 list of:
- Active currency codes
- Historic currency codesExample:EUR
-
annualAssembly
integer
The month of the annual assembly, range is 1 to 12.Example:6
-
annualAssemblyMonth
string
Textual presentation in English of the annual assembly.Example:June
-
fiscalEnd
string
The end date of a regular fiscal year. The year is not present here and will be formatted as0000
.Example:0000-12-21
-
fiscalSpecialStart
string
The start date of an exceptional fiscal year.Example:2021-03-01
-
fiscalSpecialEnd
string
The end date of an exceptional fiscal year.Example:2022-02-28
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/enterprise/{enterpriseNumber}/financial
{ "EnterpriseFinancial": { "enterpriseNumber": "0417497106", "enterpriseNumberFormatted": "0417.497.106", "capitalValue": "100000", "capitalValuta": "EUR", "annualAssembly": "6", "annualAssemblyMonth": "June", "fiscalEnd": "0000-12-21", "fiscalSpecialStart": "2021-03-01", "fiscalSpecialEnd": "2022-02-28" } }
HTTP/1.1 200 OK
/enterprise/{enterpriseNumber}/nsso
New!
Medium plan
Known differently per language:
- NL: Werkgeversrepertorium
- FR: Répertoire des employeurs
- DE: Verzeichnis der Arbeitgeber
- NL: RSZ-nummer
- FR: N° ONSS
- DE: LSS-Nummer
- EN: NSSO number
Arguments and parameters
-
FieldTypeDescription
-
enterpriseNumber
integer
Number of the enterpriseExample:0417497106
Response
Successful response | NSSO information from the enterprise.
-
FieldTypeDescription
-
EnterpriseNsso
object
-
enterpriseNumber
string
Example:0417497106
-
enterpriseNumberFormatted
string
Example:0417.497.106
-
nssoNumber
integer
The NSSO-number (or RSZ-number, LSS-number, ONSS-number) of the companyExample:154857201
-
nssoNumberFormatted
string
The formatted NSSO-number with a dash of the companyExample:1548572-01
-
nssoNumberProvisional
integer
A temporary NSSO-number that is used when no final NSSO-number has been issued.Example:1234567890
-
sectors
array
List of sectors -
code
string
Possible values:private
publicFedReg
publicPla
Example:private
-
codeDescription
object
-
nl
string
Example:Privé
-
fr
string
Example:Privé
-
de
string
Example:Privat
-
en
string
Example:Private
-
dateStart
string
Start dateExample:2024-02-01
-
periods
array
Overview of employee periods -
dateStart
string
Start date of the employee periodExample:2024-03-02
-
importanceCodes
array
-
dateStart
string
Start date of the employee importance codeExample:2024-04-02
-
code
object
Code identifierPossible values:1
2
3
4
5
6
7
8
9
Example:1
-
codeDescription
object
Description of the code identifier -
nl
string
Dutch description of the code identifierExample:1 tot 4 werknemers
-
fr
string
French description of the code identifierExample:1 à 4 travailleurs
-
de
string
German description of the code identifierExample:1 bis 4 Arbeitnehmer
-
en
string
English description of the code identifierExample:1 until 4 employees
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/enterprise/{enterpriseNumber}/nsso
{ "EnterpriseNsso": { "enterpriseNumber": "0417497106", "enterpriseNumberFormatted": "0417.497.106", "nssoNumber": "154857201", "nssoNumberFormatted": "1548572-01", "nssoNumberProvisional": "1234567890", "sectors": [ { "code": "private" }, { "codeDescription": { "nl": "Priv\u00e9", "fr": "Priv\u00e9", "de": "Privat", "en": "Private" } }, { "dateStart": "2024-02-01" } ], "periods": [ { "dateStart": "2024-03-02" }, { "importanceCodes": [ { "dateStart": "2024-04-02" }, { "code": [] }, { "codeDescription": { "nl": "1 tot 4 werknemers", "fr": "1 \u00e0 4 travailleurs", "de": "1 bis 4 Arbeitnehmer", "en": "1 until 4 employees" } } ] } ] } }
HTTP/1.1 200 OK
402
Larger plan required
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "code": "-31" }
404
The provided enterprise could not be found, or does not have any NSSO information available.
503
Service unavailable, please try again later.
/enterprise/{enterpriseNumber}/roles
Large plan
Please note:
- that sole proprietorships do not have any board members, except for the natural person that legally owns the company. This will be the only present function.
- almost all foreign entities do not have any board members registered.
Arguments and parameters
-
FieldTypeDescription
-
enterpriseNumber
integer
Number of the enterpriseExample:0417497106
Response
Successful response | All functions from the enterprise.
-
FieldTypeDescription
-
[]
array
-
EnterpriseRole
object
-
enterpriseNumber
string
Example:0417497106
-
enterpriseNumberFormatted
string
Example:0417.497.106
-
nameFirst
string
First name of the board memberExample:Frans
-
nameLast
string
Last name of the board memberExample:Vanderbeek
-
parentEnterpriseNumber
string
The enterprise number of which the role is inherited from. If thenameLast
andnameFirst
fields are both empty, the legal entity of the parent enterprise fulfills this role.Example:0417497105
-
parentEnterpriseNumberFormatted
string
The enterprise number formatted.Example:0417.497.106
-
dateInOffice
string
The date the person was registeredExample:2021-01-01
-
Role
object
-
roleCode
integer
Code of the function title. Please be aware that this code may change at anytime, so it's advisable not to put to much reference to this value. Or to check periodicly for any changes.Example:5
-
title
object
-
nl
string
Function title in DutchExample:Zaakvoerder
-
en
string
Function title in EnglishExample:Manager
-
fr
string
Function title in FrenchExample:Gérant
-
de
string
Function title in GermanExample:Geschäftsführer
-
note
object
Possible note regarding function title -
nl
string
Possible note regarding function title in DutchExample:Overeenkomstig het Wetboek van Vennootschappen en Verenigingen moet de term "Zaakvoerder" vanaf 1 januari 2020 gelezen worden als "Bestuurder"
-
en
string
Possible note regarding the function title in EnglishExample:Pursuant to the Code of Companies and Associations, the term "Manager" must, since January 1, 2020, be read as "Board member".
-
fr
string
Possible note regarding function title in FrenchExample:En application du Code des sociétés et des associations, le terme "Gérant" doit, depuis le 1er janvier 2020, être lu comme étant "Administrateur".
-
de
string
Possible note regarding function title in GermanExample:Gemäß dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff "Geschäftsführer" seit dem 1. Januar 2020 als "Verwalter" zu lesen.
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/enterprise/{enterpriseNumber}/roles
[ { "EnterpriseRole": { "enterpriseNumber": "0417497106", "enterpriseNumberFormatted": "0417.497.106", "nameFirst": "Frans", "nameLast": "Vanderbeek", "parentEnterpriseNumber": "0417497105", "parentEnterpriseNumberFormatted": "0417.497.106", "dateInOffice": "2021-01-01", "Role": { "roleCode": "5", "title": { "nl": "Zaakvoerder", "en": "Manager", "fr": "G\u00e9rant", "de": "Gesch\u00e4ftsf\u00fchrer" }, "note": { "nl": "Overeenkomstig het Wetboek van Vennootschappen en Verenigingen moet de term \"Zaakvoerder\" vanaf 1 januari 2020 gelezen worden als \"Bestuurder\"\n", "en": "Pursuant to the Code of Companies and Associations, the term \"Manager\" must, since January 1, 2020, be read as \"Board member\".\n", "fr": "En application du Code des soci\u00e9t\u00e9s et des associations, le terme \"G\u00e9rant\" doit, depuis le 1er janvier 2020, \u00eatre lu comme \u00e9tant \"Administrateur\".\n", "de": "Gem\u00e4\u00df dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff \"Gesch\u00e4ftsf\u00fchrer\" seit dem 1. Januar 2020 als \"Verwalter\" zu lesen.\n" } } } } ]
HTTP/1.1 200 OK
404
Enterprise not found
{ "exception": "RequestException", "error": "The `enterprise` item specified could not be found", "code": "-2" }
402
Larger plan required
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "code": "-31" }
/establishment/{establishmentNumber}
Arguments and parameters
-
FieldTypeDescription
-
establishmentNumber
integer
Number of the establishmentExample:2147197839
Response
Successful response | The establishment has been found.
-
FieldTypeDescription
-
Establishment
object
-
enterpriseNumber
string
Example:0417497106
-
enterpriseNumberFormatted
string
Example:0417.497.106
-
establishmentNumber
string
The establishment number without punctuation marks.Example:2102217157
-
establishmentNumberFormatted
string
The estblishment number seperated by punctuation marks.Example:2102.217.157
-
active
boolean
Whether the registration status of the establishment is active or inactiveExample:1
-
dateStart
string
Example:2020-01-01
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/establishment/{establishmentNumber}
{ "Establishment": { "enterpriseNumber": "0417497106", "enterpriseNumberFormatted": "0417.497.106", "establishmentNumber": "2102217157", "establishmentNumberFormatted": "2102.217.157", "active": "1", "dateStart": "2020-01-01" } }
HTTP/1.1 200 OK
404
Establishment not found
{ "exception": "RequestException", "error": "The `establishment` item specified could not be found", "code": "-2" }
/establishment/{establishmentNumber}/activities
Arguments and parameters
-
FieldTypeDescription
-
establishmentNumber
integer
Number of the establishmentExample:2147197839
Response
Successful response | All activities from the establishment.
-
FieldTypeDescription
-
[]
array
-
Activity
object
-
activityGroup
string
Possible values:BTW001
EDR001
OLK001
POR001
PPO001
RSZ001
SCO001
Example:BTW001
-
activityGroupDescription
object
-
nl
string
Dutch descriptionExample:BTW-activiteiten
-
fr
string
French descriptionExample:Activités TVA
-
en
string
English descriptionExample:VAT activities
-
de
string
German descriptionExample:MwSt.-Aktivitäten
-
classification
string
Possible values:ANCI
MAIN
SECO
Example:MAIN
-
classificationDescription
object
-
nl
string
Dutch descriptionExample:Hoofdactiviteit
-
fr
string
French descriptionExample:Activité principale
-
en
string
English descriptionExample:Main activity
-
de
string
German descriptionExample:Hauptaktivität
-
Nace
object
-
naceVersion
integer
Example:2008
-
naceCode
string
Example:474
-
description
object
-
nl
string
Dutch descriptionExample:Detailhandel in ICT-apparatuur in gespecialiseerde winkels
-
fr
string
French descriptionExample:Commerce de détail d'équipements de l'information et de la communication en magasin spécialisé
-
de
string
German descriptionExample:Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)
-
en
string
English descriptionExample:Retail sale of information and communication equipment in specialised stores
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/establishment/{establishmentNumber}/activities
[ { "Activity": { "activityGroup": "BTW001", "activityGroupDescription": { "nl": "BTW-activiteiten", "fr": "Activit\u00e9s TVA", "en": "VAT activities", "de": "MwSt.-Aktivit\u00e4ten" }, "classification": "MAIN", "classificationDescription": { "nl": "Hoofdactiviteit", "fr": "Activit\u00e9 principale", "en": "Main activity", "de": "Hauptaktivit\u00e4t" }, "Nace": { "naceVersion": "2008", "naceCode": "474", "description": { "nl": "Detailhandel in ICT-apparatuur in gespecialiseerde winkels", "fr": "Commerce de d\u00e9tail d'\u00e9quipements de l'information et de la communication en magasin sp\u00e9cialis\u00e9", "de": "Einzelhandel mit Ger\u00e4ten der Informations- und Kommunikationstechnik (in Verkaufsr\u00e4umen)", "en": "Retail sale of information and communication equipment in specialised stores" } } } } ]
HTTP/1.1 200 OK
404
Establishment not found
{ "exception": "RequestException", "error": "The `establishment` item specified could not be found", "code": "-2" }
/establishment/{establishmentNumber}/address
Arguments and parameters
-
FieldTypeDescription
-
establishmentNumber
integer
Number of the establishmentExample:2147197839
Response
Successful response | The specific address has been found.
-
FieldTypeDescription
-
Address
object
-
entityNumber
string
Example:0417497106
-
entityNumberFormatted
string
Example:0417.497.106
-
entityType
string
Possible values:enterprise
establishment
Example:enterprise
-
type
string
-Possible values:branch
establishment
active-establishment
legal-entity
Example:branch
-
typeDescription
object
-
street
object
Street of the registration -
nl
string
Dutch street translation of the registrationExample:Kerkstraat
-
fr
string
French street translation of the registrationExample:Rue de l'Église
-
addressNumber
string
Address street number of the registrationExample:1
-
addressAdditional
string
Additional address or street suffixExample:Unit 12, Floor 5
-
postOfficeBox
string
The post office box of the address, if applicableExample:Box 5
-
zipcode
string
Zipcode of the registrationExample:2000
-
city
object
City of the registration -
nl
string
Dutch city translation of the registrationExample:Brussel
-
fr
string
French city translation of the registrationExample:Bruxelles
-
countryCode
string
The ISO 3166-1 alpha-2 country code of the address.Example:fr
-
country
object
Translated name of the country code. -
nl
string
Dutch translation of the countryExample:Frankrijk
-
fr
string
French translation of the countryExample:France
-
en
string
English translation of the countryExample:France
-
de
string
German translation of the country -
dateRevoke
string
-
dateStart
string
Example:2020-01-01
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/establishment/{establishmentNumber}/address
{ "Address": { "entityNumber": "0417497106", "entityNumberFormatted": "0417.497.106", "entityType": "enterprise", "type": "branch", "typeDescription": { "nl": "Maatschappelijke zetel", "en": "Head office", "fr": "Si\u00e8ge social", "de": "Sitzes Adresse" }, "street": { "nl": "Kerkstraat", "fr": "Rue de l'\u00c9glise" }, "addressNumber": "1", "addressAdditional": "Unit 12, Floor 5", "postOfficeBox": "Box 5", "zipcode": "2000", "city": { "nl": "Brussel", "fr": "Bruxelles" }, "countryCode": "fr", "country": { "nl": "Frankrijk", "fr": "France", "en": "France", "de": "string" }, "dateRevoke": "string", "dateStart": "2020-01-01" } }
HTTP/1.1 200 OK
404
Establishment not found
{ "exception": "RequestException", "error": "The `establishment` item specified could not be found", "code": "-2" }
/establishment/{establishmentNumber}/contact
Large plan
Arguments and parameters
-
FieldTypeDescription
-
establishmentNumber
integer
Number of the establishmentExample:2147197839
Response
Succesful response | All contact information of the establishment.
-
FieldTypeDescription
-
[]
array
-
Contact
object
-
enterpriseNumber
string
Example:0417497106
-
enterpriseNumberFormatted
string
Example:0417.497.106
-
typeCode
string
The type of contact informationPossible values:phone
email
website
Example:phone
-
value
string
The value of the contact type, could be a phone number, email adress or website, depending on thetypeCode
.Example:0032123456789
Example
200
Succesful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/establishment/{establishmentNumber}/contact
[ { "Contact": { "enterpriseNumber": "0417497106", "enterpriseNumberFormatted": "0417.497.106", "typeCode": "phone", "value": "0032123456789" } } ]
HTTP/1.1 200 OK
404
Establishment not found
{ "exception": "RequestException", "error": "The `establishment` item specified could not be found", "code": "-2" }
402
Larger plan required
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "code": "-31" }
/establishment/{establishmentNumber}/denominations
Arguments and parameters
-
FieldTypeDescription
-
establishmentNumber
integer
Number of the establishmentExample:2147197839
Response
Successful response | All denominations from the establishment.
-
FieldTypeDescription
-
[]
array
-
Denomination
object
-
entityNumber
string
Example:0417497106
-
entityNumberFormatted
string
Example:0417.497.106
-
entityType
string
Possible values:enterprise
establishment
Example:enterprise
-
language
string
Possible values:unknown
nl
en
fr
de
Example:nl
-
value
string
The denomination nameExample:FaimMedia B.V.
-
type
string
The denomination typePossible values:social
abbreviation
commercial
Example:social
-
typeDescription
object
-
nl
string
Dutch translation of the type descriptionExample:Maatschappelijke naam
-
en
string
English translation of the type descriptionExample:Primary name
-
fr
string
French translation of the type descriptionExample:Dénomination sociale
-
de
string
German translation of the type descriptionExample:Primärname
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/establishment/{establishmentNumber}/denominations
[ { "Denomination": { "entityNumber": "0417497106", "entityNumberFormatted": "0417.497.106", "entityType": "enterprise", "language": "nl", "value": "FaimMedia B.V.", "type": "social", "typeDescription": { "nl": "Maatschappelijke naam", "en": "Primary name", "fr": "D\u00e9nomination sociale", "de": "Prim\u00e4rname" } } } ]
HTTP/1.1 200 OK
404
Establishment not found
{ "exception": "RequestException", "error": "The `establishment` item specified could not be found", "code": "-2" }
/establishment/{establishmentNumber}/denomination/{language}
Arguments and parameters
-
FieldTypeDescription
-
establishmentNumber
integer
Number of the establishmentExample:2147197839
-
language
string
The language code of the denomination. Some denominations may not have the language specified, use theunknown
value in this case.Possible values:unknown
nl
en
fr
de
Example:nl
Response
Successful response | The denomination has been found.
-
FieldTypeDescription
-
Denomination
object
-
entityNumber
string
Example:0417497106
-
entityNumberFormatted
string
Example:0417.497.106
-
entityType
string
Possible values:enterprise
establishment
Example:enterprise
-
language
string
Possible values:unknown
nl
en
fr
de
Example:nl
-
value
string
The denomination nameExample:FaimMedia B.V.
-
type
string
The denomination typePossible values:social
abbreviation
commercial
Example:social
-
typeDescription
object
-
nl
string
Dutch translation of the type descriptionExample:Maatschappelijke naam
-
en
string
English translation of the type descriptionExample:Primary name
-
fr
string
French translation of the type descriptionExample:Dénomination sociale
-
de
string
German translation of the type descriptionExample:Primärname
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/establishment/{establishmentNumber}/denomination/{language}
{ "Denomination": { "entityNumber": "0417497106", "entityNumberFormatted": "0417.497.106", "entityType": "enterprise", "language": "nl", "value": "FaimMedia B.V.", "type": "social", "typeDescription": { "nl": "Maatschappelijke naam", "en": "Primary name", "fr": "D\u00e9nomination sociale", "de": "Prim\u00e4rname" } } }
HTTP/1.1 200 OK
404
Item or resource not found
{ "exception": "RequestException", "error": "The item specified could not be found", "code": "-2" }
/denominations
Search request
Arguments and parameters
-
FieldTypeDescription
-
query
string
The keywords to search for the denominations.Example:AB Inbev
-
entityType
string
Accepted values: enterprise: show only enterprises, establishment: show only establishmentsPossible values:enterprise
establishment
Example:enterprise
-
type
string
Filter on the type of denomination.Possible values:social
abbreviation
commercial
Example:commercial
-
active
Large planstring
Choose if you want search results from inactive enterprises and establishments returned. The default is only active.Possible values:active
inactive
all
Example:active
-
language
string
Search only in this language specified fieldsPossible values:nl
fr
en
de
Example:nl
-
page
integer
The page of the results that should be returnedExample:2
-
limit
integer
The limit of results that should be returned, can be a value somewhere between 1 and your plan's maximum. If a higher value is used, this parameter is ignored and your plan's maximum is used instead.Example:30
Response
Successful response | All denominations matching the provided search criteria.
-
FieldTypeDescription
-
Denominations
array
-
Demomination
object
-
entityNumber
string
Example:0417497106
-
entityNumberFormatted
string
Example:0417.497.106
-
entityType
string
Possible values:enterprise
establishment
Example:enterprise
-
language
string
Possible values:unknown
nl
en
fr
de
Example:nl
-
value
string
The denomination nameExample:FaimMedia B.V.
-
type
string
The denomination typePossible values:social
abbreviation
commercial
Example:social
-
typeDescription
object
-
nl
string
Dutch translation of the type descriptionExample:Maatschappelijke naam
-
en
string
English translation of the type descriptionExample:Primary name
-
fr
string
French translation of the type descriptionExample:Dénomination sociale
-
de
string
German translation of the type descriptionExample:Primärname
-
Pagination
object
-
limit
integer
The used pagination limit, by default the maximum limit allowed by your planExample:10
-
page
integer
The current pageExample:1
-
totalPages
integer
The number of pagesExample:99
-
totalItems
integer
The total number of items in the source dataExample:1234
-
countItems
integer
The number of items in the current requestExample:8
-
estimate
boolean
If true, the number of total items is based on a quick scan. The total item count may vary if the next page is requested.Example:1
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/denominations
{ "Denominations": [ { "Demomination": { "entityNumber": "0417497106", "entityNumberFormatted": "0417.497.106", "entityType": "enterprise", "language": "nl", "value": "FaimMedia B.V.", "type": "social", "typeDescription": { "nl": "Maatschappelijke naam", "en": "Primary name", "fr": "D\u00e9nomination sociale", "de": "Prim\u00e4rname" } } } ], "Pagination": { "limit": "10", "page": "1", "totalPages": "99", "totalItems": "1234", "countItems": "8", "estimate": "1" } }
HTTP/1.1 200 OK
422
Invalid response, missing or incorrect parameter
{ "exception": [], "error": [], "code": [] }
402
Larger plan required for this parameter
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "parameter": "active", "code": "-31" }
/addresses
Search request
Arguments and parameters
-
FieldTypeDescription
-
query
string
Search queryExample:Grote Markt
-
entityType
string
Filter for a specific entity typePossible values:enterprise
establishment
Example:enterprise
-
active
Large planstring
Choose if you want search results from inactive enterprises and establishments returned. The default is only active.Possible values:active
inactive
all
Example:active
-
fields[]
array
Provide the fields that need to be queried. Possible values:
*street
: Search in the street fieldzipcode
: Search in the zipcode field
city
: Search in the city field
country
: Search in the country field
-
page
integer
The page of the results that should be returnedExample:2
-
limit
integer
The limit of results that should be returned, can be a value somewhere between 1 and your plan's maximum. If a higher value is used, this parameter is ignored and your plan's maximum is used instead.Example:30
-
type
string
Possible values:branch
establishment
active-establishment
legal-entity
Example:branch
Response
Successful response | All addresses matching the provided search criteria.
-
FieldTypeDescription
-
Addresses
array
-
Address
object
-
entityNumber
string
Example:0417497106
-
entityNumberFormatted
string
Example:0417.497.106
-
entityType
string
Possible values:enterprise
establishment
Example:enterprise
-
type
string
-Possible values:branch
establishment
active-establishment
legal-entity
Example:branch
-
typeDescription
object
-
street
object
Street of the registration -
nl
string
Dutch street translation of the registrationExample:Kerkstraat
-
fr
string
French street translation of the registrationExample:Rue de l'Église
-
addressNumber
string
Address street number of the registrationExample:1
-
addressAdditional
string
Additional address or street suffixExample:Unit 12, Floor 5
-
postOfficeBox
string
The post office box of the address, if applicableExample:Box 5
-
zipcode
string
Zipcode of the registrationExample:2000
-
city
object
City of the registration -
nl
string
Dutch city translation of the registrationExample:Brussel
-
fr
string
French city translation of the registrationExample:Bruxelles
-
countryCode
string
The ISO 3166-1 alpha-2 country code of the address.Example:fr
-
country
object
Translated name of the country code. -
nl
string
Dutch translation of the countryExample:Frankrijk
-
fr
string
French translation of the countryExample:France
-
en
string
English translation of the countryExample:France
-
de
string
German translation of the country -
dateRevoke
string
-
dateStart
string
Example:2020-01-01
-
Pagination
object
-
limit
integer
The used pagination limit, by default the maximum limit allowed by your planExample:10
-
page
integer
The current pageExample:1
-
totalPages
integer
The number of pagesExample:99
-
totalItems
integer
The total number of items in the source dataExample:1234
-
countItems
integer
The number of items in the current requestExample:8
-
estimate
boolean
If true, the number of total items is based on a quick scan. The total item count may vary if the next page is requested.Example:1
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/addresses
{ "Addresses": [ { "Address": { "entityNumber": "0417497106", "entityNumberFormatted": "0417.497.106", "entityType": "enterprise", "type": "branch", "typeDescription": { "nl": "Maatschappelijke zetel", "en": "Head office", "fr": "Si\u00e8ge social", "de": "Sitzes Adresse" }, "street": { "nl": "Kerkstraat", "fr": "Rue de l'\u00c9glise" }, "addressNumber": "1", "addressAdditional": "Unit 12, Floor 5", "postOfficeBox": "Box 5", "zipcode": "2000", "city": { "nl": "Brussel", "fr": "Bruxelles" }, "countryCode": "fr", "country": { "nl": "Frankrijk", "fr": "France", "en": "France", "de": "string" }, "dateRevoke": "string", "dateStart": "2020-01-01" } } ], "Pagination": { "limit": "10", "page": "1", "totalPages": "99", "totalItems": "1234", "countItems": "8", "estimate": "1" } }
HTTP/1.1 200 OK
422
Invalid response, missing or incorrect parameter
{ "exception": [], "error": [], "code": [] }
402
Larger plan required for this parameter
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "parameter": "active", "code": "-31" }
/naces
Search request
Arguments and parameters
-
FieldTypeDescription
-
query
string
Search queryExample:ICT-apparatuur
-
language
string
Specify in which language should be searched. If this parameter is omitted, all available languages will be searched.Possible values:nl
fr
de
en
Example:nl
-
page
integer
The page of the results that should be returnedExample:2
-
limit
integer
The limit of results that should be returned, can be a value somewhere between 1 and your plan's maximum. If a higher value is used, this parameter is ignored and your plan's maximum is used instead.Example:30
Response
Successful response | All NACEs matching the provided search criteria.
-
FieldTypeDescription
-
Naces
array
-
Nace
object
-
naceVersion
integer
Example:2008
-
naceCode
string
Example:474
-
description
object
-
nl
string
Dutch descriptionExample:Detailhandel in ICT-apparatuur in gespecialiseerde winkels
-
fr
string
French descriptionExample:Commerce de détail d'équipements de l'information et de la communication en magasin spécialisé
-
de
string
German descriptionExample:Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)
-
en
string
English descriptionExample:Retail sale of information and communication equipment in specialised stores
-
Pagination
object
-
limit
integer
The used pagination limit, by default the maximum limit allowed by your planExample:10
-
page
integer
The current pageExample:1
-
totalPages
integer
The number of pagesExample:99
-
totalItems
integer
The total number of items in the source dataExample:1234
-
countItems
integer
The number of items in the current requestExample:8
-
estimate
boolean
If true, the number of total items is based on a quick scan. The total item count may vary if the next page is requested.Example:1
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/naces
{ "Naces": [ { "Nace": { "naceVersion": "2008", "naceCode": "474", "description": { "nl": "Detailhandel in ICT-apparatuur in gespecialiseerde winkels", "fr": "Commerce de d\u00e9tail d'\u00e9quipements de l'information et de la communication en magasin sp\u00e9cialis\u00e9", "de": "Einzelhandel mit Ger\u00e4ten der Informations- und Kommunikationstechnik (in Verkaufsr\u00e4umen)", "en": "Retail sale of information and communication equipment in specialised stores" } } } ], "Pagination": { "limit": "10", "page": "1", "totalPages": "99", "totalItems": "1234", "countItems": "8", "estimate": "1" } }
HTTP/1.1 200 OK
/nace/{naceVersion}/{naceCode}
Arguments and parameters
-
FieldTypeDescription
-
naceVersion
integer
NACE versionExample:2003
-
naceCode
string
NACE codeExample:01
Response
Successful response, NACE is found.
-
FieldTypeDescription
-
Nace
object
-
naceVersion
integer
Example:2008
-
naceCode
string
Example:474
-
description
object
-
nl
string
Dutch descriptionExample:Detailhandel in ICT-apparatuur in gespecialiseerde winkels
-
fr
string
French descriptionExample:Commerce de détail d'équipements de l'information et de la communication en magasin spécialisé
-
de
string
German descriptionExample:Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)
-
en
string
English descriptionExample:Retail sale of information and communication equipment in specialised stores
Example
200
Successful response, NACE is found.
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/nace/{naceVersion}/{naceCode}
{ "Nace": { "naceVersion": "2008", "naceCode": "474", "description": { "nl": "Detailhandel in ICT-apparatuur in gespecialiseerde winkels", "fr": "Commerce de d\u00e9tail d'\u00e9quipements de l'information et de la communication en magasin sp\u00e9cialis\u00e9", "de": "Einzelhandel mit Ger\u00e4ten der Informations- und Kommunikationstechnik (in Verkaufsr\u00e4umen)", "en": "Retail sale of information and communication equipment in specialised stores" } } }
HTTP/1.1 200 OK
/roles
Large plan
Search request
Arguments and parameters
-
FieldTypeDescription
-
query
string
Search query, will search for a partial role titleExample:Manager
-
language
string
Specify in which language should be searched. If this parameter is omitted, all available languages will be searched.Possible values:nl
en
fr
de
Example:en
-
page
integer
The page of the results that should be returnedExample:2
-
limit
integer
The limit of results that should be returned, can be a value somewhere between 1 and your plan's maximum. If a higher value is used, this parameter is ignored and your plan's maximum is used instead.Example:30
Response
Successful response | All function titles returned
-
FieldTypeDescription
-
Roles
array
-
Role
object
-
roleCode
integer
Code of the function title. Please be aware that this code may change at anytime, so it's advisable not to put to much reference to this value. Or to check periodicly for any changes.Example:5
-
title
object
-
nl
string
Function title in DutchExample:Zaakvoerder
-
en
string
Function title in EnglishExample:Manager
-
fr
string
Function title in FrenchExample:Gérant
-
de
string
Function title in GermanExample:Geschäftsführer
-
note
object
Possible note regarding function title -
nl
string
Possible note regarding function title in DutchExample:Overeenkomstig het Wetboek van Vennootschappen en Verenigingen moet de term "Zaakvoerder" vanaf 1 januari 2020 gelezen worden als "Bestuurder"
-
en
string
Possible note regarding the function title in EnglishExample:Pursuant to the Code of Companies and Associations, the term "Manager" must, since January 1, 2020, be read as "Board member".
-
fr
string
Possible note regarding function title in FrenchExample:En application du Code des sociétés et des associations, le terme "Gérant" doit, depuis le 1er janvier 2020, être lu comme étant "Administrateur".
-
de
string
Possible note regarding function title in GermanExample:Gemäß dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff "Geschäftsführer" seit dem 1. Januar 2020 als "Verwalter" zu lesen.
-
Pagination
object
-
limit
integer
The used pagination limit, by default the maximum limit allowed by your planExample:10
-
page
integer
The current pageExample:1
-
totalPages
integer
The number of pagesExample:99
-
totalItems
integer
The total number of items in the source dataExample:1234
-
countItems
integer
The number of items in the current requestExample:8
-
estimate
boolean
If true, the number of total items is based on a quick scan. The total item count may vary if the next page is requested.Example:1
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/roles
{ "Roles": [ { "Role": { "roleCode": "5", "title": { "nl": "Zaakvoerder", "en": "Manager", "fr": "G\u00e9rant", "de": "Gesch\u00e4ftsf\u00fchrer" }, "note": { "nl": "Overeenkomstig het Wetboek van Vennootschappen en Verenigingen moet de term \"Zaakvoerder\" vanaf 1 januari 2020 gelezen worden als \"Bestuurder\"\n", "en": "Pursuant to the Code of Companies and Associations, the term \"Manager\" must, since January 1, 2020, be read as \"Board member\".\n", "fr": "En application du Code des soci\u00e9t\u00e9s et des associations, le terme \"G\u00e9rant\" doit, depuis le 1er janvier 2020, \u00eatre lu comme \u00e9tant \"Administrateur\".\n", "de": "Gem\u00e4\u00df dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff \"Gesch\u00e4ftsf\u00fchrer\" seit dem 1. Januar 2020 als \"Verwalter\" zu lesen.\n" } } } ], "Pagination": { "limit": "10", "page": "1", "totalPages": "99", "totalItems": "1234", "countItems": "8", "estimate": "1" } }
HTTP/1.1 200 OK
402
Larger plan required
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "code": "-31" }
/role/{roleCode}
Large plan
Arguments and parameters
-
FieldTypeDescription
-
roleCode
integer
The role codeExample:5
Response
Successful response | Function title is returned
-
FieldTypeDescription
-
Role
object
-
roleCode
integer
Code of the function title. Please be aware that this code may change at anytime, so it's advisable not to put to much reference to this value. Or to check periodicly for any changes.Example:5
-
title
object
-
nl
string
Function title in DutchExample:Zaakvoerder
-
en
string
Function title in EnglishExample:Manager
-
fr
string
Function title in FrenchExample:Gérant
-
de
string
Function title in GermanExample:Geschäftsführer
-
note
object
Possible note regarding function title -
nl
string
Possible note regarding function title in DutchExample:Overeenkomstig het Wetboek van Vennootschappen en Verenigingen moet de term "Zaakvoerder" vanaf 1 januari 2020 gelezen worden als "Bestuurder"
-
en
string
Possible note regarding the function title in EnglishExample:Pursuant to the Code of Companies and Associations, the term "Manager" must, since January 1, 2020, be read as "Board member".
-
fr
string
Possible note regarding function title in FrenchExample:En application du Code des sociétés et des associations, le terme "Gérant" doit, depuis le 1er janvier 2020, être lu comme étant "Administrateur".
-
de
string
Possible note regarding function title in GermanExample:Gemäß dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff "Geschäftsführer" seit dem 1. Januar 2020 als "Verwalter" zu lesen.
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/role/{roleCode}
{ "Role": { "roleCode": "5", "title": { "nl": "Zaakvoerder", "en": "Manager", "fr": "G\u00e9rant", "de": "Gesch\u00e4ftsf\u00fchrer" }, "note": { "nl": "Overeenkomstig het Wetboek van Vennootschappen en Verenigingen moet de term \"Zaakvoerder\" vanaf 1 januari 2020 gelezen worden als \"Bestuurder\"\n", "en": "Pursuant to the Code of Companies and Associations, the term \"Manager\" must, since January 1, 2020, be read as \"Board member\".\n", "fr": "En application du Code des soci\u00e9t\u00e9s et des associations, le terme \"G\u00e9rant\" doit, depuis le 1er janvier 2020, \u00eatre lu comme \u00e9tant \"Administrateur\".\n", "de": "Gem\u00e4\u00df dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff \"Gesch\u00e4ftsf\u00fchrer\" seit dem 1. Januar 2020 als \"Verwalter\" zu lesen.\n" } } }
HTTP/1.1 200 OK
402
Larger plan required
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "code": "-31" }
404
Item or resource not found
{ "exception": "RequestException", "error": "The item specified could not be found", "code": "-2" }
/juridical-forms
Large plan
Search request
Arguments and parameters
-
FieldTypeDescription
-
query
string
Search query, will search for a (partial) juridical formExample:Vennoot
-
language
string
Specify in which language should be searched. If this parameter is omitted, all available languages will be searched.Possible values:nl
fr
de
en
Example:nl
-
page
integer
The page of the results that should be returnedExample:2
-
limit
integer
The limit of results that should be returned, can be a value somewhere between 1 and your plan's maximum. If a higher value is used, this parameter is ignored and your plan's maximum is used instead.Example:30
Response
Successful response | All juridical forms matching your search criteria are returned.
-
FieldTypeDescription
-
JuridicalForms
array
-
JuridicalForm
object
-
juridicalFormCode
string
Juridical Form codeExample:030
-
description
object
-
nl
string
Dutch description of the juridical formExample:Buitenlandse entiteit
-
fr
string
French description of the juridical formExample:Entité étrangère
-
de
string
German description of the juridical formExample:Ausländische Einheit
-
Pagination
object
-
limit
integer
The used pagination limit, by default the maximum limit allowed by your planExample:10
-
page
integer
The current pageExample:1
-
totalPages
integer
The number of pagesExample:99
-
totalItems
integer
The total number of items in the source dataExample:1234
-
countItems
integer
The number of items in the current requestExample:8
-
estimate
boolean
If true, the number of total items is based on a quick scan. The total item count may vary if the next page is requested.Example:1
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/juridical-forms
{ "JuridicalForms": [ { "JuridicalForm": { "juridicalFormCode": "030", "description": { "nl": "Buitenlandse entiteit", "fr": "Entit\u00e9 \u00e9trang\u00e8re", "de": "Ausl\u00e4ndische Einheit" } } } ], "Pagination": { "limit": "10", "page": "1", "totalPages": "99", "totalItems": "1234", "countItems": "8", "estimate": "1" } }
HTTP/1.1 200 OK
402
Larger plan required
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "code": "-31" }
/juridical-situations
Large plan
Search request
Arguments and parameters
-
FieldTypeDescription
-
query
string
Search query, will search for a (partial) juridical situationExample:Stop
-
language
string
Specify in which language should be searched. If this parameter is omitted, all available languages will be searched.Possible values:nl
fr
de
en
Example:nl
-
page
integer
The page of the results that should be returnedExample:2
-
limit
integer
The limit of results that should be returned, can be a value somewhere between 1 and your plan's maximum. If a higher value is used, this parameter is ignored and your plan's maximum is used instead.Example:30
Response
Successful response | All juridical situations matching your search criteria are returned.
-
FieldTypeDescription
-
JuridicalSituations
array
-
JuridicalSituation
object
-
juridicalSituationCode
string
Juridical Situation codeExample:000
-
description
object
-
nl
string
Dutch description of the juridical situationExample:Normale toestand
-
fr
string
French description of the juridical situationExample:Situation normale
-
de
string
German description of the juridical situationExample:Gewöhnlicher Zustand
-
Pagination
object
-
limit
integer
The used pagination limit, by default the maximum limit allowed by your planExample:10
-
page
integer
The current pageExample:1
-
totalPages
integer
The number of pagesExample:99
-
totalItems
integer
The total number of items in the source dataExample:1234
-
countItems
integer
The number of items in the current requestExample:8
-
estimate
boolean
If true, the number of total items is based on a quick scan. The total item count may vary if the next page is requested.Example:1
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/juridical-situations
{ "JuridicalSituations": [ { "JuridicalSituation": { "juridicalSituationCode": "000", "description": { "nl": "Normale toestand", "fr": "Situation normale", "de": "Gew\u00f6hnlicher Zustand" } } } ], "Pagination": { "limit": "10", "page": "1", "totalPages": "99", "totalItems": "1234", "countItems": "8", "estimate": "1" } }
HTTP/1.1 200 OK
402
Larger plan required
{ "exception": "PlanScopeException", "error": "Your active plan doesn't meet the requirements for this endpoint", "code": "-31" }
/vat/{vatNumber}
Only use this method for validating the VAT-number for international transactions within the EU, not for retrieving company information, you may use the
/enterprise
endpoints for that purpose.Even though the response may say the VAT-number is invalid, it may still be valid for domestic transactions.
Arguments and parameters
-
FieldTypeDescription
-
vatNumber
string
The VAT-number to be validated, a valid Belgian VAT-number starts with BE followed by 10 digits. The field may also contains a valid Enterprise numberExample:BE0417497106
Response
Successful response | The VAT-number has been validated. Please note: this does not necessary mean the provided VAT-number is valid, check the `isValid` value of the response.
-
FieldTypeDescription
-
vatNumber
string
The validated VAT-numberExample:BE0417497106
-
isValid
boolean
Boolean if provided VAT-number is validExample:1
-
details
object
-
name
string
Example:NV BELFIUS BANK
-
address
string
Use the enterprise address endpoint instead.Example:Karel Rogierplein 11, 1210 Sint-Joost-ten-Node
-
enterpriseNumber
string
Example:0417497106
-
enterpriseNumberFormatted
string
Example:0417.497.106
Example
200
Successful response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/vat/{vatNumber}
{ "vatNumber": "BE0417497106", "isValid": "1", "details": { "name": "NV BELFIUS BANK", "address": "Karel Rogierplein 11, 1210 Sint-Joost-ten-Node" }, "enterpriseNumber": "0417497106", "enterpriseNumberFormatted": "0417.497.106" }
HTTP/1.1 200 OK
404
Item or resource not found
{ "exception": "RequestException", "error": "The item specified could not be found", "code": "-2" }
500
Service for VAT-validation is not available.
/me
Response
Success response | The provided authorization token is valid.
-
FieldTypeDescription
-
Customer
object
-
name
string
The username of the authorized customerExample:My Company Ltd.
-
planName
string
Active plan nameExample:Small
-
dateCreated
string
The date the customer is createdExample:2020-02-02 02:02:02
-
username
object
-
planDescription
object
-
ApiAccessToken
object
-
isDevelopment
boolean
API-token type -
description
string
The customer defined description of the tokenExample:Development-token
-
dateCreated
string
Example:2020-02-02 02:02:02
-
dateExpiration
string
Example:2021-02-02 02:02:02
Example
200
Success response
curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \ https://api.kbodata.app/v2/me
{ "Customer": { "name": "My Company Ltd.", "planName": "Small", "dateCreated": "2020-02-02 02:02:02", "username": [], "planDescription": [] }, "ApiAccessToken": { "isDevelopment": "boolean", "description": "Development-token", "dateCreated": "2020-02-02 02:02:02", "dateExpiration": "2021-02-02 02:02:02" } }
HTTP/1.1 200 OK
401
Invalid authorization token provided
{ "exception": "AuthorizationException", "error": "The provided access token is invalid", "code": "-2" }
Responses
HTTP status codes
By looking at the HTTP response code, you can see if the request was successful or not. If the request was unsuccessful, you can usually use the HTTP response code and the error message in the JSON-response to find out what went wrong. You probably need change something in the request parameters.
Below is a list of common HTTP response codes, used in our API:
-
200 OK
Success The request was successful and the data can be used. -
401 Unauthorized
Not authorized You will retrieve this status code if the authorization fails, possible by using an incorrect username or access token. -
402 Payment Required
Means that your plan has expired and needs renewal. You can do this on your dashboard. -
404 Not Found
Will be returned if the specific item requested, cannot be found. Also used when an endpoint doesn't exist, but the API-token is valid. -
405 Method Not Allowed
The used request method is unaccepted, in example this will be returned when the requested method isPOST
, but should be aGET
. -
409 Conflict
422 Unprocessable Entity
Incorrect or missing parameters The requested request could not be processed, usually due missing required parameters or parameters that contain an incorrect format. -
429 Too Many Requests
Request limit exceeded You have exceeded the maximum number of requests for this period, wait until for a limit reset at the end of your period or upgrade your subscription plan. You can do this on your dashboard.