Een onderneming matchen

Het verzoek#

$ curl -X POST "https://api.subsido.be/v1/match" \  -H "Authorization: Bearer sb_live_..." \  -H "Content-Type: application/json" \  -d '{"company":{"postcode":"9000","employees":12,"turnover_eur":1500000,"legal_form":"bv","nace":["62.010"]},"project":{"topics":["digitalisation","investment"],"budget_eur":25000,"planned_start":"2026-11-01"},"language":"en","limit":10}'

De body is strikt: een eigenschap die de API niet kent, waar ook, of een waarde van het verkeerde type of buiten de vaste lijst, geeft 400 invalid_parameter met de naam erbij, zodat een verkeerd gespelde turnover nooit ongemerkt een onbekende wordt. Een waarde die wel te lezen is maar niet kan kloppen (een postcode buiten België, een ondernemingsnummer met een foutief controlegetal, een negatief bedrag) geeft 422 invalid_body met de eigenschap in details.field. Stuur Content-Type: application/json mee.

Een gegeven dat je niet meegeeft, is onbekend, nooit verondersteld. Daar draait het om: in plaats van een zelfzekere score op basis van gissingen zegt het antwoord welke gegevens voor elke maatregel de doorslag zouden geven.

company

project

options

Wat er afgeleid wordt#

Gegevens die je niet meegaf, worden voorzichtig afgeleid uit gegevens die je wel meegaf, en elke afleiding staat in profile.derived met de eigenschappen waaruit ze komt. estimate: true markeert een afleiding die op een veronderstelling berust.

Groottecategorieën

Aanbeveling 2003/361/EG: een plafond voor het personeelsbestand en ofwel het omzetplafond, ofwel het plafond voor het balanstotaal. Een onderneming die de financiële plafonds van een categorie overschrijdt, schuift een categorie op.

Partner- en verbonden ondernemingen veranderen de cijfers die de definitie gebruikt, en die ziet de API niet. Dat is een van de redenen waarom een match “waarschijnlijk” zegt en niet “komt in aanmerking”. Sommige maatregelen (de Belgische tax shelter bijvoorbeeld) gebruiken in plaats daarvan de groottetoets van het Wetboek van vennootschappen en verenigingen; hun regels toetsen dan rechtstreeks de cijfers, dus stuur de cijfers mee en niet alleen size.

De vier statussen#

De regels van elke maatregel worden geëvalueerd met drie mogelijke uitkomsten (pass, fail, unknown; zie voorwaarden als regels), en die uitkomst bepaalt samen met de kwaliteit van de regels de status:

Matches worden gesorteerd op status in die volgorde, dan op wat het snelst aangevraagd kan worden (open, doorlopend, binnenkort open, onbekend, gepauzeerd, budget op, gesloten), dan op score, en dan op de dichtstbijzijnde deadline.

Het antwoord#

{
  "matches": [
    {
      "subsidy_id": "federal:investeringsaftrek",
      "match_status": "likely_eligible",
      "confidence": 0.9,
      "relevance": 1,
      "score": 0.98,
      "reasons": [
        {
          "id": "applicant_type",
          "field": "company.applicant_type",
          "op": "in",
          "value": [
            "company",
            "self_employed",
            "farmer"
          ],
          "label": "Industrial, commercial or agricultural business, or liberal profession",
          "result": "pass",
          "actual": "company",
          "provenance": {
            "method": "curated",
            "source_url": "https://financien.belgium.be/nl/ondernemingen/vennootschapsbelasting/belastingvoordelen/investeringsaftrek",
            "source_section": "Wie kan de investeringsaftrek genieten?",
            "review_status": "verified",
            "reviewed_at": "2026-09-27",
            "note": null
          }
        }
      ],
      "unknowns": [],
      "matched_topics": [
        "digitalisation",
        "investment"
      ],
      "estimate": {
        "max_amount_eur": 10000,
        "rate_applied": 40,
        "basis": "€25,000 × 40%"
      },
      "subsidy": {
        "id": "federal:investeringsaftrek",
        "title": "Investment deduction",
        "summary": "Tax deduction from FOD Financiën for companies, self-employed people and farmers in Belgium. Covers 10% to 40% of eligible costs. Applications accepted at any time.",
        "status": "continuous",
        "instrument_type": "tax_deduction",
        "issuer": "FOD Financiën",
        "scope": "national",
        "regions": [],
        "topics": [
          "investment",
          "digitalisation",
          "energy_efficiency",
          "renewable_energy"
        ],
        "opens_at": null,
        "closes_at": null,
        "rolling": true,
        "budget_exhaustion_possible": false,
        "funding": {
          "rate_min": 10,
          "rate_max": 40,
          "amount_min": null,
          "amount_max": null,
          "annual_cap": null,
          "de_minimis": null
        },
        "rules_basis": "curated",
        "source": {
          "id": "curated_federal",
          "url": "https://financien.belgium.be/nl/ondernemingen/vennootschapsbelasting/belastingvoordelen/investeringsaftrek",
          "authority": "FOD Financiën",
          "last_checked_at": "2026-09-27T06:00:12+02:00",
          "freshness": "fresh"
        },
        "links": {
          "api": "https://api.subsido.be/v1/subsidies/federal:investeringsaftrek",
          "web": "https://subsido.be/en/grants/investeringsaftrek",
          "apply": "https://financien.belgium.be/nl/ondernemingen/vennootschapsbelasting/belastingvoordelen/investeringsaftrek"
        }
      }
    },
    {
      "subsidy_id": "federal:tax-shelter-start-up",
      "match_status": "possibly_eligible",
      "confidence": 0.9,
      "relevance": 0.25,
      "score": 0.515,
      "reasons": [
        {
          "id": "size",
          "field": "company.employees",
          "op": "lte",
          "value": 50,
          "label": "At most 50 employees (annual average)",
          "result": "pass",
          "actual": 12,
          "provenance": {
            "method": "curated",
            "source_url": "https://financien.belgium.be/nl/ondernemingen/tax-shelter-kleine-ondernemingen/startende-start-up",
            "source_section": "Art. 1:24 WVV",
            "review_status": "verified",
            "reviewed_at": "2026-09-27",
            "note": null
          }
        },
        {
          "id": "size_turnover_a",
          "field": "company.turnover_eur",
          "op": "lte",
          "value": 11250000,
          "label": "Annual turnover at most EUR 11,250,000 (excl. VAT)",
          "result": "pass",
          "actual": 1500000,
          "provenance": {
            "method": "curated",
            "source_url": "https://financien.belgium.be/nl/ondernemingen/tax-shelter-kleine-ondernemingen/startende-start-up",
            "source_section": "Art. 1:24 WVV",
            "review_status": "verified",
            "reviewed_at": "2026-09-27",
            "note": null
          }
        },
        {
          "id": "size_employees_b",
          "field": "company.employees",
          "op": "lte",
          "value": 50,
          "label": "At most 50 employees (annual average)",
          "result": "pass",
          "actual": 12,
          "provenance": {
            "method": "curated",
            "source_url": "https://financien.belgium.be/nl/ondernemingen/tax-shelter-kleine-ondernemingen/startende-start-up",
            "source_section": "Art. 1:24 WVV",
            "review_status": "verified",
            "reviewed_at": "2026-09-27",
            "note": null
          }
        },
        {
          "id": "size_balance_b",
          "field": "company.balance_sheet_eur",
          "op": "lte",
          "value": 6000000,
          "label": "Balance sheet total at most EUR 6,000,000",
          "result": "unknown",
          "actual": null,
          "provenance": {
            "method": "curated",
            "source_url": "https://financien.belgium.be/nl/ondernemingen/tax-shelter-kleine-ondernemingen/startende-start-up",
            "source_section": "Art. 1:24 WVV",
            "review_status": "verified",
            "reviewed_at": "2026-09-27",
            "note": null
          }
        },
        {
          "id": "size_turnover_c",
          "field": "company.turnover_eur",
          "op": "lte",
          "value": 11250000,
          "label": "Annual turnover at most EUR 11,250,000 (excl. VAT)",
          "result": "pass",
          "actual": 1500000,
          "provenance": {
            "method": "curated",
            "source_url": "https://financien.belgium.be/nl/ondernemingen/tax-shelter-kleine-ondernemingen/startende-start-up",
            "source_section": "Art. 1:24 WVV",
            "review_status": "verified",
            "reviewed_at": "2026-09-27",
            "note": null
          }
        },
        {
          "id": "size_balance_c",
          "field": "company.balance_sheet_eur",
          "op": "lte",
          "value": 6000000,
          "label": "Balance sheet total at most EUR 6,000,000",
          "result": "unknown",
          "actual": null,
          "provenance": {
            "method": "curated",
            "source_url": "https://financien.belgium.be/nl/ondernemingen/tax-shelter-kleine-ondernemingen/startende-start-up",
            "source_section": "Art. 1:24 WVV",
            "review_status": "verified",
            "reviewed_at": "2026-09-27",
            "note": null
          }
        },
        {
          "id": "age_max",
          "field": "company.age_years",
          "op": "lt",
          "value": 4,
          "label": "Within the first four years after incorporation",
          "result": "unknown",
          "actual": null,
          "provenance": {
            "method": "curated",
            "source_url": "https://financien.belgium.be/nl/ondernemingen/tax-shelter-kleine-ondernemingen/startende-start-up",
            "source_section": null,
            "review_status": "verified",
            "reviewed_at": "2026-09-27",
            "note": "Completed years: the fifth year after incorporation belongs to the scale-up regime."
          }
        }
      ],
      "unknowns": [
        {
          "field": "company.age_years",
          "request_path": "company.founded_on",
          "question": "When was the company founded?"
        }
      ],
      "matched_topics": [],
      "estimate": {
        "max_amount_eur": 11250,
        "rate_applied": 45,
        "basis": "€25,000 × 45%, capped at €500,000"
      },
      "subsidy": {
        "id": "federal:tax-shelter-start-up",
        "title": "Tax shelter for start-ups",
        "summary": "Tax credit from FOD Financiën for small companies in Belgium. Covers 30% to 45% of eligible costs, up to €500,000. Applications accepted at any time.",
        "status": "continuous",
        "instrument_type": "tax_credit",
        "issuer": "FOD Financiën",
        "scope": "national",
        "regions": [],
        "topics": [
          "starting_business",
          "financing"
        ],
        "opens_at": null,
        "closes_at": null,
        "rolling": true,
        "budget_exhaustion_possible": false,
        "funding": {
          "rate_min": 30,
          "rate_max": 45,
          "amount_min": null,
          "amount_max": 500000,
          "annual_cap": null,
          "de_minimis": null
        },
        "rules_basis": "curated",
        "source": {
          "id": "curated_federal",
          "url": "https://financien.belgium.be/nl/ondernemingen/tax-shelter-kleine-ondernemingen/startende-start-up",
          "authority": "FOD Financiën",
          "last_checked_at": "2026-09-27T06:00:12+02:00",
          "freshness": "fresh"
        },
        "links": {
          "api": "https://api.subsido.be/v1/subsidies/federal:tax-shelter-start-up",
          "web": "https://subsido.be/en/grants/tax-shelter-start-up",
          "apply": "https://financien.belgium.be/nl/ondernemingen/tax-shelter-kleine-ondernemingen/startende-start-up"
        }
      }
    }
  ],
  "matched": 2,
  "evaluated": 412,
  "profile": {
    "facts": {
      "company.applicant_type": "company",
      "company.employees": 12,
      "company.has_legal_personality": true,
      "company.legal_form": "bv",
      "company.nace": [
        "62010"
      ],
      "company.province": "east_flanders",
      "company.regions": [
        "flanders"
      ],
      "company.size": "small",
      "company.turnover_eur": 1500000,
      "project.budget_eur": 25000,
      "project.region": "flanders",
      "project.started": false,
      "project.topics": [
        "digitalisation",
        "investment"
      ]
    },
    "derived": [
      {
        "field": "company.regions",
        "value": [
          "flanders"
        ],
        "from": [
          "company.postcode"
        ],
        "estimate": false
      },
      {
        "field": "company.province",
        "value": "east_flanders",
        "from": [
          "company.postcode"
        ],
        "estimate": false
      },
      {
        "field": "company.size",
        "value": "small",
        "from": [
          "company.employees",
          "company.turnover_eur"
        ],
        "estimate": false
      },
      {
        "field": "company.applicant_type",
        "value": "company",
        "from": [
          "company.legal_form"
        ],
        "estimate": false
      },
      {
        "field": "company.has_legal_personality",
        "value": true,
        "from": [
          "company.legal_form"
        ],
        "estimate": false
      },
      {
        "field": "project.started",
        "value": false,
        "from": [
          "project.planned_start"
        ],
        "estimate": false
      },
      {
        "field": "project.region",
        "value": "flanders",
        "from": [
          "company.region"
        ],
        "estimate": true
      }
    ],
    "enterprise_number": null,
    "warnings": []
  },
  "missing_information": [
    {
      "field": "company.age_years",
      "request_path": "company.founded_on",
      "question": "When was the company founded?",
      "would_settle": 1
    }
  ],
  "language": "en",
  "disclaimer": "Independent service. Not affiliated with, endorsed by, or operated by any government or public authority. Eligibility and awards are decided by the competent authority.",
  "meta": {
    "request_id": "req_0192d3a4b5c67d8e9f0a1b2c3d4e5f61",
    "warnings": []
  }
}

Illustratieve waarden. De match met de tax shelter toont de logica aan het werk: de groottetoets is “twee van de drie criteria”, geschreven als een any van drie paren. Het eerste paar slaagde, dus het onbekende balanstotaal in de andere twee doet er niet toe en wordt niet gevraagd; de leeftijd van de onderneming is onbekend en zou de doorslag geven, dus die wordt wel gevraagd.

De raming

Rekenwerk op de gepubliceerde cijfers, louter indicatief:

• Het percentage is het hoogste niveau in funding.rates voor de grootte van de onderneming, of funding.rate_max als geen niveau die grootte noemt.
• Het plafond is het laagste van funding.amount_max en funding.annual_cap.
• Met een projectbudget en een percentage: budget × percentage, begrensd door het plafond. Anders, als er een plafond is: het plafond, als maximumbedrag. Anders null.
• basis beschrijft de berekening in woorden, in jouw taal (€ 25.000 × 40%, begrensd tot € 7.500). Bij een fiscale maatregel is het bedrag de omvang van het voordeel dat het percentage beschrijft, geen uitbetaling.

Wat een match kost#

Elke POST /v1/match is één request en één match-evaluatie, hoeveel maatregelen er ook geëvalueerd worden. Een verzoek dat geweigerd wordt wegens ongeldige gegevens, telt niet als evaluatie. Match-evaluaties hebben hun eigen maandelijks tegoed, zodat je maatregelen kunt blijven lezen als het op is; zie limieten en quota.

Bulkmatching#

Business en hogerVoor POST /v1/match/bulk heb je de capability bulk_match nodig.

Veel ondernemingen in één verzoek: tot 500 met Business en 5.000 met Enterprise. Elke onderneming krijgt je eigen reference (1 tot 200 tekens, uniek in het verzoek), die in het antwoord terugkomt.

{
  "companies": [
    {
      "reference": "client-0042",
      "company": {
        "postcode": "2000",
        "employees": 4,
        "legal_form": "bv"
      },
      "project": {
        "topics": [
          "energy_efficiency"
        ]
      }
    },
    {
      "reference": "client-0043",
      "company": {
        "postcode": "4000",
        "nace": [
          "47.110"
        ]
      }
    }
  ],
  "options": {
    "statuses": [
      "open",
      "continuous"
    ]
  },
  "language": "fr",
  "limit_per_company": 10
}

Het antwoord is { results, evaluated, language, disclaimer, meta }, één resultaat per onderneming in de volgorde van het verzoek: { reference, matches, matched, missing_information, error }. Een onderneming met ongeldige gegevens krijgt haar eigen error ({ code, message, details }) en lege matches, en telt niet mee; de andere zijn elk één evaluatie. limit_per_company is 1 tot 100 (standaard 10). Het hele verzoek wordt geweigerd met match_quota_exceeded als de geldige ondernemingen je over je tegoed zouden brengen, en met plan_required als het meer ondernemingen bevat dan je plan in één verzoek toelaat.

Wil je dezelfde ondernemingen opnieuw matchen telkens een maatregel verandert, zet ze dan op een watchlist: de herevaluatie is inbegrepen.