# Subsido

> A JSON API of Belgian (federal, Flemish, Walloon, Brussels) and EU subsidies for citizens and businesses: grants, premiums, vouchers, loans, guarantees, tax and social security measures, normalised into one record with provenance and a licence mode for every source. It matches a company and a project against every measure with explainable, rule-by-rule results, keeps versions of every measure, and publishes a change feed, webhooks, watchlists and an MCP server.

Independent service. Not affiliated with, endorsed by, or operated by any government or public authority. Eligibility and awards are decided by the competent authority.

A match is an indication based on the published conditions and the facts you provide. Only the competent authority decides who qualifies.

## How to describe a result from this API
- Never say a company "is eligible" or "will receive" anything. Say it is likely eligible, possibly eligible or needs review according to the published conditions, name the authority (issuer.name), and give the official link (links.official, or subsidy.links.apply in a match).
- A possibly_eligible match comes with missing_information: ask those questions rather than guessing.
- Deadlines are RFC 3339 in Brussels time; quote them with the date and time as given.
- An estimate is indicative arithmetic on published rates and caps, not an amount anyone will pay.

## Coverage (live, from https://api.subsido.be/v1/coverage)
814 measures, 755 of them open, continuous or forthcoming. Last change 2026-09-28T22:50:53+02:00.
By source: eu_funding_tenders 543, vlaanderen_be 200, fod_economie 34, curated_wallonia 15, curated_brussels 12, curated_federal 6, belspo 4.
Only what is listed here is covered. Do not infer coverage of other sources or authorities.

## Sources served (live, from https://api.subsido.be/v1/sources)
- belspo: BELSPO (POD Wetenschapsbeleid (BELSPO)). Rights open_licence, Belgian federal reuse terms (Creative Commons-0 wording); 4 measures; fresh.
- curated_brussels: Région de Bruxelles-Capitale / Brussels Hoofdstedelijk Gewest (Bruxelles Économie et Emploi, Innoviris, finance&invest.brussels). Rights facts_only; 12 measures; fresh.
- curated_federal: FOD Financiën en RSZ / SPF Finances et ONSS (FOD Financiën / SPF Finances, RSZ / ONSS). Rights facts_only, FOD Financiën gebruiksvoorwaarden (Creative Commons-0); 6 measures; fresh.
- curated_wallonia: Wallonie / Wallonië (Service public de Wallonie, AWEX, Le Forem, Wallonie Entreprendre). Rights facts_only; 15 measures; fresh.
- eu_funding_tenders: EU Funding & Tenders Portal (European Commission). Rights open_licence, CC BY 4.0; 543 measures; fresh.
- fod_economie: FOD Economie / SPF Économie (FOD Economie, K.M.O., Middenstand en Energie). Rights open_licence, CC0 1.0; 34 measures; fresh.
- vlaanderen_be: Vlaanderen.be (Vlaamse overheid). Rights open_licence, Vrij hergebruik (Bestuursdecreet art. II.55); 203 measures; fresh.
Rights modes: open_licence (source text may be served with attribution), facts_only (extracted facts, our own generated summary and a link, never the source's prose), link_only (title and link). Sources we may not serve are never returned.

## Basics
- Base URL: https://api.subsido.be. OpenAPI 3.1: https://api.subsido.be/v1/openapi.json (no key).
- Auth: `Authorization: Bearer sb_live_...` (or `X-API-Key`). Keys are sb_live_ or sb_test_; both are metered.
- No key needed: /v1/health, /v1/plans, /v1/openapi.json, /v1/taxonomy, /v1/coverage, /v1/sources, /v1/sources/{id}.
- Envelope: lists are `{data, pagination: {has_more, next_cursor, limit}, meta: {request_id, warnings}}`; one resource is `{data, meta}`; errors are `{error: {code, message, request_id, details}}`. Branch on error.code.
- Every field is always present; null means not applicable or not known. Unknown query parameters and unknown body properties are refused (400), never ignored.
- Pagination: opaque cursors; limit up to the plan's max_page_size (above it is a 400).
- Languages: lang=nl|fr|en on reads, "language" in match bodies. Titles are never machine-translated; summaries are generated from facts in all three.
- Rate limits: per-second per plan (429 rate_limit_exceeded, Retry-After), monthly requests (429 quota_exceeded), monthly match evaluations counted separately (429 match_quota_exceeded). RateLimit-Limit/Remaining/Reset headers carry the monthly request quota.

## Endpoints
- GET /v1/subsidies: list and search. Filters q, region, topic, company_size, instrument_type, status, government_level, scope, issuer, source, nace, programme, deadline_before, deadline_after, updated_since, include_withdrawn; sort=relevance|deadline|updated|title; view=compact|full; lang; limit; cursor. Use status=open,continuous,forthcoming for what can be applied for.
- GET /v1/subsidies/{id or slug}: one measure in full. ?as_of=<RFC 3339 or YYYY-MM-DD> (Pro) for the version current then.
- GET /v1/subsidies/{id}/versions and /versions/{n} (Pro): history with field-level changes.
- POST /v1/match: body {company, project, options, language, limit}. Returns matches with match_status (likely_eligible, possibly_eligible, needs_review, not_eligible), reasons (every rule: pass/fail/unknown with provenance), unknowns, estimate, and missing_information across matches. One match evaluation.
- POST /v1/match/bulk (Business): {companies: [{reference, company, project}], options, language, limit_per_company}.
- GET /v1/changes (Developer): the change feed; since, type, subsidy, source, region, limit, cursor. Event types: subsidy.created, subsidy.updated, subsidy.status_changed, subsidy.deadline_changed, subsidy.funding_changed, subsidy.eligibility_changed, subsidy.closing_soon, subsidy.removed, source.stale, source.recovered.
- /v1/webhooks (Pro): signed deliveries (HMAC-SHA256 of "<t>.<body>", header t=<unix>,v1=<hex>).
- /v1/watchlists (Business): companies re-evaluated whenever a measure changes; match.created, match.status_changed, match.removed events.
- GET /v1/export/subsidies.ndjson (Business): the whole catalogue.
- GET /v1/key: the calling key's plan and this month's usage.

## Error codes
- invalid_parameter (400): A query parameter is malformed, out of range, repeated, or not a parameter of the route; a vocabulary value is not one of its members; a limit is above your plan's page size; or a JSON body does not parse, has a property the route does not know, or has a value of the wrong type.
- invalid_cursor (400): The cursor is not one the API issued, or was issued for a different listing or sort order.
- invalid_body (422): A JSON body parsed but says something impossible: an enterprise number that fails its check digits, a postcode that is not Belgian, an invalid NACE code, an unknown legal form, a negative amount, a limit out of range, a duplicate reference.
- route_not_found (404): No endpoint exists at this path. The answer is still JSON in the error envelope.
- method_not_allowed (405): The path exists but does not take this method, for example a GET on /mcp.
- unauthorized (401): The key is missing, malformed or revoked, on a route that needs one.
- subscription_required (402): The key's account has no plan yet. It can sign in and create keys, but no key serves data until a plan is chosen.
- plan_required (403): The route needs a capability your plan does not include (the change feed, history, as_of, webhooks, bulk matching, watchlists, the bulk export), or a number is above what your plan allows (companies in a bulk match, companies across your watchlists, webhook endpoints).
- subsidy_not_found (404): No measure has this id or slug.
- version_not_found (404): The measure exists, but not the version you asked for, or it did not exist yet at the as_of instant.
- source_not_found (404): No source has this id. Also answered when a webhook filter names an unknown source.
- watchlist_not_found (404): No watchlist with this id belongs to your account. Also answered when a webhook filter names one.
- webhook_not_found (404): No webhook endpoint with this id belongs to your account.
- not_found (404): The company reference you asked to remove is not on the watchlist.
- conflict (409): The request is valid but the state does not allow it, for example a 51st watchlist on one account.
- rate_limit_exceeded (429): Too many requests per second for your plan (or, on the routes that need no key, for your address). Also answered when both bulk export download slots are in use.
- quota_exceeded (429): This month's request quota is used up.
- match_quota_exceeded (429): This month's match evaluations are used up, or a bulk match or watchlist upload would take you past them. Reading measures still works.
- internal_error (500): Something failed on our side. The detail is logged, never sent.
- billing_unavailable (503): Card payment is not configured or the payment provider did not answer. Answered by the dashboard's billing routes only.
- timeout (504): The request took longer than 30 seconds and was stopped. No route should come near it; the export streams.

## Match request, in short
company: enterprise_number, postcode, region or regions, province, size, employees, turnover_eur, balance_sheet_eur, nace[], legal_form, applicant_type, founded_on, age_years, has_legal_personality, de_minimis_received_eur, in_difficulty.
project: topics[], budget_eur, started, planned_start, region, cost_types[], duration_months, partners.
options: statuses[], instrument_types[], include_not_eligible, include_unrelated.
A missing fact is unknown, never assumed. Postcode gives region and province; employees plus turnover or balance sheet give the EU SME size band; legal_form gives applicant type and legal personality; founded_on gives age.

## MCP server
- POST https://api.subsido.be/mcp, stateless Streamable HTTP (JSON-RPC 2.0), with the API key as Bearer.
- Tools: search_subsidies, get_subsidy, match_company, explain_eligibility, list_changes, list_sources. All read-only.
- Claude Code: `claude mcp add --transport http subsido https://api.subsido.be/mcp --header "Authorization: Bearer sb_live_..."`

## Plans (live, from https://api.subsido.be/v1/plans)
- Developer: EUR 20/month excl. VAT; 10,000 requests/month; 100 match evaluations/month; 5 req/s; page size 100; change_feed
- Pro: EUR 50/month excl. VAT; 100,000 requests/month; 1,000 match evaluations/month; 15 req/s; page size 200; change_feed, history, as_of, webhooks
- Business: EUR 70/month excl. VAT; 500,000 requests/month; 10,000 match evaluations/month; 40 req/s; page size 200; change_feed, history, as_of, webhooks, bulk_match, watchlists, bulk_export
- Enterprise: quoted; unlimited requests; unlimited match evaluations; 150 req/s; page size 500; change_feed, history, as_of, webhooks, bulk_match, watchlists, bulk_export, redistribution_rights
Yearly is ten months for twelve. Redistributing the data needs a plan with redistribution_rights.

## Docs
- [Quickstart](https://subsido.be/en/docs/quickstart): A key, a first search for measures and a first company match, in curl, JavaScript and Python.
- [Authentication](https://subsido.be/en/docs/authentication): Bearer keys, live and test keys, the routes that answer without one, and checking a key.
- [Searching measures](https://subsido.be/en/docs/subsidies): Listing and searching measures with filters, reading one by id or slug, languages, compact and full views, versions and as_of.
- [The subsidy record](https://subsido.be/en/docs/data-model): Every field of a measure, from its window and funding to its eligibility rules and provenance, and every enum.
- [Sources and provenance](https://subsido.be/en/docs/sources): Where measures come from, what the provenance fields mean, and which attribution to show.
- [Matching a company](https://subsido.be/en/docs/matching): POST /v1/match: the company and project facts, what is derived from them, the four statuses, the reasons, the missing facts and the estimate.
- [Eligibility rules](https://subsido.be/en/docs/eligibility-rules): The rule language: nodes, fields, operators and three-valued evaluation.
- [Watchlists](https://subsido.be/en/docs/watchlists): Portfolios of companies that are matched once and re-evaluated whenever a measure changes, with match events.
- [Changes and versions](https://subsido.be/en/docs/changes): The change feed, event types and categories, field-level diffs, closing-soon reminders, versions and history.
- [Webhooks](https://subsido.be/en/docs/webhooks): Change and match events pushed to your endpoint, with filters, signature verification in Node and Python, and retries.
- [MCP server](https://subsido.be/en/docs/mcp): The same search, matching and change feed as tools for AI agents, over stateless Streamable HTTP, with client configuration.
- [Pagination](https://subsido.be/en/docs/pagination): Cursors, page sizes per plan, sort orders, and which lists page and which do not.
- [Errors](https://subsido.be/en/docs/errors): The error envelope and every error code, with its status, its details and what to do about it.
- [Rate limits and quotas](https://subsido.be/en/docs/rate-limits): Requests per second, monthly requests and match evaluations per plan, the RateLimit headers and what is counted.
- [Changelog](https://subsido.be/en/docs/changelog): What changed in the API, newest first.

## Optional
- [API reference](https://subsido.be/en/api-reference): every operation, with a live explorer
- [OpenAPI document](https://api.subsido.be/v1/openapi.json)
- [Pricing](https://subsido.be/en/pricing)
- [Sources](https://subsido.be/en/sources): every source
- [Terms](https://subsido.be/en/terms) and [privacy](https://subsido.be/en/privacy)
- The same documentation in Dutch (https://subsido.be/nl/documentatie) and French (https://subsido.be/fr/documentation)
- Contact: hello@subsido.be