Endpoints
All end-points must begin with this protocol and domain https://api.kbodata.app/v1/
.
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.
Enterprises
GET
/enterprise/get.json
Retreive the enterprise details by the enterpise number.
Arguments
-
enterpriseNumber
The enterprise number (chamber of commerce number) of the registration.
Response
-
enterpriseNumber
The enterprise number without punctuation marks. -
enterpriseNumberFormatted
The enterprise number seperated by punctuation marks. -
status
The registration subscription status of the enterprise,1
is most cases. -
type
Code relating to the type of registration. 0: Unknown, 1: Natural person, 2: Legal person -
typeDescription
Description relating to the type of registration -
juridicalSituationCode
Legal situation code -
juridicalSituationDescription
Legal situation description -
juridicalFormCode
Legal form code -
juridicalFormDescription
Legal form description -
dateStart
Registration date of the enterprise -
vatNumber
The VAT number of the enterprise
Always verify the VAT number for cross-border transactions. -
addresses
De addressen die zijn gekoppeld aan de ondernemingsinschrijving. Voor de specifieke velden kunt u de adressen-sectie raadplegen. -
establishments
De vestigingen die zijn gekoppeld aan de ondernemingsinschrijving. Voor de specifieke velden kunt u de vestigingen-sectie raadplegen. -
denominations
De handelsnamen die zijn gekoppeld aan de ondernemingsinschrijving. Voor de specifieke velden kunt u de handelsnamen-sectie raadplegen.
Example
Demande
curl -X GET \ -u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \ https://api.kbodata.app/v1/enterprise/get.json?enterpriseNumber=0123456789
Réponse
{ "success": 1, "data": { "enterpriseNumber": "0123456789", "enterpriseNumberFormatted": "0123.456.789", "status": "1", "type": 2, "juridicalSituationCode": "000", "juridicalSituationDescription": "Normale toestand", "juridicalFormCode": "411", "juridicalFormDescription": "Stad \/ gemeente", "dateStart": "2000-01-01", "vatNumber": "BE0123456789", "addresses": [ { "type": "REGO", "typeDescription": "Maatschappelijke zetel", "zipcode": "6581", "cityNL": "Malden", "cityFR": "Malden", "streetNL": "De Steiger", "streetFR": "De Steiger", "addressNumber": "23", "addressAdditional": null, "dateRevoke": "2017-01-01" } ], "establishments": [ { "establishmentNumber": "2123456789", "establishmentNumberFormatted": "2.123.456.789", "dateStart": "2017-01-1" } ], "denominations": [ { "value": "KBO Databank", "language": "NL", "type": 1, "typeDescription": "Maatschappelijke naam" }, { "value": "KBO Base de données", "language": "FR", "type": 1, "typeDescription": "Maatschappelijke naam" } ] } }
VAT number
GET
/vat-number/verify.json
Check for a valid VAT number for cross-border transaction within the European Union (VIES).
Even if this method returns false
, the VAT number may still be valid for domestic (Belgium) transactions.
(this endpoint may only be used with a production access token, the request will fail with a development access token)
Arguments
-
enterpriseNumber
The enterprise number of the registration.
(this parameter must be omitted when the parametervatNumber
is being used) -
vatNumber
A Belgian VAT number, starting with BE, followed by 10 digits.BE0123456789
(this parameter must be omitted when the parameterenterpriseNumber
is being used)
Response
-
isValid
true
represents a valid VAT number;
false
represents an invalid VAT number or is invalid for cross-border transaction . -
vatNumber
The VAT-number that was being verified -
details
Registration details of the VAT-number, as known with the European Union.
(only with a valid VAT number) -
enterpriseNumber
The enterprise number of the verified enterprise.
(only by using theenterpriseNumber
argument) -
enterpriseNumberFormatted
The enterprise number of the verified enterprise, seperated by punctuation marks.
(only by using theenterpriseNumber
argument)
Example enterpriseNumber
Demande
curl -X GET \ -u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \ https://api.kbodata.app/v1/vat-number/verify.json?enterpriseNumber=0123456789
Réponse
{ "success": 1, "data": { "isValid": true, "vatNumber": "BE0123456789", "details": { "name": "FaimMedia B.V.", "address": "Steiger 00023, 6581KZ MALDEN" }, "enterpriseNumber": "0123456789", "enterpriseNumberFormatted": "0123.456.789" } }
Example vatNumber
Demande
curl -X GET \ -u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \ https://api.kbodata.app/v1/vat-number/verify.json?vatNumber=BE0123456789
Réponse
{ "success": 1, "data": { "isValid": true, "vatNumber": "BE0123456789", "details": { "name": "FaimMedia B.V.", "address": "Steiger 00023, 6581KZ MALDEN" } } }
Establishments
GET
/establishment/get.json
Retreive the establishment details by the establishment number.
Arguments
-
establishmentNumber
The establishment number of the registration.
Response
-
enterpriseNumber
The enterprise number without punctuation marks, that belongs to this establishment. -
enterpriseNumberFormatted
The enterprise number seperated by punctuation marks, that belongs to this establishment. -
establishmentNumber
The establishment number without punctuation marks. -
establishmentNumberFormatted
The estblishment number seperated by punctuation marks. -
dateStart
The registration date of the establishment. -
addresses
De addressen die zijn gekoppeld aan deze vestigingsinschrijving. Voor de specifieke velden kunt u de adressen-sectie raadplegen. -
denominations
De handelsnamen die zijn gekoppeld deze vestigingsinschrijving. Voor de specifieke velden kunt u de handelsnamen-sectie raadplegen.
Example
Demande
curl -X GET \ -u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \ https://api.kbodata.app/v1/establishment/get.json?establishmentNumber=0123456789
Réponse
{ "success": 1, "data": { "enterpriseNumber": "0123456789", "enterpriseNumberFormatted": "0123.456.789", "establishmentNumber": "2123456789", "establishmentNumberFormatted": "2.123.456.789", "dateStart": "2017-01-01", "addresses": [ { "type": "BAET", "typeDescription": "Vestigingseenheid", "zipcode": "6581", "cityNL": "Malden", "cityFR": "Malden", "streetNL": "De Steiger", "streetFR": "De Steiger", "addressNumber": "23", "addressAdditional": null, "dateRevoke": "2017-01-01" } ], "denominations": [ { "value": "KBO Databank", "language": "NL", "type": 1, "typeDescription": "Maatschappelijke naam" }, { "value": "KBO Base de données", "language": "FR", "type": 1, "typeDescription": "Maatschappelijke naam" } ] } }
Denominations
GET
/denomination/search.json
Search for denominations (trade name) by using keywords or an entity number.
Both enterprises and establishments can have one or more denominations. Although an enterprise almost always has at lease one denominations, this must not be assumed. So it is adviced to verify any denominations that belong to the enterprise' establishments.
Arguments
-
query
The keywords to search for the denominations.
(this parameter is not mandatory if the parameterentityNumber
is used) -
entityNumber
The enterprise number of establishment number of the registration.
(this parameter is not mandatory if the parameterquery
is used) -
filter[entityType]
Accepted values:enterprise
: show only enterprises,establishment
: show only establishments -
filter[type]
Filter on the type of denomination. You will find the accepted values in the response paragraph.
Response
-
entityNumber
The entity number without punctuation marks, that belongs to this registration. -
entityNumberFormatted
The entity number seperated by punctuation marks, that belongs to this registration. -
entityType
The type of denomination, incase of an enterprise this will beenterprise
, incase of an establishment,establishment
. -
enterpriseNumber
The enterprise number without punctuation marks, that belongs to this denomination. -
enterpriseNumberFormatted
The enterprise number seperated by punctuation marks, that belongs to this denomination. -
value
… -
language
… -
type
… -
typeDescription
… -
description
…
This field will only be shown if the denomination is linked to an establishment. In case that the denomination belongs to an enterprise the fields entityNumber
and entityNumberFormatted
already contains the enterprise number.
Example
Demande
curl -X GET \ -u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \ https://api.kbodata.app/v1/denomination/search.json?query=databank
Réponse
{ "success": 1, "count": 4, "pagination" : { }, "data": [ { "entityNumber": "0436969360", "entityNumberFormatted": "0436.969.360", "entityType": "enterprise", "value": "DE BRUGSE DATABANK", "language": "NL", "type": 1, "typeDescription": "Maatschappelijke naam", "description": "Maatschappelijke naam" }, { "entityNumber": "0442157870", "entityNumberFormatted": "0442.157.870", "entityType": "enterprise", "value": "INVESTMENTS OVERSEAS DATABANK EUROGOLD", "language": "FR", "type": 1, "typeDescription": "Maatschappelijke naam", "description": "Maatschappelijke naam" }, { "entityNumber": "0443786678", "entityNumberFormatted": "0443.786.678", "entityType": "enterprise", "value": "WEST VLAAMSE DATABANK", "language": "NL", "type": 1, "typeDescription": "Maatschappelijke naam", "description": "Maatschappelijke naam" }, { "entityNumber": "0446386476", "entityNumberFormatted": "0446.386.476", "entityType": "enterprise", "value": "Omni Databank", "language": "NL", "type": 1, "typeDescription": "Maatschappelijke naam", "description": "Maatschappelijke naam" } } }
Address
GET
/address/get.json
Retreive the address of an enterprise or establishment by using the entity number and type-code.
Arguments
-
entityNumber
The enterprise number of establishment number of the registration. -
type
The type-code of the registration address, possible values:1
: Branch2
: Location unit3
: Oldest active establishment unit4
: Registered Office
Response
-
entityNumber
Het inschrijfnummer zonder leestekens, dat bij deze vestigingsinschrijving hoort. -
entityNumberFormatted
Het inschrijfnummer gescheiden doormiddel van punten, dat bij deze vestigingsinschrijving hoort -
entityType
Het type handelsnaam, in het geval van een onderneming is ditenterprise
, in het geval van een vestiging is ditestablishment
. -
type
The type code of the address, possible values:0
: Unknown1
: Branch2
: Location unit3
: Oldest active establishment unit4
: Registered Office
-
typeDescription
De type omschrijving die bij de type code hoort. -
zipcode
Postcode van de inschrijving -
cityNL
De Nederlandse vertaling van de plaatsnaam -
cityFR
De Franse vertaling van de plaatsnaam -
streetNL
De Nederlands vertaling van de straatnaam -
streetFR
De Franse vertaling van de straatnaam -
addressNumber
Het huisnummer van de inschrijving -
addressAdditional
Eventuele extra adrestoevoeging -
dateRevoke
The revoke date of the address, could both be a date in the history or in the future.
Example
Demande
curl -X GET \ -u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \ https://api.kbodata.app/v1/address/get-list.json?entityNumber=0123456789&type=4
Réponse
{ "success": 1, "data": { "entityNumber": "0400377891", "entityNumberFormatted": "0400.377.891", "entityType": "enterprise", "type": 4, "typeDescription": "Maatschappelijke zetel", "zipcode": null, "cityNL": "Brierley Hill, Staffs", "cityFR": "Brierley Hill, Staffs", "streetNL": "P.O. Box 20 Leuches Bridge", "streetFR": "P.O. Box 20 Leuches Bridge", "addressNumber": null, "addressAdditional": null, "dateRevoke": "2017-03-31" } }
Addresses per entity
GET
/address/get-list.json
Retreive all addresses of an enterprise or establishment by using the entity number.
Arguments
-
entityNumber
The enterprise number or establishment number of the registration.
Response
The response values are the same as the get.json-request.
Voorbeeld
Demande
curl -X GET \
-u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \
https://api.kbodata.app/v1/address/get-list.json?entityNumber=0123456789
Réponse
{
"success": 1,
"data": [
{
"entityNumber": "0400377891",
"entityNumberFormatted": "0400.377.891",
"entityType": "enterprise",
"type": 4,
"typeDescription": "Maatschappelijke zetel",
"zipcode": null,
"cityNL": "Brierley Hill, Staffs",
"cityFR": "Brierley Hill, Staffs",
"streetNL": "P.O. Box 20 Leuches Bridge",
"streetFR": "P.O. Box 20 Leuches Bridge",
"addressNumber": null,
"addressAdditional": null,
"dateRevoke": "2017-03-31"
}
]
}
Demande
curl -X GET \ -u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \ https://api.kbodata.app/v1/address/get-list.json?entityNumber=0123456789
Réponse
{ "success": 1, "data": [ { "entityNumber": "0400377891", "entityNumberFormatted": "0400.377.891", "entityType": "enterprise", "type": 4, "typeDescription": "Maatschappelijke zetel", "zipcode": null, "cityNL": "Brierley Hill, Staffs", "cityFR": "Brierley Hill, Staffs", "streetNL": "P.O. Box 20 Leuches Bridge", "streetFR": "P.O. Box 20 Leuches Bridge", "addressNumber": null, "addressAdditional": null, "dateRevoke": "2017-03-31" } ] }
Address search
GET
/address/search.json
Retreive all addresses by using a search query.
Arguments
-
query
The search query, this field must contain atlease three characters. -
fields
(array)A range (array) of search fields, possible values are:street
,zipcode
,city
. If the argument is omitted, all fields will be used. -
type
The type-code of the registration address, possible values:1
: Branch2
: Location unit3
: Oldest active establishment unit4
: Registered Office
Response
The response values are the same as the get.json-request.
Example
Demande
curl -X GET \ -u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \ https://api.kbodata.app/v1/address/search.json?query=Kerk&fields[]=street&fields[]=city&type=4
Réponse
{ "success": 1, "data": [ { "entityNumber": "0400377891", "entityNumberFormatted": "0400.377.891", "entityType": "enterprise", "type": 4, "typeDescription": "Maatschappelijke zetel", "zipcode": null, "cityNL": "Brierley Hill, Staffs", "cityFR": "Brierley Hill, Staffs", "streetNL": "P.O. Box 20 Leuches Bridge", "streetFR": "P.O. Box 20 Leuches Bridge", "addressNumber": null, "addressAdditional": null, "dateRevoke": "2017-03-31" } ] }
Activities
GET
/activity/get-list.json
Retreive all activities (sectors and branches) of an enterprise or establishment.
Arguments
-
entityNumber
The enterprise number or establishment number of the registration. -
filter[naceVersion]
Filter the fieldnaceVersion
-
filter[naceCode]
Filter the fieldnaceCode
-
filter[activityGroup]
Filter the fieldactivityGroup
-
filter[classification]
Filter the fieldclassification
Response
-
activityGroup
The activity group code. -
activityGroupDescription
The description of the activity group. -
naceVersion
Nace version -
naceCode
Nace code -
naceDescription
Nace description -
classification
Classification code -
classificationDescription
Classification description
Example
Demande
curl -X GET \ -u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \ https://api.kbodata.app/v1/activity/get-list.json?entityNumber=0123456789
Réponse
{ "success": 1, "count": 4, "data": [ { "activityGroup": "BTW001", "activityGroupDescription": "BTW-activiteiten", "naceVersion": 2003, "naceCode": "41000", "naceDescription": "Winning, zuivering en distributie van water", "classification": "MAIN", "classificationDescription": "Hoofdactiviteit" }, { "activityGroup": "BTW001", "activityGroupDescription": "BTW-activiteiten", "naceVersion": 2008, "naceCode": "84114", "naceDescription": "Gemeentelijke overheid, met uitzondering van het O.C.M.W.", "classification": "MAIN", "classificationDescription": "Hoofdactiviteit" }, { "activityGroup": "BTW001", "activityGroupDescription": "BTW-activiteiten", "naceVersion": 2008, "naceCode": "56309", "naceDescription": "Andere drinkgelegenheden", "classification": "SECO", "classificationDescription": "Nevenactiviteit" }, { "activityGroup": "PPO001", "activityGroupDescription": "RSZPPO-activiteiten", "naceVersion": 2008, "naceCode": "84114", "naceDescription": "Gemeentelijke overheid, met uitzondering van het O.C.M.W.", "classification": "MAIN", "classificationDescription": "Hoofdactiviteit" } ] }
Authorization
GET
/authorization/me.json
Retreive usefull information about the currently used API-key and the customer linked to this key.
Example
Demande
curl -X GET \ -u user@company.com:tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7 \ https://api.kbodata.app/v1/authorization/me.json
Réponse
{ "success": 1, "data": { "customer": { "username": "user@company.com", "planDescription": "Large", "dateCreated": "2017-03-31 13:51:28" }, "accessToken": { "isDevelopment": false, "description": "Website production key", "dateCreated": "2017-03-31 13:52:45", "dateExpiration": "2018-03-31" } } }
Responses
HTTP status codes
Bij het antwoord van uw verzoek wordt meegestuurd of het antwoord succesvol is. Dit wordt gedaan middels de HTTP-statuscode. Indien een verzoek niet succesvol is, kunt u meestal aan de hand van de HTTP-status en de fout in het JSON-antwoord achterhalen wat er misging en eventueel aangepast dient te worden in het verzoek. Hieronder treft u een lijst met veel voorkomende HTTP-status codes die gebruikt worden in onze API.
Tevens wordt er een extra success
parameter meegestuurd in het antwoord, deze is 1
(cijfer één) bij een succesvol verzoek en 0
(cijfer nul) bij een fouttief verzoek. Hieruit is echter niet te herleiden om wat voor een type fout het gaat.
-
200 OK
Success The request was successful and the data can be used. -
401 Unauthorized
Not authorized You will retreive this status code if the authorization fails, possible by using a 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
Wordt als antwoord gegeven als het specifiek opgevraagde item niet kan worden gevonden. Wordt tevens gebruikt bij een methode die niet bestaat, maar de API-sleutel wel geldig is. -
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
Conflict Het aangevraagde verzoek kon niet worden verwerkt, meestal door parameters die verplicht zijn, maar niet in het verzoek aanwezig zijn of parameters die een onjuist formaat bevatten. -
429 Too Many Requests
Request limit exceeded U hebt het maximaal aantal verzoeken voor deze maand overschreven, wacht tot het einde van uw periode totdat het limiet gereset word of upgrade uw abbonement. Dit kunt u doen in uw dashboard.