Do you feed Belgian company information into a CRM, an ERP or a sign-up form? Version 2 of our data API adds stable reference tables, VAT number validation, a payment risk score and, above all, real-time webhooks. Here is what changes, how to migrate from v1 and which practices keep your integration robust.
Why a new version of the data API?
The first version kept its promise: it exposed KBO/BCE records and Espero-Soft enrichments cleanly. Usage, however, taught us two lessons. Integrators want push instead of polling, and they prefer stable reference tables to a bundle of codes they must translate on every call.
Reference tables built for caching
NACE codes, legal forms and activity groups now have dedicated endpoints. Every path below sits under the version 2 base path:
- GET /reference/nace-codes?lang=fr
- GET /reference/juridical-forms?lang=nl
- GET /reference/activity-groups?lang=en
These tables rarely change, so load them once and keep them in a client-side cache: the data API returns an ETag header and a 24-hour Cache-Control. You no longer ask what a code means on every company lookup, because the dictionary stays in memory. The ETag also lets you check whether a table has changed before you download it again.
Belgian VAT number validation
It is one of the most requested endpoints of the data API: POST /vat/validate. It returns the normalised number, its status (valid, invalid or wrong format) and the linked enterprise number. In Belgium, the VAT number consists of BE followed by the ten-digit KBO/BCE enterprise number. Validate it as early as the sign-up form, before you create the customer record or send an e-invoice through Peppol.
Payment risk scoring
GET /companies/{enterpriseNumber}/payment-risk returns a score from 0 to 100 and a category: low, moderate, high or critical. The score combines several signals: age of the business, size, sector, accounting situation and recent KBO/BCE events.
A ready-made front-end widget also lets your team display the score in its back office without building everything. Treat it as an early warning, for instance to request a deposit, rather than as an automatic verdict.
Real-time webhooks in the data API
This is the most far-reaching addition. You subscribe to the events that matter to you:
- company.updated
- company.status_changed
- company.filing_deposited
- establishment.created
- establishment.closed
Each event arrives as a POST request at your URL, signed with HMAC SHA-256 using a shared secret, in the X-Espero-Signature header. If delivery fails, we retry with exponential backoff for up to 24 hours. Moreover, an admin page lets you replay an event manually.
Good practices on the receiving side
- Verify the signature on the raw request body before any processing.
- Answer fast with a 2xx status, then handle the event in the background.
- Handle duplicates: a retry can deliver the same event twice.
- Monitor failures and replay missed events from the admin page.
Authentication and quotas
Authentication still relies on a public and secret key pair (pk_live_... and sk_live_...), unchanged since v1. Keep the secret key on your server, never in a mobile app or front-end script. Quotas on version 2 of the data API are also more generous, and a live counter in your dashboard shows your usage.
Migrating from v1
Version 1 remains supported until the end of 2026, and the v2 endpoints run in parallel. In most cases, migration takes three steps:
- insert v2 into the base path of your URLs (/api/v2/);
- add the Accept: application/json header (recommended);
- review the enriched responses, which contain more fields by default, never fewer.
Test the switch in a staging environment first, then move production traffic over gradually.
Who is the data API for?
Our data API serves developers, ERP integrators, analytics teams that feed a warehouse and firms that industrialise the collection of customer information. In short, it suits anyone who no longer wants to code a custom KBO/BCE connector. Keep in mind, though, that records about sole traders remain personal data under the GDPR.
Typical use cases for the data API:
- Customer onboarding: pre-fill the record from the enterprise number and validate the VAT number.
- Risk management: receive a webhook as soon as a customer's status changes.
- Accounting: know when a client files new annual accounts.
Need help plugging these flows into your tools? Our custom IT development team can build the integration for you.
