API documentation

Dépréciation de l'API: Cette version de l'API est dépréciée, ne l'utilisez que si elle est déjà impliquée ! Veuillez utiliser la version la plus récente pour les nouveaux projets.

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 parameter vatNumber is being used)
vatNumber

A Belgian VAT number, starting with BE, followed by 10 digits. BE0123456789
(this parameter must be omitted when the parameter enterpriseNumber 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 the enterpriseNumber argument)
enterpriseNumberFormatted

The enterprise number of the verified enterprise, seperated by punctuation marks.
(only by using the enterpriseNumber 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 parameter entityNumber is used)
entityNumber

The enterprise number of establishment number of the registration.
(this parameter is not mandatory if the parameter query 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 be enterprise, 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: Branch
- 2: Location unit
- 3: Oldest active establishment unit
- 4: 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 dit enterprise, in het geval van een vestiging is dit establishment.
type
The type code of the address, possible values:
- 0: Unknown
- 1: Branch
- 2: Location unit
- 3: Oldest active establishment unit
- 4: 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"
		}
	]
}

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: Branch
- 2: Location unit
- 3: Oldest active establishment unit
- 4: 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 field naceVersion
filter[naceCode]

Filter the field naceCode
filter[activityGroup]

Filter the field activityGroup
filter[classification]

Filter the field classification

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 is POST, but should be a GET.
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.

API documentation

Endpoints

Enterprises

Arguments

Response

Example

Demande

Réponse

VAT number

Arguments

Response

Example enterpriseNumber

Demande

Réponse

Example vatNumber

Demande

Réponse

Establishments

Arguments

Response

Example

Demande

Réponse

Denominations

Arguments

Response

Example

Demande

Réponse

Address

Arguments

Response

Example

Demande

Réponse

Addresses per entity

Arguments

Response

Voorbeeld

Demande

Réponse

Address search

Arguments

Response

Example

Demande

Réponse

Activities

Arguments

Response

Example

Demande

Réponse

Authorization

Example

Demande

Réponse

Responses

HTTP status codes

Cookies

Example `enterpriseNumber`

Example `vatNumber`