API documentation

Intro

Our JSON REST-API is easy to integrate and contains a logical structure of the methods.

What's an API?

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.

What's an REST API?

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.

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

The provided authorization token is valid.

Response (example) Request Response (headers)

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

Field

Type

Description

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.

Example (headers)

Response (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

The headers below are displayed in a request. Some values may depend on the type of key used (development- or production key).

Header

Type

Description

This details serves as an aid, and can also be seen visually on your dashboard.

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 name

Type

Description

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}

Retrieve enterprise details.

Retrieve the enterprise details by the enterprise number.

Arguments and parameters

Field

Type

Description
enterpriseNumber

integer

Number of the enterprise

Example: 0417497106

Response

Successful response | Enterprise is found.

Field

Type

Description
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 number

Example: BE0417497106
status

integer

Example: 1
active

boolean

Whether the registration status of the establishment is active or inactive

Example: 1
type

string

The company type, natural for natural person or entity for legal entity.

Possible values: natural entity

Example: entity
typeDescription

object
nl

string

Dutch description

Example: Rechtspersoon
en

string

English description

Example: Legal entity
fr

string

French description

Example: Personne morale
de

string

German description

Example: Juristische Person
JuridicalForm

object
juridicalFormCode

string

Juridical Form code

Example: 030
description

object
nl

string

Dutch description of the juridical form

Example: Buitenlandse entiteit
fr

string

French description of the juridical form

Example: Entité étrangère
de

string

German description of the juridical form

Example: Ausländische Einheit
JuridicalSituation

object
juridicalSituationCode

string

Juridical Situation code

Example: 000
description

object
nl

string

Dutch description of the juridical situation

Example: Normale toestand
fr

string

French description of the juridical situation

Example: Situation normale
de

string

German description of the juridical situation

Example: Gewöhnlicher Zustand
dateStart

string

Example: 2020-01-01

Example

`200` Successful response

Enterprise is found.

Response (example) Request Response (headers)

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

The specified Enterprise number could not be found, please make sure the enterprise number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `enterprise` item specified could not be found",
    "code": "-2"
}

/enterprise/{enterpriseNumber}/activities

Retrieve all enterprise activities.

Retrieve all registered activity details by the enterprise number.

Arguments and parameters

Field

Type

Description
enterpriseNumber

integer

Number of the enterprise

Example: 0417497106

Response

Successful response | All activities from the enterprise.

Field

Type

Description
[]

array
Activity

object
activityGroup

string

Possible values: BTW001 EDR001 OLK001 POR001 PPO001 RSZ001 SCO001

Example: BTW001
activityGroupDescription

object
nl

string

Dutch description

Example: BTW-activiteiten
fr

string

French description

Example: Activités TVA
en

string

English description

Example: VAT activities
de

string

German description

Example: MwSt.-Aktivitäten
classification

string

Possible values: ANCI MAIN SECO

Example: MAIN
classificationDescription

object
nl

string

Dutch description

Example: Hoofdactiviteit
fr

string

French description

Example: Activité principale
en

string

English description

Example: Main activity
de

string

German description

Example: Hauptaktivität
Nace

object
naceVersion

integer

Example: 2008
naceCode

string

Example: 474
description

object
nl

string

Dutch description

Example: Detailhandel in ICT-apparatuur in gespecialiseerde winkels
fr

string

French description

Example: Commerce de détail d'équipements de l'information et de la communication en magasin spécialisé
de

string

German description

Example: Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)
en

string

English description

Example: Retail sale of information and communication equipment in specialised stores

Example

`200` Successful response

All activities from the enterprise.

Response (example) Request Response (headers)

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

The specified Enterprise number could not be found, please make sure the enterprise number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `enterprise` item specified could not be found",
    "code": "-2"
}

/enterprise/{enterpriseNumber}/address

Retrieve a specific enterprise address by type.

Retrieve a specific address by the enterprise number and address type.

Arguments and parameters

Field

Type

Description
enterpriseNumber

integer

Number of the enterprise

Example: 0417497106

Response

Successful response | The specific address has been found.

Field

Type

Description
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 registration

Example: Kerkstraat
fr

string

French street translation of the registration

Example: Rue de l'Église
addressNumber

string

Address street number of the registration

Example: 1
addressAdditional

string

Additional address or street suffix

Example: Unit 12, Floor 5
postOfficeBox

string

The post office box of the address, if applicable

Example: Box 5
zipcode

string

Zipcode of the registration

Example: 2000
city

object

City of the registration
nl

string

Dutch city translation of the registration

Example: Brussel
fr

string

French city translation of the registration

Example: 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 country

Example: Frankrijk
fr

string

French translation of the country

Example: France
en

string

English translation of the country

Example: France
de

string

German translation of the country
dateRevoke

string
dateStart

string

Example: 2020-01-01

Example

`200` Successful response

The specific address has been found.

Response (example) Request Response (headers)

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

The specified Enterprise number could not be found, please make sure the enterprise number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `enterprise` item specified could not be found",
    "code": "-2"
}

/enterprise/{enterpriseNumber}/contact

Large plan

Retrieve contact information of the enterprise.

Retrieve contact information of the enterprise (phone numbers, email addresses and websites). Please note that companies aren't required to provide these details, so not all enterprises have contact information available.

Arguments and parameters

Field

Type

Description
enterpriseNumber

integer

Number of the enterprise

Example: 0417497106

Response

Succesful response | All contact information of the enterprise.

Field

Type

Description
[]

array
Contact

object
enterpriseNumber

string

Example: 0417497106
enterpriseNumberFormatted

string

Example: 0417.497.106
typeCode

string

The type of contact information

Possible 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 the typeCode.

Example: 0032123456789

Example

`200` Succesful response

All contact information of the enterprise.

Response (example) Request Response (headers)

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

The specified Enterprise number could not be found, please make sure the enterprise number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `enterprise` item specified could not be found",
    "code": "-2"
}

`402` Larger plan required

The endpoint (or a parameter that is present), is only accessible for a specific plan. Please verify the request which plan is required and upgrade accordingly.

{
    "exception": "PlanScopeException",
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "code": "-31"
}

/enterprise/{enterpriseNumber}/denominations

Retrieve all enterprise denominations.

Retrieve all the denominations (business names and trade names) by the enterprise number.

Arguments and parameters

Field

Type

Description
enterpriseNumber

integer

Number of the enterprise

Example: 0417497106

Response

Successful response | All denominations from the enterprise.

Field

Type

Description
[]

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 name

Example: FaimMedia B.V.
type

string

The denomination type

Possible values: social abbreviation commercial

Example: social
typeDescription

object
nl

string

Dutch translation of the type description

Example: Maatschappelijke naam
en

string

English translation of the type description

Example: Primary name
fr

string

French translation of the type description

Example: Dénomination sociale
de

string

German translation of the type description

Example: Primärname

Example

`200` Successful response

All denominations from the enterprise.

Response (example) Request Response (headers)

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

The specified Enterprise number could not be found, please make sure the enterprise number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `enterprise` item specified could not be found",
    "code": "-2"
}

/enterprise/{enterpriseNumber}/denomination/{language}/{type}

Retrieve a specific enterprise denomination.

Retrieve a specific type of denomination (business names and trade names) by the enterprise number and language.

Arguments and parameters

Field

Type

Description
enterpriseNumber

integer

Number of the enterprise

Example: 0417497106
language

string

The language code of the denomination. Some denominations may not have the language specified, use the unknown 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.

Field

Type

Description
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 name

Example: FaimMedia B.V.
type

string

The denomination type

Possible values: social abbreviation commercial

Example: social
typeDescription

object
nl

string

Dutch translation of the type description

Example: Maatschappelijke naam
en

string

English translation of the type description

Example: Primary name
fr

string

French translation of the type description

Example: Dénomination sociale
de

string

German translation of the type description

Example: Primärname

Example

`200` Successful response

The denomination has been found.

Response (example) Request Response (headers)

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

The specified Enterprise number could not be found, please make sure the enterprise number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `enterprise` item specified could not be found",
    "code": "-2"
}

/enterprise/{enterpriseNumber}/establishments

Retrieve all enterprise establishments.

Retrieve all the establishments registered for this enterprise.

Arguments and parameters

Field

Type

Description
enterpriseNumber

integer

Number of the enterprise

Example: 0417497106
active Large plan

string

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.

Field

Type

Description
[]

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 inactive

Example: 1
dateStart

string

Example: 2020-01-01

Example

`200` Successful response

All establishments from the enterprise.

Response (example) Request Response (headers)

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

The parameter you are using, is only accessible for a larger plan. Please verify the request which plan is required and upgrade your plan or omit the parameter.

{
    "exception": "PlanScopeException",
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "parameter": "active",
    "code": "-31"
}

`404` Enterprise not found

The specified Enterprise number could not be found, please make sure the enterprise number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `enterprise` item specified could not be found",
    "code": "-2"
}

/enterprise/{enterpriseNumber}/financial

Large plan

Retrieve short financial information of the enterprise.

Retrieve short financial information of the enterprise, the following information is available:
- 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

Field

Type

Description
enterpriseNumber

integer

Number of the enterprise

Example: 0417497106

Response

Successful response | Financial information from the enterprise.

Field

Type

Description
EnterpriseFinancial

object
enterpriseNumber

string

Example: 0417497106
enterpriseNumberFormatted

string

Example: 0417.497.106
capitalValue

integer

Placed capital according to statutes

Example: 100000
capitalValuta

string

The valuta of the placed capital, while EUR is the most common, this value can be any ISO-4217 code. It's also common for companies founded before the introduction of the Euro to have historical valuta, in example: BEF, FRF and NLG. Most foreign companies have foreign valuta present.

Please visit wikipedia for an up-to-date ISO-4217 list of:
- Active currency codes
- Historic currency codes

Example: 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 as 0000.

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

Financial information from the enterprise.

Response (example) Request Response (headers)

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

Retrieve NSSO (RSZ, LSS, ONSS) details of the enterprise.

Retrieve NSSO details of the enterprise.

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

Field

Type

Description
enterpriseNumber

integer

Number of the enterprise

Example: 0417497106

Response

Successful response | NSSO information from the enterprise.

Field

Type

Description
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 company

Example: 154857201
nssoNumberFormatted

string

The formatted NSSO-number with a dash of the company

Example: 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 date

Example: 2024-02-01
periods

array

Overview of employee periods
dateStart

string

Start date of the employee period

Example: 2024-03-02
importanceCodes

array
dateStart

string

Start date of the employee importance code

Example: 2024-04-02
code

object

Code identifier

Possible 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 identifier

Example: 1 tot 4 werknemers
fr

string

French description of the code identifier

Example: 1 à 4 travailleurs
de

string

German description of the code identifier

Example: 1 bis 4 Arbeitnehmer
en

string

English description of the code identifier

Example: 1 until 4 employees

Example

`200` Successful response

NSSO information from the enterprise.

Response (example) Request Response (headers)

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

The endpoint (or a parameter that is present), is only accessible for a specific plan. Please verify the request which plan is required and upgrade accordingly.

{
    "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

Retrieve all official functions of the enterprise.

Retrieve all the official funtions registered for this enterprise (board of directors).

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

Field

Type

Description
enterpriseNumber

integer

Number of the enterprise

Example: 0417497106

Response

Successful response | All functions from the enterprise.

Field

Type

Description
[]

array
EnterpriseRole

object
enterpriseNumber

string

Example: 0417497106
enterpriseNumberFormatted

string

Example: 0417.497.106
nameFirst

string

First name of the board member

Example: Frans
nameLast

string

Last name of the board member

Example: Vanderbeek
parentEnterpriseNumber

string

The enterprise number of which the role is inherited from. If the nameLast and nameFirst 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 registered

Example: 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 Dutch

Example: Zaakvoerder
en

string

Function title in English

Example: Manager
fr

string

Function title in French

Example: Gérant
de

string

Function title in German

Example: Geschäftsführer
note

object

Possible note regarding function title
nl

string

Possible note regarding function title in Dutch

Example: 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 English

Example: 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 French

Example: 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 German

Example: Gemäß dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff "Geschäftsführer" seit dem 1. Januar 2020 als "Verwalter" zu lesen.

Example

`200` Successful response

All functions from the enterprise.

Response (example) Request Response (headers)

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

The specified Enterprise number could not be found, please make sure the enterprise number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `enterprise` item specified could not be found",
    "code": "-2"
}

`402` Larger plan required

The endpoint (or a parameter that is present), is only accessible for a specific plan. Please verify the request which plan is required and upgrade accordingly.

{
    "exception": "PlanScopeException",
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "code": "-31"
}

/establishment/{establishmentNumber}

Retrieve establishment details.

Retrieve the establishment details by the establishment number.

Arguments and parameters

Field

Type

Description
establishmentNumber

integer

Number of the establishment

Example: 2147197839

Response

Successful response | The establishment has been found.

Field

Type

Description
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 inactive

Example: 1
dateStart

string

Example: 2020-01-01

Example

`200` Successful response

The establishment has been found.

Response (example) Request Response (headers)

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

The specified Establishment number could not be found, please make sure the establishment number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `establishment` item specified could not be found",
    "code": "-2"
}

/establishment/{establishmentNumber}/activities

Retrieve all establishment activities.

Retrieve all activities by the establishment number.

Arguments and parameters

Field

Type

Description
establishmentNumber

integer

Number of the establishment

Example: 2147197839

Response

Successful response | All activities from the establishment.

Field

Type

Description
[]

array
Activity

object
activityGroup

string

Possible values: BTW001 EDR001 OLK001 POR001 PPO001 RSZ001 SCO001

Example: BTW001
activityGroupDescription

object
nl

string

Dutch description

Example: BTW-activiteiten
fr

string

French description

Example: Activités TVA
en

string

English description

Example: VAT activities
de

string

German description

Example: MwSt.-Aktivitäten
classification

string

Possible values: ANCI MAIN SECO

Example: MAIN
classificationDescription

object
nl

string

Dutch description

Example: Hoofdactiviteit
fr

string

French description

Example: Activité principale
en

string

English description

Example: Main activity
de

string

German description

Example: Hauptaktivität
Nace

object
naceVersion

integer

Example: 2008
naceCode

string

Example: 474
description

object
nl

string

Dutch description

Example: Detailhandel in ICT-apparatuur in gespecialiseerde winkels
fr

string

French description

Example: Commerce de détail d'équipements de l'information et de la communication en magasin spécialisé
de

string

German description

Example: Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)
en

string

English description

Example: Retail sale of information and communication equipment in specialised stores

Example

`200` Successful response

All activities from the establishment.

Response (example) Request Response (headers)

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

The specified Establishment number could not be found, please make sure the establishment number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `establishment` item specified could not be found",
    "code": "-2"
}

/establishment/{establishmentNumber}/address

Retrieve the address of the establishment address.

Retrieve the address of the establishment.

Arguments and parameters

Field

Type

Description
establishmentNumber

integer

Number of the establishment

Example: 2147197839

Response

Successful response | The specific address has been found.

Field

Type

Description
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 registration

Example: Kerkstraat
fr

string

French street translation of the registration

Example: Rue de l'Église
addressNumber

string

Address street number of the registration

Example: 1
addressAdditional

string

Additional address or street suffix

Example: Unit 12, Floor 5
postOfficeBox

string

The post office box of the address, if applicable

Example: Box 5
zipcode

string

Zipcode of the registration

Example: 2000
city

object

City of the registration
nl

string

Dutch city translation of the registration

Example: Brussel
fr

string

French city translation of the registration

Example: 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 country

Example: Frankrijk
fr

string

French translation of the country

Example: France
en

string

English translation of the country

Example: France
de

string

German translation of the country
dateRevoke

string
dateStart

string

Example: 2020-01-01

Example

`200` Successful response

The specific address has been found.

Response (example) Request Response (headers)

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

The specified Establishment number could not be found, please make sure the establishment number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `establishment` item specified could not be found",
    "code": "-2"
}

/establishment/{establishmentNumber}/contact

Large plan

Retrieve contact information of the establishment.

Retrieve contact information of the establishment (phone numbers, email addresses and websites). Please note that companies aren't required to provide these details, so not all establishment have contact information available.

Arguments and parameters

Field

Type

Description
establishmentNumber

integer

Number of the establishment

Example: 2147197839

Response

Succesful response | All contact information of the establishment.

Field

Type

Description
[]

array
Contact

object
enterpriseNumber

string

Example: 0417497106
enterpriseNumberFormatted

string

Example: 0417.497.106
typeCode

string

The type of contact information

Possible 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 the typeCode.

Example: 0032123456789

Example

`200` Succesful response

All contact information of the establishment.

Response (example) Request Response (headers)

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

The specified Establishment number could not be found, please make sure the establishment number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `establishment` item specified could not be found",
    "code": "-2"
}

`402` Larger plan required

The endpoint (or a parameter that is present), is only accessible for a specific plan. Please verify the request which plan is required and upgrade accordingly.

{
    "exception": "PlanScopeException",
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "code": "-31"
}

/establishment/{establishmentNumber}/denominations

Retrieve all establishment denominations.

Retrieve all the denominations (business names and trade names) by the establishment number.

Arguments and parameters

Field

Type

Description
establishmentNumber

integer

Number of the establishment

Example: 2147197839

Response

Successful response | All denominations from the establishment.

Field

Type

Description
[]

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 name

Example: FaimMedia B.V.
type

string

The denomination type

Possible values: social abbreviation commercial

Example: social
typeDescription

object
nl

string

Dutch translation of the type description

Example: Maatschappelijke naam
en

string

English translation of the type description

Example: Primary name
fr

string

French translation of the type description

Example: Dénomination sociale
de

string

German translation of the type description

Example: Primärname

Example

`200` Successful response

All denominations from the establishment.

Response (example) Request Response (headers)

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

The specified Establishment number could not be found, please make sure the establishment number is valid and correct.

{
    "exception": "RequestException",
    "error": "The `establishment` item specified could not be found",
    "code": "-2"
}

/establishment/{establishmentNumber}/denomination/{language}

Retrieve a specific establishment denomination.

Retrieve a language specific establishment name by the establishment number and language.

Arguments and parameters

Field

Type

Description
establishmentNumber

integer

Number of the establishment

Example: 2147197839
language

string

The language code of the denomination. Some denominations may not have the language specified, use the unknown value in this case.

Possible values: unknown nl en fr de

Example: nl

Response

Successful response | The denomination has been found.

Field

Type

Description
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 name

Example: FaimMedia B.V.
type

string

The denomination type

Possible values: social abbreviation commercial

Example: social
typeDescription

object
nl

string

Dutch translation of the type description

Example: Maatschappelijke naam
en

string

English translation of the type description

Example: Primary name
fr

string

French translation of the type description

Example: Dénomination sociale
de

string

German translation of the type description

Example: Primärname

Example

`200` Successful response

The denomination has been found.

Response (example) Request Response (headers)

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

The item or resource specified could not be found

{
    "exception": "RequestException",
    "error": "The item specified could not be found",
    "code": "-2"
}

/denominations

Search request

Autocomplete company names (denominations)

Search for denominations (trade name) by using keywords. 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 and parameters

Field

Type

Description
query

string

The keywords to search for the denominations.

Example: AB Inbev
entityType

string

Accepted values: enterprise: show only enterprises, establishment: show only establishments

Possible values: enterprise establishment

Example: enterprise
type

string

Filter on the type of denomination.

Possible values: social abbreviation commercial

Example: commercial
active Large plan

string

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 fields

Possible values: nl fr en de

Example: nl
page

integer

The page of the results that should be returned

Example: 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.

Field

Type

Description
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 name

Example: FaimMedia B.V.
type

string

The denomination type

Possible values: social abbreviation commercial

Example: social
typeDescription

object
nl

string

Dutch translation of the type description

Example: Maatschappelijke naam
en

string

English translation of the type description

Example: Primary name
fr

string

French translation of the type description

Example: Dénomination sociale
de

string

German translation of the type description

Example: Primärname
Pagination

object
limit

integer

The used pagination limit, by default the maximum limit allowed by your plan

Example: 10
page

integer

The current page

Example: 1
totalPages

integer

The number of pages

Example: 99
totalItems

integer

The total number of items in the source data

Example: 1234
countItems

integer

The number of items in the current request

Example: 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

All denominations matching the provided search criteria.

Response (example) Request Response (headers)

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

The parameter you are using, is only accessible for a larger plan. Please verify the request which plan is required and upgrade your plan or omit the parameter.

{
    "exception": "PlanScopeException",
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "parameter": "active",
    "code": "-31"
}

/addresses

Search request

Search for multiple addresses.

Search for multiple addresses by query parameter.

Arguments and parameters

Field

Type

Description
query

string

Search query

Example: Grote Markt
entityType

string

Filter for a specific entity type

Possible values: enterprise establishment

Example: enterprise
active Large plan

string

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 field
- zipcode: Search in the zipcode field
- city: Search in the city field
- country: Search in the country field
filter.zipCodeExact Large plan

string

Filter for exact zipcode match
filter.streetNumberExact Large plan

string

Filter for exact street number match
page

integer

The page of the results that should be returned

Example: 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.

Field

Type

Description
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 registration

Example: Kerkstraat
fr

string

French street translation of the registration

Example: Rue de l'Église
addressNumber

string

Address street number of the registration

Example: 1
addressAdditional

string

Additional address or street suffix

Example: Unit 12, Floor 5
postOfficeBox

string

The post office box of the address, if applicable

Example: Box 5
zipcode

string

Zipcode of the registration

Example: 2000
city

object

City of the registration
nl

string

Dutch city translation of the registration

Example: Brussel
fr

string

French city translation of the registration

Example: 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 country

Example: Frankrijk
fr

string

French translation of the country

Example: France
en

string

English translation of the country

Example: 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 plan

Example: 10
page

integer

The current page

Example: 1
totalPages

integer

The number of pages

Example: 99
totalItems

integer

The total number of items in the source data

Example: 1234
countItems

integer

The number of items in the current request

Example: 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

All addresses matching the provided search criteria.

Response (example) Request Response (headers)

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

The parameter you are using, is only accessible for a larger plan. Please verify the request which plan is required and upgrade your plan or omit the parameter.

{
    "exception": "PlanScopeException",
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "parameter": "active",
    "code": "-31"
}

/naces

Search request

Search for nace code

Arguments and parameters

Field

Type

Description
query

string

Search query

Example: 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 returned

Example: 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.

Field

Type

Description
Naces

array
Nace

object
naceVersion

integer

Example: 2008
naceCode

string

Example: 474
description

object
nl

string

Dutch description

Example: Detailhandel in ICT-apparatuur in gespecialiseerde winkels
fr

string

French description

Example: Commerce de détail d'équipements de l'information et de la communication en magasin spécialisé
de

string

German description

Example: Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)
en

string

English description

Example: 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 plan

Example: 10
page

integer

The current page

Example: 1
totalPages

integer

The number of pages

Example: 99
totalItems

integer

The total number of items in the source data

Example: 1234
countItems

integer

The number of items in the current request

Example: 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

All NACEs matching the provided search criteria.

Response (example) Request Response (headers)

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}

Get NACE by version and code

Arguments and parameters

Field

Type

Description
naceVersion

integer

NACE version

Example: 2003
naceCode

string

NACE code

Example: 01

Response

Successful response, NACE is found.

Field

Type

Description
Nace

object
naceVersion

integer

Example: 2008
naceCode

string

Example: 474
description

object
nl

string

Dutch description

Example: Detailhandel in ICT-apparatuur in gespecialiseerde winkels
fr

string

French description

Example: Commerce de détail d'équipements de l'information et de la communication en magasin spécialisé
de

string

German description

Example: Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)
en

string

English description

Example: Retail sale of information and communication equipment in specialised stores

Example

`200` Successful response, NACE is found.

Response (example) Request Response (headers)

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

Search for a role code (function title)

Arguments and parameters

Field

Type

Description
query

string

Search query, will search for a partial role title

Example: 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 returned

Example: 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

Field

Type

Description
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 Dutch

Example: Zaakvoerder
en

string

Function title in English

Example: Manager
fr

string

Function title in French

Example: Gérant
de

string

Function title in German

Example: Geschäftsführer
note

object

Possible note regarding function title
nl

string

Possible note regarding function title in Dutch

Example: 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 English

Example: 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 French

Example: 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 German

Example: 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 plan

Example: 10
page

integer

The current page

Example: 1
totalPages

integer

The number of pages

Example: 99
totalItems

integer

The total number of items in the source data

Example: 1234
countItems

integer

The number of items in the current request

Example: 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

All function titles returned

Response (example) Request Response (headers)

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

The endpoint (or a parameter that is present), is only accessible for a specific plan. Please verify the request which plan is required and upgrade accordingly.

{
    "exception": "PlanScopeException",
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "code": "-31"
}

/role/{roleCode}

Large plan

Get a specific function title by code

Arguments and parameters

Field

Type

Description
roleCode

integer

The role code

Example: 5

Response

Successful response | Function title is returned

Field

Type

Description
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 Dutch

Example: Zaakvoerder
en

string

Function title in English

Example: Manager
fr

string

Function title in French

Example: Gérant
de

string

Function title in German

Example: Geschäftsführer
note

object

Possible note regarding function title
nl

string

Possible note regarding function title in Dutch

Example: 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 English

Example: 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 French

Example: 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 German

Example: Gemäß dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff "Geschäftsführer" seit dem 1. Januar 2020 als "Verwalter" zu lesen.

Example

`200` Successful response

Function title is returned

Response (example) Request Response (headers)

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

The endpoint (or a parameter that is present), is only accessible for a specific plan. Please verify the request which plan is required and upgrade accordingly.

{
    "exception": "PlanScopeException",
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "code": "-31"
}

`404` Item or resource not found

The item or resource specified could not be found

{
    "exception": "RequestException",
    "error": "The item specified could not be found",
    "code": "-2"
}

/juridical-forms

Large plan Search request

Search for a juridical form

Arguments and parameters

Field

Type

Description
query

string

Search query, will search for a (partial) juridical form

Example: 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 returned

Example: 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.

Field

Type

Description
JuridicalForms

array
JuridicalForm

object
juridicalFormCode

string

Juridical Form code

Example: 030
description

object
nl

string

Dutch description of the juridical form

Example: Buitenlandse entiteit
fr

string

French description of the juridical form

Example: Entité étrangère
de

string

German description of the juridical form

Example: Ausländische Einheit
Pagination

object
limit

integer

The used pagination limit, by default the maximum limit allowed by your plan

Example: 10
page

integer

The current page

Example: 1
totalPages

integer

The number of pages

Example: 99
totalItems

integer

The total number of items in the source data

Example: 1234
countItems

integer

The number of items in the current request

Example: 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

All juridical forms matching your search criteria are returned.

Response (example) Request Response (headers)

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

The endpoint (or a parameter that is present), is only accessible for a specific plan. Please verify the request which plan is required and upgrade accordingly.

{
    "exception": "PlanScopeException",
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "code": "-31"
}

/juridical-situations

Large plan Search request

Search for a juridical situation

Arguments and parameters

Field

Type

Description
query

string

Search query, will search for a (partial) juridical situation

Example: 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 returned

Example: 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.

Field

Type

Description
JuridicalSituations

array
JuridicalSituation

object
juridicalSituationCode

string

Juridical Situation code

Example: 000
description

object
nl

string

Dutch description of the juridical situation

Example: Normale toestand
fr

string

French description of the juridical situation

Example: Situation normale
de

string

German description of the juridical situation

Example: Gewöhnlicher Zustand
Pagination

object
limit

integer

The used pagination limit, by default the maximum limit allowed by your plan

Example: 10
page

integer

The current page

Example: 1
totalPages

integer

The number of pages

Example: 99
totalItems

integer

The total number of items in the source data

Example: 1234
countItems

integer

The number of items in the current request

Example: 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

All juridical situations matching your search criteria are returned.

Response (example) Request Response (headers)

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

The endpoint (or a parameter that is present), is only accessible for a specific plan. Please verify the request which plan is required and upgrade accordingly.

{
    "exception": "PlanScopeException",
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "code": "-31"
}

/vat/{vatNumber}

Verify VAT-number or enterprise number for internation transactions within the EU

Please note: we use an external service for validating VAT-numbers this may not always be available.
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

Field

Type

Description
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 number

Example: 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.

Field

Type

Description
vatNumber

string

The validated VAT-number

Example: BE0417497106
isValid

boolean

Boolean if provided VAT-number is valid

Example: 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

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.

Response (example) Request Response (headers)

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

The item or resource specified could not be found

{
    "exception": "RequestException",
    "error": "The item specified could not be found",
    "code": "-2"
}

`500` Service for VAT-validation is not available.

/me

Get authorized customer information

Response

Success response | The provided authorization token is valid.

Field

Type

Description
Customer

object
name

string

The username of the authorized customer

Example: My Company Ltd.
planName

string

Active plan name

Example: Small
dateCreated

string

The date the customer is created

Example: 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 token

Example: Development-token
dateCreated

string

Example: 2020-02-02 02:02:02
dateExpiration

string

Example: 2021-02-02 02:02:02

Example

`200` Success response

The provided authorization token is valid.

Response (example) Request Response (headers)

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

API documentation

Intro

What's an API?

What's an REST API?

Requests

API-token

Authorization

200 Success response

Pagination

Response

Headers

Example (headers)

Description

Endpoints

Endpoints overview

Enterprises

Retrieve enterprise details.

Retrieve all enterprise activities.

Retrieve a specific enterprise address by type.

Retrieve contact information of the enterprise.

Retrieve all enterprise denominations.

Retrieve a specific enterprise denomination.

Retrieve all enterprise establishments.

Retrieve short financial information of the enterprise.

Retrieve NSSO (RSZ, LSS, ONSS) details of the enterprise.

Retrieve all official functions of the enterprise.

Establishments

Retrieve establishment details.

Retrieve all establishment activities.

Retrieve the address of the establishment address.

Retrieve contact information of the establishment.

Retrieve all establishment denominations.

Retrieve a specific establishment denomination.

Denominations

Autocomplete company names (denominations)

Addresses

Search for multiple addresses.

Nace

Search for nace code

Get NACE by version and code

Roles

Search for a role code (function title)

Get a specific function title by code

Juridical

Search for a juridical form

Search for a juridical situation

VAT

Verify VAT-number or enterprise number for internation transactions within the EU

Customer

Get authorized customer information

/enterprise/{enterpriseNumber}

Arguments and parameters

Response

Example

200 Successful response

404 Enterprise not found

/enterprise/{enterpriseNumber}/activities

Arguments and parameters

Response

Example

200 Successful response

404 Enterprise not found

/enterprise/{enterpriseNumber}/address

Arguments and parameters

Response

Example

200 Successful response

404 Enterprise not found

/enterprise/{enterpriseNumber}/contact Large plan

Arguments and parameters

Response

Example

200 Succesful response

404 Enterprise not found

402 Larger plan required

/enterprise/{enterpriseNumber}/denominations

Arguments and parameters

Response

Example

200 Successful response

`200` Success response

`200` Successful response

`404` Enterprise not found

`200` Successful response

`404` Enterprise not found

`200` Successful response

`404` Enterprise not found

/enterprise/{enterpriseNumber}/contact

Large plan

`200` Succesful response

`404` Enterprise not found

`402` Larger plan required

`200` Successful response

`404` Enterprise not found

`200` Successful response

`404` Enterprise not found

`200` Successful response

`402` Larger plan required for this parameter

`404` Enterprise not found

/enterprise/{enterpriseNumber}/financial

Large plan

`200` Successful response

/enterprise/{enterpriseNumber}/nsso

New! Medium plan

`200` Successful response

`402` Larger plan required

`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

`200` Successful response

`404` Enterprise not found

`402` Larger plan required

`200` Successful response

`404` Establishment not found

`200` Successful response

`404` Establishment not found

`200` Successful response

`404` Establishment not found

/establishment/{establishmentNumber}/contact

Large plan

`200` Succesful response

`404` Establishment not found

`402` Larger plan required

`200` Successful response

`404` Establishment not found