Matching d'une entreprise

La requête#

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

Le corps est strict : une propriété que l’API ne connaît pas, où qu’elle se trouve, ou une valeur du mauvais type ou hors de sa liste, donne 400 invalid_parameter avec son nom, si bien qu’un turnover mal orthographié ne devient jamais une inconnue en silence. Une valeur lisible mais impossible (un code postal hors de Belgique, un numéro d’entreprise dont le chiffre de contrôle est faux, un montant négatif) donne 422 invalid_body avec la propriété dans details.field. Envoyez Content-Type: application/json.

Une information que vous ne donnez pas est inconnue, jamais supposée. C’est tout l’intérêt : au lieu d’un score assuré bâti sur des suppositions, la réponse indique quelles informations trancheraient pour chaque mesure.

company

project

options

Ce qui est déduit#

Les informations que vous n’avez pas données sont déduites, prudemment, de celles que vous avez données, et chaque déduction figure dans profile.derived avec les propriétés dont elle provient. estimate: true signale une déduction qui repose sur une hypothèse.

Catégories de taille

Recommandation 2003/361/CE : un plafond d’effectif et soit le plafond de chiffre d’affaires, soit celui du total du bilan. Une entreprise qui dépasse les plafonds financiers d’une catégorie passe à la catégorie supérieure.

Les entreprises partenaires et liées modifient les chiffres qu’utilise la définition, et l’API ne les voit pas. C’est l’une des raisons pour lesquelles un résultat dit « probable » et non « éligible ». Certaines mesures (le tax shelter belge, par exemple) appliquent plutôt le critère de taille du Code des sociétés et des associations ; leurs règles testent alors directement les chiffres : envoyez donc les chiffres, et pas seulement size.

Les quatre statuts#

Les règles de chaque mesure sont évaluées selon une logique à trois valeurs (pass, fail, unknown ; voir les règles d’éligibilité), et ce résultat, combiné à la qualité des règles de la mesure, donne le statut :

Les résultats sont triés par statut dans cet ordre, puis selon ce qui peut être demandé le plus tôt (ouvert, permanent, à venir, inconnu, suspendu, budget épuisé, clôturé), puis par score, puis par l’échéance la plus proche.

La réponse#

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

Valeurs d’exemple. Le résultat du tax shelter montre la logique à l’œuvre : son critère de taille est « deux critères sur trois », écrit comme un any de trois paires. La première paire est satisfaite, donc le total du bilan inconnu dans les deux autres n’a pas d’importance et n’est pas demandé ; l’âge de l’entreprise est inconnu et serait décisif, il est donc demandé.

L’estimation

Un calcul sur les chiffres publiés, à titre indicatif uniquement :

• Le taux est le palier le plus élevé de funding.rates pour la taille de l’entreprise, ou funding.rate_max si aucun palier ne cite cette taille.
• Le plafond est le plus bas de funding.amount_max et funding.annual_cap.
• Avec un budget de projet et un taux : budget × taux, plafonné. Sinon, s’il y a un plafond : le plafond, comme montant maximal. Sinon null.
• basis exprime le calcul en toutes lettres, dans votre langue (25 000 € × 40 %, plafonné à 7 500 €). Pour une mesure fiscale, le montant est l’ampleur de l’avantage que décrit le taux, pas un versement.

Ce que coûte un matching#

Chaque POST /v1/match compte pour une requête et une évaluation de matching, quel que soit le nombre de mesures évaluées. Une requête refusée pour des informations invalides n’est pas comptée comme évaluation. Les évaluations de matching ont leur propre quota mensuel : vous pouvez continuer à lire des mesures une fois celui-ci épuisé ; voir limites et quotas.

Matching en masse#

À partir de BusinessPOST /v1/match/bulk nécessite la capacité bulk_match.

De nombreuses entreprises en une seule requête : jusqu’à 500 avec Business et 5 000 avec Enterprise. Chacune porte votre propre reference (de 1 à 200 caractères, unique dans la requête), renvoyée telle quelle.

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

La réponse est { results, evaluated, language, disclaimer, meta }, un résultat par entreprise dans l’ordre de la requête : { reference, matches, matched, missing_information, error }. Une entreprise dont les informations sont invalides reçoit sa propre error ({ code, message, details }) et une liste de résultats vide, et n’est pas comptée ; les autres comptent chacune pour une évaluation. limit_per_company va de 1 à 100 (10 par défaut). La requête entière est refusée avec match_quota_exceeded si ses entreprises valides vous feraient dépasser votre quota, et avec plan_required si elle contient plus d’entreprises que votre formule n’en permet par requête.

Pour réévaluer les mêmes entreprises chaque fois qu’une mesure change, placez-les plutôt dans une liste de suivi : la réévaluation est incluse.