Watchlists

Business en hogerWatchlists vragen de functie watchlists. Tot 50 watchlists per account; het aantal ondernemingen over alle watchlists samen hangt af van het plan (5.000 op Business, onbeperkt op Enterprise).

Een watchlist aanmaken#

$ curl -X POST "https://api.subsido.be/v1/watchlists" \  -H "Authorization: Bearer sb_live_..." \  -H "Content-Type: application/json" \  -d '{"name": "Clients Gent", "language": "nl", "options": {"statuses": ["open", "continuous", "forthcoming"]}}'

201 met de watchlist: { id, name, options, language, companies, matches, created_at, updated_at, last_evaluated_at }, waarbij id de vorm wl_… heeft, companies het aantal ondernemingen erop telt en matches de huidige matches die niet not_eligible zijn.

Ondernemingen toevoegen#

$ curl -X POST "https://api.subsido.be/v1/watchlists/wl_06f8r9t2b4c6d8e0f2g4h6j8km/companies" \  -H "Authorization: Bearer sb_live_..." \  -H "Content-Type: application/json" \  -d '{"companies": [        {"reference": "client-0042", "company": {"postcode": "9000", "employees": 12, "turnover_eur": 1500000, "legal_form": "bv", "nace": ["62.010"]}},        {"reference": "client-0043", "company": {"postcode": "98200", "legal_form": "eenmanszaak"}, "project": {"topics": ["energy_efficiency"]}}      ]}'

• 1 tot 1.000 ondernemingen per request. Elke onderneming krijgt je eigen reference (1 tot 200 tekens), en company en project nemen precies dezelfde eigenschappen als een matchrequest.
• Een referentie die al op de watchlist staat, wordt vervangen en telt niet opnieuw mee voor het maximum aantal ondernemingen van je plan.
• Een onderneming met ongeldige gegevens, een dubbele of een lege referentie wordt afzonderlijk geweigerd; de rest wordt aanvaard.
• Elke aanvaarde onderneming wordt geëvalueerd voordat de call terugkomt, tegen dezelfde maatregelen als /v1/match, en telt als één match-evaluatie. De hele request wordt geweigerd met match_quota_exceeded als de aanvaarde ondernemingen je over je maandelijkse hoeveelheid zouden brengen, en met plan_required als ze het account boven het maximum aantal ondernemingen zouden brengen.

{
  "watchlist_id": "wl_06f8r9t2b4c6d8e0f2g4h6j8km",
  "added": 1,
  "replaced": 0,
  "rejected": [
    {
      "reference": "client-0043",
      "error": {
        "code": "invalid_body",
        "message": "company.postcode: company.postcode is not a Belgian postcode",
        "details": {
          "field": "company.postcode"
        }
      }
    }
  ],
  "matches": 7,
  "meta": {
    "request_id": "req_0192d3a4b5c67d8e9f0a1b2c3d4e5f63",
    "warnings": []
  }
}

matches telt de matches van de aanvaarde ondernemingen die niet not_eligible zijn. De tweede onderneming werd geweigerd om een postcode van vijf cijfers; de eerste werd toegevoegd en gematcht.

De matches lezen#

$ curl "https://api.subsido.be/v1/watchlists/wl_06f8r9t2b4c6d8e0f2g4h6j8km/matches?company=client-0042" \  -H "Authorization: Bearer sb_live_..."

Het antwoord is { data, meta, disclaimer }. Elke rij is { company_reference, subsidy_id, match_status, score, result, subsidy_version, first_matched_at, updated_at }, waarbij result de match is zoals /v1/match hem berekent (status, zekerheid, relevantie, redenen, onbekenden, raming), zonder de samenvatting van de maatregel: die lees je met GET /v1/subsidies/{id}. subsidy_version is de versie waartegen geëvalueerd werd.

Herevaluatie en events#

We evalueren een watchlist opnieuw zodra een maatregel die kan matchen of een van haar ondernemingen veranderd is sinds de laatste evaluatie (last_evaluated_at). Die herevaluatie op de achtergrond zit in het plan en telt nooit als match-evaluatie. Elk verschil wordt een event:

Match-events horen bij de eigenaar van de watchlist. Ze gaan alleen naar de webhooks van dat account (filter ze met watchlists of event_types) en verschijnen nooit in de publieke change feed.

{
  "id": "chg_06f8s2m4d2a9b1c7e3g5h8j0kn",
  "event": "match.created",
  "created_at": "2026-09-27T07:00:03+02:00",
  "data": {
    "subject": "match",
    "id": "wl_06f8r9t2b4c6d8e0f2g4h6j8km:client-0042:federal:investeringsaftrek",
    "version": null,
    "categories": [
      "match.created"
    ],
    "diff": {},
    "summary": {
      "watchlist_id": "wl_06f8r9t2b4c6d8e0f2g4h6j8km",
      "company_reference": "client-0042",
      "subsidy_id": "federal:investeringsaftrek",
      "match_status": "likely_eligible",
      "previous_status": null,
      "subsidy": {
        "title": {
          "nl": "Investeringsaftrek",
          "fr": "Déduction pour investissement",
          "en": "Investment deduction",
          "de": null
        },
        "status": "continuous",
        "instrument_type": "tax_deduction",
        "issuer": "FOD Financiën",
        "closes_at": null,
        "regions": [],
        "topics": [
          "investment",
          "digitalisation"
        ],
        "url": "https://financien.belgium.be/nl/ondernemingen/vennootschapsbelasting/belastingvoordelen/investeringsaftrek",
        "source_id": "curated_federal"
      }
    }
  }
}

Wat we bewaren#