Documentation / Examples

API BCE examples: calls in cURL, JavaScript and Python

API BCE examples ready to copy: company record, search by name or address, VAT validation through VIES and NACE codes, in cURL, JavaScript and Python.

Copy-paste recipes for the most common tasks. Every call is authenticated (see Authentication).

Fetch an enterprise#

curl https://companybelgium.be/api/v2/enterprise/1033.022.383 \
  -H "X-API-Key: $API_BCE_KEY" \
  -H "X-API-Secret: $API_BCE_SECRET"

Search by company name#

curl "https://companybelgium.be/api/v2/denominations?q=espero&limit=5" \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"

Search by address#

curl "https://companybelgium.be/api/v2/search/address?postalCode=1080&street=Colonne" \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"

Validate an EU VAT number#

curl "https://companybelgium.be/api/v2/vat/BE1033022383" \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"

Search NACE activity codes#

curl "https://companybelgium.be/api/v2/naces?q=programmation&version=2008&limit=10" \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"
ℹ️

Prefer to explore interactively? Open the API Playground and fire real requests from your browser.

Combining the recipes into real workflows#

Each example shows a single call. In practice, a feature chains several of them. Here are typical combinations that teams build first, and the order in which the calls usually happen.

  • Supplier onboarding: search by name with /denominations, let the user pick a result, then fetch /enterprise/{num} and validate the VAT number with /vat/{vatNumber}.
  • Field sales: query /search/address to find the companies registered at an address you visit.
  • Market segmentation: search activity codes with /naces, then store the chosen code on each CRM account.
  • Invoicing: run the VAT check right before you issue the invoice, and keep the requestDate with it.

Adapting API BCE examples to production code#

The snippets read credentials from environment variables, and you should keep that habit. However, they skip error handling on purpose to stay short. So, add a status check, a timeout and a retry with exponential backoff on 429 and 5xx responses. In addition, URL-encode query parameters such as q and street, because company names and streets contain spaces and accents.

Next, set an explicit limit. For instance, /denominations returns 20 suggestions by default and 50 at most, while /naces returns 50 rows by default and 200 at most. A small limit keeps responses fast and your interface readable.

Run the examples safely#

The examples use the publisher’s own enterprise, 1033.022.383, so they return real data with a live key. To experiment without spending quota, replace the base URL with https://api-bce.be/test/v2 and use 0999.999.130 instead. Alternatively, open the sandbox and send the same requests from your browser.

Testing the recipes in your codebase#

Turn each API BCE recipe into an automated test. First, point the test at the test API with a pk_test_ key. Then, assert the fields your feature uses rather than the whole response, because new fields may be added. For instance, a supplier onboarding test can check the name, the status and the VAT result for 0999.999.130. Next, add one test per error case, such as 0999.999.999 for a 400. As a result, a regression shows up in your pipeline, not in production.

API BCE examples FAQ#

Which languages can call API BCE?

Any language with an HTTP client works, because the API uses plain HTTPS and JSON. The examples cover cURL, JavaScript and Python. Also, the OpenAPI document can generate a typed client.

Why does my name search return nothing?

Check the length of q first. The name search needs at least 2 characters. Then, check that the term is URL-encoded.

Do the example calls count against my quota?

Yes, when you use a live key. However, test mode uses no monthly quota, and calls to /me never count.