API v2: Reference Data, VAT validation and real-time webhooks

In brief

Company Belgium API v2 introduces four structural additions: Reference Data endpoints for NACE codes and legal forms (designed for client-side caching), real-time Belgian VAT number validation, a 0-100 payment risk score, and HMAC-SHA256-signed webhooks to receive BCE events in push mode rather than polling. v1 stays supported through end of 2026.

Why v2?

Our v1 BCE API delivered on its promise: expose Belgian company data and Company Belgium enrichments cleanly. But usage taught us two things: integrators want push over polling, and they want stable reference tables rather than a pile of codes to translate on every call.

v2 runs in parallel with v1 and introduces four structural additions: Reference Data, VAT validation, risk scoring, and webhooks.

Reference Data

NACE codes, legal forms, activity groups are now accessible via dedicated endpoints:

• GET /api/v2/reference/nace-codes?lang=en

• GET /api/v2/reference/juridical-forms?lang=en

• GET /api/v2/reference/activity-groups?lang=en

These tables rarely change. They're meant to be cached client-side (ETag + 24h Cache-Control provided).

1
2
3
4
5

class="code-comment">// Load NACE codes once at startup, cache in memory
const res = await fetch(class="code-string">"https:class="code-comment">//companybelgium.be/api/v2/reference/nace-codes?lang=en", {
  headers: { class="code-string">"X-API-Key": key, class="code-string">"X-API-Secret": secret }
});
const naceCodes = await res.json();

Belgian VAT validation

Highly requested endpoint:

1
2
3
4

curl -X POST https://companybelgium.be/api/v2/vat/validate \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..." \
  -d '{"vatNumber": "BE 0200.065.765"}'

Returns the normalized version, the status (valid / invalid / bad_format) and the matched BCE enterprise number. This same mechanism powers our Belgian invoicing module with automatic intracom reverse-charge.

Payment risk scoring

1
2
3

curl https://companybelgium.be/api/v2/companies/0200065765/payment-risk \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Returns a 0–100 score and a category (low / moderate / high / critical), built from aggregated signals.

Real-time webhooks

The most structural addition. Subscribe to events:

• company.updated

• company.status_changed

• company.filing_deposited

• establishment.created

• establishment.closed

Each event fires a POST to your URL, signed with HMAC SHA-256 using a shared secret. Header X-Espero-Signature.

1
2
3
4
5
6
7
8
9

import crypto from class="code-string">"crypto";

function verify(rawBody: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac(class="code-string">"sha256", secret)
    .update(rawBody)
    .digest(class="code-string">"hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Exponential retry up to 24 h, admin page to manually replay an event on consumer-side failure. For a complete guide on webhooks and their security, read our article on webhooks and real-time notifications.

Authentication and quotas

Auth still uses a public key + secret pair, unchanged since v1. Quotas are more generous on v2.

Migrating from v1

v1 stays supported through end of 2026. For most cases: replace /api/ with /api/v2/ in your URLs. A detailed migration guide is coming next sprint. In the meantime, consult the REST endpoints reference guide for the full v2 route structure.