{ "openapi": "3.0.0", "info": { "title": "CBE2JSON API", "description": "Official Belgian company data from the Crossroads Bank for Enterprises (CBE / BCE / KBO) as JSON.\n\n**Authentication.** Every endpoint is a `POST` with a JSON body holding your credentials and a `data` object: `{\"clientId\": \"…\", \"secretKey\": \"…\", \"data\": { … }}`. Generate a key in your dashboard.\n\n**Credits.** `byCBE` uses 1 credit per enterprise found; `byDenomination` and `/search` use 1 credit per enterprise returned; `/search/numbers` uses 1 credit per non-empty page of up to 1,000 numbers. Each is refused (400 `QUOTA_EXHAUSTED`, nothing charged) when it would exceed the credits left. Failed requests and empty results use no credits; `total` is always free. Every response to an identified key carries the credits in headers: `CBE2JSON-Credits-Used`, `CBE2JSON-Credits-Remaining`, `CBE2JSON-Credits-Limit` and `CBE2JSON-Credits-Reset` (the last three are left out when they do not apply).\n\n**Errors.** Check the HTTP status first. API errors return `{\"errorCode\": \"…\", \"message\": \"…\"}` with the status listed under each endpoint; other failures (malformed JSON, server errors) can return a different body.\n\n**Versions.** Each API key is pinned to a response format: version 1 is the original format; version 2 wraps every response in `{ \"data\": …, \"meta\": { … } }`, where `meta` gives the dataset date, the credits and, for searches, the page. Version 2 also caps `limit` at 100 for `byDenomination` and `/search` (1000 for `/search/numbers`) and answers an empty search with 200 and an empty list. New keys start on the latest version; switch a key in your dashboard. Send the `CBE2JSON-Version` header to use another version for one request; every response carries that header with the version used. Older versions stay supported for at least 12 months after a newer one ships.\n\n**Browser access (CORS).** By default an API key works from any website. In your dashboard you can restrict a key to a list of origins, or block browser access entirely. Origins are matched as globs: `https://app.example.com` matches exactly that origin; `https://*.example.com` matches `app.example.com` and `a.b.example.com` but **not** the bare `https://example.com`; `http://localhost:*` matches any local port. A request from a disallowed origin returns 403 `ORIGIN_NOT_ALLOWED` and consumes no quota.\n\nCORS is enforced by browsers only — a script, server or mobile app can still use the key, so keep your secret key secret.", "contact": { "name": "CBE2JSON", "email": "contact@cbe2json.be" }, "license": { "name": "proprietary license" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.cbe2json.be", "description": "CBE2JSON API server" } ], "components": { "enterprise": { "Description": { "type": "object", "description": "Readable text of a coded value: FR and NL, DE on some fields.", "properties": { "FR": { "type": "string" }, "NL": { "type": "string" }, "DE": { "type": "string" } } }, "Activity": { "type": "object", "properties": { "activityGroup": { "type": "string" }, "activityGroupDescription": { "$ref": "#/components/enterprise/Description" }, "naceVersion": { "type": "string" }, "naceCode": { "type": "string" }, "naceCodeDescription": { "$ref": "#/components/enterprise/Description" }, "classification": { "type": "string" }, "classificationDescription": { "$ref": "#/components/enterprise/Description" } } }, "Establishment": { "type": "object", "properties": { "establishmentNumber": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "denominations": { "type": "array", "items": { "$ref": "#/components/enterprise/Denomination" } }, "contacts": { "type": "array", "items": { "$ref": "#/components/enterprise/Contact" } }, "activities": { "type": "array", "items": { "$ref": "#/components/enterprise/Activity" } }, "addresses": { "type": "array", "items": { "$ref": "#/components/enterprise/Address" } } } }, "Denomination": { "type": "object", "properties": { "language": { "type": "number" }, "languageDescription": { "$ref": "#/components/enterprise/Description" }, "typeOfDenomination": { "type": "string" }, "typeOfDenominationDescription": { "$ref": "#/components/enterprise/Description" }, "denomination": { "type": "string" } } }, "Contact": { "type": "object", "properties": { "entityContact": { "type": "string" }, "entityContactDescription": { "$ref": "#/components/enterprise/Description" }, "contactType": { "type": "string" }, "contactTypeDescription": { "$ref": "#/components/enterprise/Description" }, "value": { "type": "string" } } }, "Address": { "type": "object", "properties": { "typeOfAddress": { "type": "string" }, "typeOfAddressDescription": { "$ref": "#/components/enterprise/Description" }, "countryNL": { "type": "string", "required": false }, "countryFR": { "type": "string", "required": false }, "zipcode": { "type": "string", "required": false }, "municipalityNL": { "type": "string", "required": false }, "municipalityFR": { "type": "string", "required": false }, "streetNL": { "type": "string", "required": false }, "streetFR": { "type": "string", "required": false }, "houseNumber": { "type": "string", "required": false }, "box": { "type": "string", "required": false }, "extraAddressInfo": { "type": "string", "required": false }, "dateStrikingOff": { "type": "string", "required": false } } }, "Enterprise": { "type": "object", "properties": { "enterpriseNumber": { "type": "string" }, "status": { "type": "string" }, "statusDescription": { "$ref": "#/components/enterprise/Description" }, "juridicalSituation": { "type": "string" }, "juridicalSituationDescription": { "$ref": "#/components/enterprise/Description" }, "typeOfEnterprise": { "type": "integer", "description": "1 = natural person, 2 = legal person.", "example": 2 }, "typeOfEnterpriseDescription": { "$ref": "#/components/enterprise/Description" }, "juridicalForm": { "type": "number", "required": false }, "juridicalFormDescription": { "$ref": "#/components/enterprise/Description", "required": false }, "startDate": { "type": "string", "format": "date-time" }, "activities": { "type": "array", "items": { "$ref": "#/components/enterprise/Activity" } }, "establishments": { "type": "array", "items": { "$ref": "#/components/enterprise/Establishment" } }, "denominations": { "type": "array", "items": { "$ref": "#/components/enterprise/Denomination" } }, "contacts": { "type": "array", "items": { "$ref": "#/components/enterprise/Contact" } }, "addresses": { "type": "array", "items": { "$ref": "#/components/enterprise/Address" } } } } }, "versionHeader": { "in": "header", "name": "CBE2JSON-Version", "required": false, "description": "Response version for this request only (1 or 2). Omit it to use the version your API key is pinned to.", "schema": { "type": "integer", "enum": [ 1, 2 ] } }, "commonError": { "badRequestResponse": { "description": "`VALIDATION_FAILED`: the body is malformed (a missing or unknown field, or an invalid enterprise number). `QUOTA_EXHAUSTED`: your credits for this month are used up, or the request would return more results than the credits left (lower data.limit); nothing is charged. `UNSUPPORTED_API_VERSION`: the CBE2JSON-Version header names a version that does not exist. Version 2: `VALIDATION_FAILED` also when data.limit is above 100.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorCode": { "type": "string", "enum": [ "VALIDATION_FAILED", "QUOTA_EXHAUSTED", "UNSUPPORTED_API_VERSION" ] }, "message": { "type": "string", "example": "Your quota limit is reached — upgrade your plan at https://www.cbe2json.be/dashboard/subscription" }, "meta": { "description": "Version 2 only, and only when the API key was identified before the error: the dataset and credits, as in a successful response (creditsUsed is 0).", "allOf": [ { "$ref": "#/components/envelope/ResponseMeta" } ] } } } } }, "headers": { "CBE2JSON-Credits-Used": { "description": "Credits this call used. Sent with QUOTA_EXHAUSTED, ENTERPRISE_NOT_FOUND and the data.limit VALIDATION_FAILED.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Remaining": { "description": "Credits left after this call. Sent with QUOTA_EXHAUSTED, ENTERPRISE_NOT_FOUND and the data.limit VALIDATION_FAILED.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Limit": { "description": "Your monthly allowance. Sent with QUOTA_EXHAUSTED, ENTERPRISE_NOT_FOUND and the data.limit VALIDATION_FAILED.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Reset": { "description": "When used credits next return to 0 (ISO 8601). Sent with QUOTA_EXHAUSTED, ENTERPRISE_NOT_FOUND and the data.limit VALIDATION_FAILED.", "schema": { "type": "string", "format": "date-time" } } } }, "unauthorizedResponse": { "description": "The clientId and secretKey do not match an API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorCode": { "type": "string", "enum": [ "BAD_CLIENT_SECRET" ] }, "message": { "type": "string" } } } } } }, "enterpriseNotFound": { "description": "No enterprise matches the CBE number (byCBE) or the name (byDenomination). Version 2: byDenomination answers a search without results with 200 and an empty list instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorCode": { "type": "string", "enum": [ "ENTERPRISE_NOT_FOUND" ] }, "message": { "type": "string", "example": "Enterprise not found" }, "meta": { "description": "Version 2 only, and only when the API key was identified before the error: the dataset and credits, as in a successful response (creditsUsed is 0).", "allOf": [ { "$ref": "#/components/envelope/ResponseMeta" } ] } } } } }, "headers": { "CBE2JSON-Credits-Used": { "description": "Credits this call used. Sent with QUOTA_EXHAUSTED, ENTERPRISE_NOT_FOUND and the data.limit VALIDATION_FAILED.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Remaining": { "description": "Credits left after this call. Sent with QUOTA_EXHAUSTED, ENTERPRISE_NOT_FOUND and the data.limit VALIDATION_FAILED.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Limit": { "description": "Your monthly allowance. Sent with QUOTA_EXHAUSTED, ENTERPRISE_NOT_FOUND and the data.limit VALIDATION_FAILED.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Reset": { "description": "When used credits next return to 0 (ISO 8601). Sent with QUOTA_EXHAUSTED, ENTERPRISE_NOT_FOUND and the data.limit VALIDATION_FAILED.", "schema": { "type": "string", "format": "date-time" } } } }, "originNotAllowedResponse": { "description": "The request's Origin is not on this API key's allowlist. No quota is consumed. Because the response deliberately carries no Access-Control-Allow-Origin header, a browser cannot read this body — rejected origins are listed in your dashboard instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorCode": { "type": "string", "enum": [ "ORIGIN_NOT_ALLOWED" ] }, "message": { "type": "string", "example": "Origin not allowed for this API key" } } } } } }, "searchBadRequestResponse": { "description": "`VALIDATION_FAILED` takes two forms here. Before the API key is identified, a malformed body (an unknown field, or a field of the wrong basic type — e.g. nace/zipcode not a string or an array of strings, naceVersion not 2008 or 2025, juridicalForm/juridicalSituation not a non-empty array of the right type, limit/offset not an integer) answers a bare `{ \"errorCode\": \"VALIDATION_FAILED\" }`: no `message`, no `meta`, no credit headers — the key isn't known yet. Once the key is identified, every filter and size/range rule answers with the specific reason in `message` plus credit `meta` and the credit headers below (creditsUsed is 0): at least one of nace, zipcode, municipality, street or name is required; street needs zipcode or municipality; houseNumber needs street; a nace entry must be 2 to 7 digits once dots are stripped, at most 10 entries; a zipcode entry must be exactly 4 digits, at most 20 entries; at most 20 juridicalForm or juridicalSituation entries; data.limit must be between 1 and 100 for /search or 1 and 1000 for /search/numbers; data.offset must be 0 or greater; offset + limit must not exceed 10000; municipality, street, name or houseNumber must contain at least one searchable character. `QUOTA_EXHAUSTED`: your credits for this month are used up, or the request would return more results than the credits left (lower data.limit); nothing is charged. `UNSUPPORTED_API_VERSION`: the CBE2JSON-Version header names a version that does not exist, or asks for a version earlier than 2 (not supported on these routes).", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorCode": { "type": "string", "enum": [ "VALIDATION_FAILED", "QUOTA_EXHAUSTED", "UNSUPPORTED_API_VERSION" ] }, "message": { "type": "string", "example": "Your quota limit is reached — upgrade your plan at https://www.cbe2json.be/dashboard/subscription" }, "meta": { "description": "Version 2 only, and only when the API key was identified before the error: the dataset and credits, as in a successful response (creditsUsed is 0).", "allOf": [ { "$ref": "#/components/envelope/ResponseMeta" } ] } } } } }, "headers": { "CBE2JSON-Credits-Used": { "description": "Credits this call used. Sent with QUOTA_EXHAUSTED and every VALIDATION_FAILED raised after the key is identified (not the bare pre-identification shape errors).", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Remaining": { "description": "Credits left after this call. Sent with QUOTA_EXHAUSTED and every VALIDATION_FAILED raised after the key is identified (not the bare pre-identification shape errors).", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Limit": { "description": "Your monthly allowance. Sent with QUOTA_EXHAUSTED and every VALIDATION_FAILED raised after the key is identified (not the bare pre-identification shape errors).", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Reset": { "description": "When used credits next return to 0 (ISO 8601). Sent with QUOTA_EXHAUSTED and every VALIDATION_FAILED raised after the key is identified (not the bare pre-identification shape errors).", "schema": { "type": "string", "format": "date-time" } } } } }, "byCBE": { "body": { "description": "Body contains your account information and a data object identifying the enterprise requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "secretKey": { "type": "string" }, "data": { "type": "object", "properties": { "cbe": { "description": "An enterprise (CBE/KBO/BCE) number: 0XXX.XXX.XXX, with or without the dots, optionally prefixed with BE (e.g. 0123.456.789, 0123456789, BE0123456789). A 9-digit number is read with a leading 0.", "type": "string", "example": "0202.239.951" } } } } } } } } }, "byDenomination": { "body": { "description": "Body contains your account information and a data object identifying the enterprise requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "secretKey": { "type": "string" }, "data": { "type": "object", "properties": { "denomination": { "description": "A name of an enterprise or one of its establishments", "type": "string", "example": "Proximus" }, "limit": { "description": "[Optional; default: 10] The maximum number of enterprises returned. Version 2: 1 to 100.", "type": "number", "example": 10, "optional": true, "default": 10 }, "offset": { "description": "[Optional; default: 0] The number of companies to ignore before starting to return them as results", "type": "number", "example": 0, "optional": true, "default": 0 } } } } } } } } }, "envelope": { "ResponseMeta": { "type": "object", "description": "Version 2. About the call: the dataset served and the credits.", "properties": { "source": { "type": "string", "example": "CBE" }, "dataUpdatedAt": { "type": "string", "format": "date", "nullable": true, "description": "Date of the CBE dataset served.", "example": "2026-09-27" }, "creditsUsed": { "type": "integer", "description": "Credits this call used.", "example": 1 }, "creditsRemaining": { "type": "integer", "nullable": true, "description": "Credits left after this call; null for an account without a limit." }, "creditsLimit": { "type": "integer", "nullable": true, "description": "Your monthly allowance; null for an account without a limit." }, "creditsResetAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When used credits next return to 0: the 1st of the month (00:00 UTC) on the Free plan, your billing date on paid plans and trials. null when unknown or for an account without a limit." } } }, "SearchMeta": { "allOf": [ { "$ref": "#/components/envelope/ResponseMeta" }, { "type": "object", "properties": { "total": { "type": "integer", "description": "Matches in total. On /search and /search/numbers it stops at 10,000 (see totalCapped)." }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasNext": { "type": "boolean", "description": "Whether a next page exists." }, "totalCapped": { "type": "boolean", "description": "Only on /search and /search/numbers, and only when true: total stopped at 10,000 and more enterprises match. Pages still cover the first 10,000 in order; narrow the filters to see the rest." } } } ] }, "EnterpriseResponse": { "type": "object", "description": "Version 2 response of byCBE.", "properties": { "data": { "$ref": "#/components/enterprise/Enterprise" }, "meta": { "$ref": "#/components/envelope/ResponseMeta" } } }, "SearchResponse": { "type": "object", "description": "Version 2 response of byDenomination. No match, or a page past the last result, returns an empty data list.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/enterprise/Enterprise" } }, "meta": { "$ref": "#/components/envelope/SearchMeta" } } }, "SearchResult": { "allOf": [ { "$ref": "#/components/enterprise/Enterprise" }, { "type": "object", "properties": { "match": { "type": "object", "description": "Which units met the NACE and address filters.", "properties": { "registeredOffice": { "type": "boolean" }, "establishments": { "type": "array", "items": { "type": "string" }, "example": [ "2.123.456.789" ] } } } } } ] }, "CompanySearchResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/envelope/SearchResult" } }, "meta": { "$ref": "#/components/envelope/SearchMeta" } } }, "NumbersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string", "example": "0403.170.701" } }, "meta": { "$ref": "#/components/envelope/SearchMeta" } } } }, "search": { "body": { "description": "Your account information and the filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "secretKey": { "type": "string" }, "data": { "type": "object", "description": "Give at least one of nace, zipcode, municipality, street or name. NACE and address filters must match the same unit: the registered office or one establishment.", "properties": { "nace": { "description": "NACE code prefix, 2 to 7 digits (dots allowed), or a list of up to 10. \"56\" matches every code starting with 56.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 10 } ], "example": "62.01" }, "naceVersion": { "description": "[Optional; default: 2025] NACE code list the codes refer to.", "type": "integer", "enum": [ 2008, 2025 ] }, "zipcode": { "description": "Belgian postcode (4 digits), or a list of up to 20.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 20 } ], "example": "1000" }, "municipality": { "description": "Municipality name in Dutch or French; case and accents are ignored.", "type": "string" }, "street": { "description": "Street name in Dutch or French; case and accents are ignored. Needs zipcode or municipality.", "type": "string" }, "houseNumber": { "description": "House number. Needs street.", "type": "string" }, "name": { "description": "Name of the enterprise or of one of its establishments, as in byDenomination.", "type": "string" }, "juridicalForm": { "description": "Legal form codes.", "type": "array", "items": { "type": "integer" }, "maxItems": 20 }, "juridicalSituation": { "description": "Legal situation codes.", "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "offset": { "description": "[Optional; default: 0] Results to skip. offset + limit must not exceed 10000.", "type": "integer", "default": 0 }, "limit": { "description": "[Optional; default: 10] 1 to 100.", "type": "integer", "default": 10 } } } } } } } }, "numbersBody": { "description": "Your account information and the filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "secretKey": { "type": "string" }, "data": { "type": "object", "description": "Give at least one of nace, zipcode, municipality, street or name. NACE and address filters must match the same unit: the registered office or one establishment.", "properties": { "nace": { "description": "NACE code prefix, 2 to 7 digits (dots allowed), or a list of up to 10. \"56\" matches every code starting with 56.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 10 } ], "example": "62.01" }, "naceVersion": { "description": "[Optional; default: 2025] NACE code list the codes refer to.", "type": "integer", "enum": [ 2008, 2025 ] }, "zipcode": { "description": "Belgian postcode (4 digits), or a list of up to 20.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 20 } ], "example": "1000" }, "municipality": { "description": "Municipality name in Dutch or French; case and accents are ignored.", "type": "string" }, "street": { "description": "Street name in Dutch or French; case and accents are ignored. Needs zipcode or municipality.", "type": "string" }, "houseNumber": { "description": "House number. Needs street.", "type": "string" }, "name": { "description": "Name of the enterprise or of one of its establishments, as in byDenomination.", "type": "string" }, "juridicalForm": { "description": "Legal form codes.", "type": "array", "items": { "type": "integer" }, "maxItems": 20 }, "juridicalSituation": { "description": "Legal situation codes.", "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "offset": { "description": "[Optional; default: 0] Results to skip. offset + limit must not exceed 10000.", "type": "integer", "default": 0 }, "limit": { "description": "[Optional; default: 100] 1 to 1000.", "type": "integer", "default": 100 } } } } } } } } } }, "paths": { "/byDenomination": { "post": { "description": "Search enterprises by their name (denomination) or the name of one of their establishments. Uses 1 credit per enterprise returned.", "summary": "Find enterprises by Denomination", "required": true, "parameters": [ { "$ref": "#/components/versionHeader" } ], "requestBody": { "$ref": "#/components/byDenomination/body" }, "responses": { "200": { "description": "Version 1: a non-empty array of enterprises (no match, or a page past the last result, returns 404 ENTERPRISE_NOT_FOUND). Version 2: { data, meta }; no match returns an empty list.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/envelope/SearchResponse" }, { "type": "array", "items": { "$ref": "#/components/enterprise/Enterprise" } } ] } } }, "headers": { "CBE2JSON-Credits-Used": { "description": "Credits this call used.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Remaining": { "description": "Credits left after this call.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Limit": { "description": "Your monthly allowance.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Reset": { "description": "When used credits next return to 0 (ISO 8601).", "schema": { "type": "string", "format": "date-time" } } } }, "400": { "$ref": "#/components/commonError/badRequestResponse" }, "401": { "$ref": "#/components/commonError/unauthorizedResponse" }, "403": { "$ref": "#/components/commonError/originNotAllowedResponse" }, "404": { "$ref": "#/components/commonError/enterpriseNotFound" } } } }, "/byCBE": { "post": { "description": "Returns one enterprise by its CBE number. Uses 1 credit when found.", "summary": "Find enterprise by CBE number", "required": true, "parameters": [ { "$ref": "#/components/versionHeader" } ], "requestBody": { "$ref": "#/components/byCBE/body" }, "responses": { "200": { "description": "The enterprise. Version 1: the enterprise object. Version 2: { data, meta }.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/envelope/EnterpriseResponse" }, { "$ref": "#/components/enterprise/Enterprise" } ] } } }, "headers": { "CBE2JSON-Credits-Used": { "description": "Credits this call used.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Remaining": { "description": "Credits left after this call.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Limit": { "description": "Your monthly allowance.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Reset": { "description": "When used credits next return to 0 (ISO 8601).", "schema": { "type": "string", "format": "date-time" } } } }, "400": { "$ref": "#/components/commonError/badRequestResponse" }, "401": { "$ref": "#/components/commonError/unauthorizedResponse" }, "403": { "$ref": "#/components/commonError/originNotAllowedResponse" }, "404": { "$ref": "#/components/commonError/enterpriseNotFound" } } } }, "/search": { "post": { "description": "Look up enterprises by NACE code, postcode, municipality, street and house number, name, legal form or legal situation. Enterprises that are natural persons (sole traders) are never returned: their data is personal data under the KBO Open Data licence. Look them up one at a time with /byCBE or /byDenomination. Uses 1 credit per enterprise returned; an empty result uses none. Results are ordered by ascending enterprise number, so offset and limit page through them in a stable order. total stops at 10,000; totalCapped is true when there are more.", "summary": "Find enterprises by activity, address or legal status", "required": true, "parameters": [ { "$ref": "#/components/versionHeader" } ], "requestBody": { "$ref": "#/components/search/body" }, "responses": { "200": { "description": "Always { data, meta } (version 2). No match returns an empty list.", "content": { "application/json": { "schema": { "$ref": "#/components/envelope/CompanySearchResponse" } } }, "headers": { "CBE2JSON-Credits-Used": { "description": "Credits this call used.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Remaining": { "description": "Credits left after this call.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Limit": { "description": "Your monthly allowance.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Reset": { "description": "When used credits next return to 0 (ISO 8601).", "schema": { "type": "string", "format": "date-time" } } } }, "400": { "$ref": "#/components/commonError/searchBadRequestResponse" }, "401": { "$ref": "#/components/commonError/unauthorizedResponse" }, "403": { "$ref": "#/components/commonError/originNotAllowedResponse" } } } }, "/search/numbers": { "post": { "description": "Same filters and rules as /search, so natural persons are never returned; returns only enterprise numbers, up to 1000 per page. Uses 1 credit per page with results; an empty page uses none. Results are ordered by ascending enterprise number, so offset and limit page through them in a stable order. total stops at 10,000; totalCapped is true when there are more.", "summary": "Find enterprise numbers by activity, address or legal status", "required": true, "parameters": [ { "$ref": "#/components/versionHeader" } ], "requestBody": { "$ref": "#/components/search/numbersBody" }, "responses": { "200": { "description": "Always { data, meta } (version 2). No match returns an empty list.", "content": { "application/json": { "schema": { "$ref": "#/components/envelope/NumbersResponse" } } }, "headers": { "CBE2JSON-Credits-Used": { "description": "Credits this call used.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Remaining": { "description": "Credits left after this call.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Limit": { "description": "Your monthly allowance.", "schema": { "type": "integer" } }, "CBE2JSON-Credits-Reset": { "description": "When used credits next return to 0 (ISO 8601).", "schema": { "type": "string", "format": "date-time" } } } }, "400": { "$ref": "#/components/commonError/searchBadRequestResponse" }, "401": { "$ref": "#/components/commonError/unauthorizedResponse" }, "403": { "$ref": "#/components/commonError/originNotAllowedResponse" } } } } } }