Matching a company

The request#

$ 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}'

The body is strict: a property the API does not know, anywhere in it, or a value of the wrong type or outside its vocabulary, is 400 invalid_parameter naming it, so a misspelt turnover never silently turns into an unknown. A value that parses but cannot be right (a postcode outside Belgium, an enterprise number whose check digits fail, a negative amount) is 422 invalid_body with the property in details.field. Send Content-Type: application/json.

A fact you do not give is unknown, never assumed. That is the point: instead of a confident score built on guesses, the answer says which facts would settle each measure.

company

project

options

What is derived#

Facts you did not give are worked out from facts you did, conservatively, and every derivation is reported in profile.derived with the properties it came from. estimate: true marks one that rests on an assumption.

Size bands

Recommendation 2003/361/EC: a headcount ceiling and either the turnover or the balance-sheet ceiling. A company over a band’s financial ceilings moves up a band.

Partner and linked enterprises change the figures the definition uses, and the API cannot see them. That is one reason a match is “likely”, not “eligible”. Some measures (the Belgian tax shelter, for example) use the Belgian company code’s own size test instead; their rules then test the figures directly, so send the figures rather than only size.

The four statuses#

Each measure’s rules are evaluated with three-valued logic (pass, fail, unknown; see eligibility rules), and the outcome, together with how good the measure’s rules are, gives the status:

Matches are sorted by status in that order, then by what can be applied for soonest (open, continuous, forthcoming, unknown, paused, budget exhausted, closed), then by score, then by the nearest deadline.

The response#

{
  "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": []
  }
}

Illustrative values. The Tax Shelter match shows the logic at work: its size test is “two of three criteria”, written as an any of three pairs. The first pair passed, so the unknown balance sheet in the other two does not matter and is not asked for; the company’s age is unknown and would decide, so it is.

The estimate

Arithmetic on the published figures, indicative only:

• The rate is the highest tier in funding.rates for the company’s size, or funding.rate_max when no tier names that size.
• The cap is the lower of funding.amount_max and funding.annual_cap.
• With a project budget and a rate: budget × rate, capped. Otherwise, when there is a cap: the cap, as the maximum amount. Otherwise null.
• basis says the sum in words, in your language (€25,000 × 40%, capped at €7,500). For a tax measure the figure is the size of the advantage the rate describes, not a payment.

What a match costs#

Each POST /v1/match is one request and one match evaluation, whatever the number of measures evaluated. A request refused for invalid facts is not counted as an evaluation. Match evaluations have their own monthly allowance, so you can keep reading measures after it is spent; see rate limits and quotas.

Bulk matching#

Business and abovePOST /v1/match/bulk needs the bulk_match capability.

Many companies in one request: up to 500 on Business and 5,000 on Enterprise. Each has your own reference (1 to 200 characters, unique in the request), echoed back.

{
  "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
}

The answer is { results, evaluated, language, disclaimer, meta }, one result per company in request order: { reference, matches, matched, missing_information, error }. A company whose facts are invalid gets its own error ({ code, message, details }) and empty matches, and is not counted; the others are one evaluation each. limit_per_company is 1 to 100 (default 10). The whole request is refused with match_quota_exceeded when its valid companies would take you past your allowance, and with plan_required when it has more companies than your plan allows in one request.

To match the same companies again whenever a measure changes, put them on a watchlist instead: re-evaluation is included.