Company data API

Nummo API

Fetch Belgian company data in your own software: KBO data, key figures from the annual accounts and Peppol status, through a simple REST API with JSON.

Get the API plan OpenAPI description

Overview

What you get

Data from the Crossroads Bank for Enterprises (KBO) for every Belgian enterprise.
Key figures and ratios from the annual accounts filed with the National Bank.
The Peppol status, straight from the Peppol network.
Search by name, number, street or municipality.

All responses are JSON with English field names. The API is read-only. Nummo is not an official source: when in doubt, the source itself always prevails.

Rather use Nummo in Claude or ChatGPT, without writing code yourself? Connect Nummo to your AI assistant.

Getting started

Authenticating with a key

The API is part of the API plan. With it you create up to 5 keys on your profile; they work as long as the plan runs. You only see a key once: copy it straight away and keep it like a password. We only store an unreadable fingerprint of the key.

Send the key in the Authorization header (or in X-Api-Key):

curl -H "Authorization: Bearer $NUMMO_KEY" \
  https://www.nummo.be/api/v1/companies/0999001020

Only use the key on your own server, not in code that runs in your visitors' browsers. If a key leaks anyway, revoke it on your profile and create a new one.

REST API with JSON

Endpoints

Base URL: https://www.nummo.be/api/v1

Call	What you get
`GET /companies/{number}`	KBO data: name, legal form, status, registered office, activities (NACE), number of branches and contact details. With ?lang=nl, fr or en you choose the language of the descriptions.
`GET /companies/{number}/financials`	Key figures from the filed annual accounts: revenue, gross margin, profit, equity, staff, debt and ratios. With ?years=1 to 10 (default 5).
`GET /companies/{number}/peppol`	Is the enterprise on Peppol, under the enterprise number (0208) and the VAT number (9925)?
`GET /search?q=...`	Search by name, number, street or municipality. With ?limit=1 to 50 (default 20).
`GET /openapi.json`	The full description of the API in OpenAPI 3.1. No key needed.

The enterprise number may be written with or without dots and with or without BE: 0999001020, 0999.001.020 and BE0999001020 all work.

curl

Examples

# A company
curl -H "Authorization: Bearer $NUMMO_KEY" "https://www.nummo.be/api/v1/companies/0999001020?lang=fr"

# Key figures for the last 3 fiscal years
curl -H "Authorization: Bearer $NUMMO_KEY" "https://www.nummo.be/api/v1/companies/0999001020/financials?years=3"

# Peppol status
curl -H "X-Api-Key: $NUMMO_KEY" "https://www.nummo.be/api/v1/companies/0999001020/peppol"

# Search
curl -H "Authorization: Bearer $NUMMO_KEY" "https://www.nummo.be/api/v1/search?q=bakkerij%20gent&limit=5"

Response for a company

{
  "enterprise_number": "0999001020",
  "formatted": "0999.001.020",
  "vat_number": "BE0999001020",
  "type": "legal_entity",
  "name": "Bakkerij De Zoete Korst BV",
  "abbreviation": null,
  "other_names": [
    { "name": "Zoete Korst", "type": "commercial_name", "language": "nl" }
  ],
  "status": "active",
  "legal_form": { "code": "015", "description": "Besloten vennootschap" },
  "legal_situation": "Normale toestand",
  "start_date": "1985-01-01",
  "stop_date": null,
  "registered_office": {
    "street": "Veldstraat", "house_number": "10", "box": "2",
    "postal_code": "9000", "municipality": "Gent", "country": "België"
  },
  "activities": [
    { "nace_code": "10.710", "version": "2025", "description": "Vervaardiging van brood en van vers banketbakkerswerk", "main": true }
  ],
  "branches_count": 3,
  "contact": { "website": "www.bakkerijdezoetekorst.example", "email": null, "phone": null },
  "nummo_url": "https://www.nummo.be/bakkerij-de-zoete-korst-bv-0999001020"
}

Response for a sole proprietorship

{
  "enterprise_number": "0999008047",
  "formatted": "0999.008.047",
  "type": "natural_person",
  "status": "active",
  "legal_form": null,
  "start_date": "2005-06-15",
  "stop_date": null,
  "registered_office": { "postal_code": "9070", "municipality": "Destelbergen" },
  "activities": [ ... ]
}

Limits

With the API plan, 25,000 calls per calendar month for all your keys together, and at most 2,500 per day. Calls to /search count only toward the daily limit, not the monthly quota. The daily counter resets at midnight (Belgian time), the monthly counter on the first of the month.
At most 60 calls per minute per key.
Every response contains the headers X-RateLimit-Limit and X-RateLimit-Remaining (monthly quota) and X-RateLimit-Daily-Limit and X-RateLimit-Daily-Remaining (daily limit).
If you exceed a limit, you get 429 with a Retry-After header.

Need more than 25,000 calls per month? Let us know through the help page and we will make you a custom offer. Go to help

HTTP

Errors

On an error you get an HTTP status and a JSON object with a fixed code and an explanation in English:

{
  "error": {
    "code": "invalid_number",
    "message": "Not a valid Belgian enterprise number. ..."
  }
}

Status	Code	Meaning
`400`	`invalid_number, invalid_parameter`	Not a valid enterprise number, or a parameter out of range.
`401`	`missing_key, invalid_key`	No key sent, or a key we do not know.
`403`	`key_revoked, api_plan_required`	The key has been revoked, or the account has no active API plan.
`404`	`not_found, not_available, no_financials`	Unknown or hidden number, no annual accounts for a natural person, or no annual accounts found.
`429`	`rate_limited, daily_limit_reached, monthly_quota_exceeded`	Too many calls: per minute, per day or per month. The Retry-After header says how many seconds to wait.
`503`	`service_unavailable`	The API is temporarily unavailable.
`504`	`upstream_timeout`	The Peppol network did not answer in time.

GDPR

Privacy

The KBO also contains sole proprietorships of natural persons. We handle those with care, in the API too.

Sole proprietorships (natural persons): no name, no street, no contact details and no branches. You only get the number, status, legal form, dates, postal code and municipality, and activities. A name search does not find them, and there are no annual accounts.
Enterprises that asked to restrict their data: the name yes, but of the address only postal code and municipality, and no contact details.
Enterprises that asked not to be shown: they do not exist for the API (404).

If you use the data for direct marketing or profiling, you are responsible for complying with the GDPR. Privacy policy

CORS

From the browser

The API allows CORS for GET calls from any domain, handy for internal tools and prototypes. Never put a key in a public website: anyone can read it there. Responses are not cached (Cache-Control: private, no-store).

Pricing

API plan

€999 per year, excl. VAT

25,000 calls per month per account, at most 2,500 per day
Searches do not count toward the monthly quota
Up to 5 keys, for example for testing and production
Nummo Pro included, for anyone who also works on the website
Invoice with VAT, also via Peppol

Trying it out

The examples above show every call and every response, and you can view the OpenAPI description without a key. You create keys with the API plan: without a plan the API does not work.

Create an API key OpenAPI description