Wij kunnen de website tonen in een taal die waarschijnlijk meer overeenkomt met uw taal instellingen
We can display the website in a language that is more likely to match your language settings
Nous pouvons afficher le site dans une langue qui est plus susceptible de correspondre à vos paramètres linguistiques
Wir können die Website in einer Sprache anzeigen, die eher geeignet ist für Ihre Spracheinstellungen.
You are using a outdated browser, not all functionalities on this website may work properly. For the best user experience, it is recommended to upgrade your browser.

API documentation

2.4

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.
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"
    },
    "ApiAccessToken": {
        "isDevelopment": false,
        "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
  • limit
    integer
    The used pagination limit, by default the maximum limit allowed by your plan
  • page
    integer
    The current page
  • totalPages
    integer
    The number of pages
  • totalItems
    integer
    The total number of items in the source data
  • countItems
    integer
    The number of items in the current request
  • 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.

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)

X-API-Key-Type: production
X-API-Request-Count: 124
X-API-Request-Limit: 1000
X-API-Search-Request-Count: 794
X-API-Search-Request-Limit: 1000

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
  • X-API-Key-Type
    string
    The type of the used API-key. `development` for a development-key and `production` regarding a production key.
  • X-API-Request-Count
    integer
    The request count usage of the current period, excluding the current request.
  • X-API-Request-Limit
    integer
    The maximum allowed requests per period.
  • X-API-Search-Request-Count
    integer
    The maximum allowed search requests per period.
  • X-API-Search-Request-Limit
    integer
    The request search count usage of the current period, excluding the current request.

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
    Environment
    Description
  • https://api.kbodata.app/v2/
    production
    KBO API (production key)
  • https://mock.api.kbodata.app/v2/
    development
    KBO Mock API (development key)

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.

Enterprise Denominations Enterprise/Addresses Enterprise/Activities Activities Activities Juridical forms Juridical situations Establishments Establishment/Denominations Establishment/Addresses Establishment/Activities Establishment/Activities Establishment/Activities

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

/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
  • active
    boolean
    Whether the registration status of the enterprise is active or inactive. This field will also be false if the enterprise is in a pre-registration state.
    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.
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",
        "active": true,
        "type": "entity",
        "typeDescription": {
            "nl": "Rechtspersoon",
            "en": "Legal entity",
            "fr": "Personne morale",
            "de": "Juristische Person"
        },
        "JuridicalForm": {
            "juridicalFormCode": "030",
            "description": {
                "nl": "Buitenlandse entiteit",
                "fr": "Entité étrangère",
                "de": "Ausländische Einheit"
            }
        },
        "JuridicalSituation": {
            "juridicalSituationCode": "000",
            "description": {
                "nl": "Normale toestand",
                "fr": "Situation normale",
                "de": "Gewöhnlicher 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.
{
    "error": "The `enterprise` item specified could not be found",
    "type": "RequestException",
    "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.
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és TVA",
                "en": "VAT activities",
                "de": "MwSt.-Aktivitäten"
            },
            "classification": "MAIN",
            "classificationDescription": {
                "nl": "Hoofdactiviteit",
                "fr": "Activité principale",
                "en": "Main activity",
                "de": "Hauptaktivität"
            },
            "Nace": {
                "naceVersion": 2008,
                "naceCode": "474",
                "description": {
                    "nl": "Detailhandel in ICT-apparatuur in gespecialiseerde winkels",
                    "fr": "Commerce de détail d'équipements de l'information et de la communication en magasin spécialisé",
                    "de": "Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)",
                    "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.
{
    "error": "The `enterprise` item specified could not be found",
    "type": "RequestException",
    "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.
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ège social",
            "de": "Sitzes Adresse"
        },
        "street": {
            "nl": "Kerkstraat",
            "fr": "Rue de l'Église"
        },
        "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.
{
    "error": "The `enterprise` item specified could not be found",
    "type": "RequestException",
    "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.
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.
{
    "error": "The `enterprise` item specified could not be found",
    "type": "RequestException",
    "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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "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.
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énomination sociale",
                "de": "Primärname"
            }
        }
    }
]
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.
{
    "error": "The `enterprise` item specified could not be found",
    "type": "RequestException",
    "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.
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énomination sociale",
            "de": "Primärname"
        }
    }
}
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.
{
    "error": "The `enterprise` item specified could not be found",
    "type": "RequestException",
    "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. This field will also be false if the establishment is in a pre-registration state.
    Example: 1
  • dateStart
    string
    Example: 2020-01-01

Example

200 Successful response

All establishments from the enterprise.
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": true,
            "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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "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.
{
    "error": "The `enterprise` item specified could not be found",
    "type": "RequestException",
    "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.
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.
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é",
                    "fr": "Privé",
                    "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 à 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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "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.
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érant",
                    "de": "Geschäftsführer"
                },
                "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étés et des associations, le terme \"Gérant\" doit, depuis le 1er janvier 2020, être lu comme étant \"Administrateur\".\n",
                    "de": "Gemäß dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff \"Geschäftsführer\" 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.
{
    "error": "The `enterprise` item specified could not be found",
    "type": "RequestException",
    "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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "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. This field will also be false if the establishment is in a pre-registration state.
    Example: 1
  • dateStart
    string
    Example: 2020-01-01

Example

200 Successful response

The establishment has been found.
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": true,
        "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.
{
    "error": "The `establishment` item specified could not be found",
    "type": "RequestException",
    "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.
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és TVA",
                "en": "VAT activities",
                "de": "MwSt.-Aktivitäten"
            },
            "classification": "MAIN",
            "classificationDescription": {
                "nl": "Hoofdactiviteit",
                "fr": "Activité principale",
                "en": "Main activity",
                "de": "Hauptaktivität"
            },
            "Nace": {
                "naceVersion": 2008,
                "naceCode": "474",
                "description": {
                    "nl": "Detailhandel in ICT-apparatuur in gespecialiseerde winkels",
                    "fr": "Commerce de détail d'équipements de l'information et de la communication en magasin spécialisé",
                    "de": "Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)",
                    "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.
{
    "error": "The `establishment` item specified could not be found",
    "type": "RequestException",
    "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.
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ège social",
            "de": "Sitzes Adresse"
        },
        "street": {
            "nl": "Kerkstraat",
            "fr": "Rue de l'Église"
        },
        "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.
{
    "error": "The `establishment` item specified could not be found",
    "type": "RequestException",
    "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.
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.
{
    "error": "The `establishment` item specified could not be found",
    "type": "RequestException",
    "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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "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.
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énomination sociale",
                "de": "Primärname"
            }
        }
    }
]
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.
{
    "error": "The `establishment` item specified could not be found",
    "type": "RequestException",
    "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.
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énomination sociale",
            "de": "Primärname"
        }
    }
}
HTTP/1.1 200 OK

404 Item or resource not found

The item or resource specified could not be found
{
    "type": "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.
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énomination sociale",
                    "de": "Primärname"
                }
            }
        }
    ],
    "Pagination": {
        "limit": 10,
        "page": 1,
        "totalPages": 99,
        "totalItems": 1234,
        "countItems": 8,
        "estimate": true
    }
}
HTTP/1.1 200 OK

422 Invalid response, missing or incorrect parameter 

{
    "type": "RequestException",
    "error": "Missing `query` parameter",
    "code": -3
}

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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "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

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.
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ège social",
                    "de": "Sitzes Adresse"
                },
                "street": {
                    "nl": "Kerkstraat",
                    "fr": "Rue de l'Église"
                },
                "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": true
    }
}
HTTP/1.1 200 OK

422 Invalid response, missing or incorrect parameter 

{
    "type": "RequestException",
    "error": "Missing `query` parameter",
    "code": -3
}

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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "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.
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étail d'équipements de l'information et de la communication en magasin spécialisé",
                    "de": "Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)",
                    "en": "Retail sale of information and communication equipment in specialised stores"
                }
            }
        }
    ],
    "Pagination": {
        "limit": 10,
        "page": 1,
        "totalPages": 99,
        "totalItems": 1234,
        "countItems": 8,
        "estimate": true
    }
}
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. 

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étail d'équipements de l'information et de la communication en magasin spécialisé",
            "de": "Einzelhandel mit Geräten der Informations- und Kommunikationstechnik (in Verkaufsräumen)",
            "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
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érant",
                    "de": "Geschäftsführer"
                },
                "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étés et des associations, le terme \"Gérant\" doit, depuis le 1er janvier 2020, être lu comme étant \"Administrateur\".\n",
                    "de": "Gemäß dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff \"Geschäftsführer\" seit dem 1. Januar 2020 als \"Verwalter\" zu lesen.\n"
                }
            }
        }
    ],
    "Pagination": {
        "limit": 10,
        "page": 1,
        "totalPages": 99,
        "totalItems": 1234,
        "countItems": 8,
        "estimate": true
    }
}
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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "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
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érant",
            "de": "Geschäftsführer"
        },
        "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étés et des associations, le terme \"Gérant\" doit, depuis le 1er janvier 2020, être lu comme étant \"Administrateur\".\n",
            "de": "Gemäß dem Gesellschafts- und Vereinigungsgesetzbuch ist der Begriff \"Geschäftsführer\" 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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "code": -31
}

404 Item or resource not found

The item or resource specified could not be found
{
    "type": "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.
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é étrangère",
                    "de": "Ausländische Einheit"
                }
            }
        }
    ],
    "Pagination": {
        "limit": 10,
        "page": 1,
        "totalPages": 99,
        "totalItems": 1234,
        "countItems": 8,
        "estimate": true
    }
}
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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "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.
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öhnlicher Zustand"
                }
            }
        }
    ],
    "Pagination": {
        "limit": 10,
        "page": 1,
        "totalPages": 99,
        "totalItems": 1234,
        "countItems": 8,
        "estimate": true
    }
}
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.
{
    "error": "Your active plan doesn't meet the requirements for this endpoint",
    "type": "PlanScopeException",
    "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.
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer tk9xkS0PrDpa1yxIT6WWwD204c3pgOe8fIpguPCeGGzZ2ufRU5F74lMW1ap111g7" \
https://api.kbodata.app/v2/vat/{vatNumber}
{
    "vatNumber": "BE0417497106",
    "isValid": true,
    "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
{
    "type": "RequestException",
    "error": "The item specified could not be found",
    "code": -2
}

500 Service for VAT-validation is not available.

/me

Get authorized customer information
Please note that this endpoint is rate limited to once per 60 seconds, if this is exceeded you'll receive a 429 response, and have to wait another 60 seconds before a valid response is returned.

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
  • 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.
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"
    },
    "ApiAccessToken": {
        "isDevelopment": false,
        "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 

{
    "error": "The provided access token is invalid",
    "type": "AuthorizationException",
    "code": -2
}

429 Too many requests

You have exceeded the rate limit for this endpoint. Consult the `Retry-After` response header after how many seconds you may retry the request again.
{
    "error": "You have exceeded the rate limit for this endpoint, try again in 60 seconds",
    "type": "HttpTooManyRequestsException",
    "code": 429
}

/health

Health check for the API
Check the health of the API, every 2xx status code should be considered healthy, and every 5xx status code should be considered unhealth.
Please note that this endpoint is rate limited to once per 60 seconds, if this is exceeded you'll receive a 429 response, and have to wait another 60 seconds before a valid response is returned.

Example

204 Success response

The API is healthy

500 The API in unhealthy

503 The API is unhealthy

429 Too many requests

You have exceeded the rate limit for this endpoint. Consult the `Retry-After` response header after how many seconds you may retry the request again.
{
    "error": "You have exceeded the rate limit for this endpoint, try again in 60 seconds",
    "type": "HttpTooManyRequestsException",
    "code": 429
}

405 Invalid method

Make sure the request is an OPTIONS method

/health/vat

Health check for the VAT endpoints
Check the health of the VAT endpoints, every 2xx status code should be considered healthy, and every 5xx status code should be considered unhealth.
Please note that this endpoint is rate limited to once per 60 seconds, if this is exceeded you'll receive a 429 response, and have to wait another 60 seconds before a valid response is returned.
Endpoints include:
- /vat/{vatNumber}

Example

204 Success response

The VAT endpoints are healthy.

500 The VAT service in unhealthy

503 The VAT service is unhealthy

429 Too many requests

You have exceeded the rate limit for this endpoint. Consult the `Retry-After` response header after how many seconds you may retry the request again.
{
    "error": "You have exceeded the rate limit for this endpoint, try again in 60 seconds",
    "type": "HttpTooManyRequestsException",
    "code": 429
}

405 Invalid method

Make sure the request is an OPTIONS method

/health/nsso

Health check for the NSSO endpoints
Check the health of the VAT endpoints, every 2xx status code should be considered healthy, and every 5xx status code should be considered unhealth.
Please note that this endpoint is rate limited to once per 60 seconds, if this is exceeded you'll receive a 429 response, and have to wait another 60 seconds before a valid response is returned.
Endpoints include:
- /enterprise/{enterpriseNumber}/nsso

Example

204 Success response

The NSSO endpoints are healthy

500 The NSSO service in unhealthy.

503 The NSSO service is unhealthy.

429 Too many requests

You have exceeded the rate limit for this endpoint. Consult the `Retry-After` response header after how many seconds you may retry the request again.
{
    "error": "You have exceeded the rate limit for this endpoint, try again in 60 seconds",
    "type": "HttpTooManyRequestsException",
    "code": 429
}

405 Invalid method

Make sure the request is an OPTIONS method

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.