Belgian Company Data API v2 + Webhooks

Why v2?

Our v1 API delivered on its promise: expose Belgian company data and Espero-Soft 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.

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). No more asking "describe this code" on every lookup — you hold the dictionary in memory.

Belgian VAT validation

Highly requested endpoint: POST /api/v2/vat/validate. Returns the normalized version, the status (valid / invalid / bad format), and the matched enterprise number. Handy to validate an onboarding form before creating a client record.

Payment risk scoring

GET /api/v2/companies/{enterpriseNumber}/payment-risk returns a 0–100 score and a category (low / moderate / high / critical), built from aggregated signals: company age, size, sector, accounting situation, recent BCE events.

A ready-to-use front widget is also available for teams who want to visually integrate the info into their back office without rebuilding it all.

Real-time webhooks

The most structural addition. You can 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. Exponential retry up to 24 h, admin page to manually replay if needed.

Authentication and quotas

Auth is still based on a public key + secret pair (pk_live_... / sk_live_...), unchanged since v1. Quotas are more generous on v2, and the counter is visible in real time in your dashboard.

Migrating from v1

v1 stays supported through end of 2026. v2 endpoints run in parallel. For most cases:

• Replace /api/ with /api/v2/ in your URLs.
• Add Accept: application/json header (recommended).
• Review richer responses (more fields by default, not fewer).

Who is it for?

Developers, ERP integrators, data teams feeding a warehouse, firms industrializing client-data collection. Anyone tired of coding their own BCE connector.