Aan de slag
- Maak een gratis account op app.firmtrove.nl en bevestig je e-mailadres.
- Maak onder Mijn account → Koppelingen een toegangssleutel. De sleutel wordt één keer getoond, wordt gehasht opgeslagen en is per direct in te trekken. Maximaal vijf actieve sleutels per account.
- Stuur de sleutel mee als
Authorization: Bearer ft_live_…. Sleutels horen in een geheimenbeheerder, nooit in een URL of in clientcode.
Koppel je AI-agent
Zet je sleutel in een omgevingsvariabele en verwijs ernaar. Let op de enkele aanhalingstekens bij Claude Code: zo bewaart Claude de verwijzing en niet de sleutel zelf. Controleer daarna met claude mcp get firmtrove of de status Connected is.
Claude Code
export FIRMTROVE_KEY=ft_live_…
claude mcp add --transport http firmtrove https://app.firmtrove.nl/mcp \
--header 'Authorization: Bearer ${FIRMTROVE_KEY}'
Daarna stel je gewoon je vraag. Claude kiest zelf de juiste FirmTrove-tool.
Codex
export FIRMTROVE_KEY=ft_live_…
codex mcp add firmtrove --url https://app.firmtrove.nl/mcp \
--bearer-token-env-var FIRMTROVE_KEYcodex mcp list toont de koppeling. De sleutel zelf staat alleen in je omgeving.
Cursor
Zet dit in .cursor/mcp.json:
{ "mcpServers": { "firmtrove": {
"url": "https://app.firmtrove.nl/mcp",
"headers": { "Authorization": "Bearer ${env:FIRMTROVE_KEY}" }
} } }De zes tools
firmtrove_search_companies: zoeken op naam, sector, provincie, postcode, oprichtingsjaar en beschikbaarheid van website, telefoon of zakelijk e-mailadresfirmtrove_get_company: één bedrijf met alle velden die je mag zienfirmtrove_market_size: aantallen per sector en provinciefirmtrove_find_similar: vergelijkbare bedrijven met redenfirmtrove_export: een CSV binnen je exportlimietfirmtrove_dataset_info: stand en labels van de database
REST
Basis-URL https://app.firmtrove.nl. Alle antwoorden zijn JSON. Limieten en labels zijn gelijk aan de browser.
| Aanroep | Parameters | Antwoord |
|---|---|---|
GET /api/companies | q (minimaal 3 tekens; zoekt in naam en plaats), sector, province, signal (tender, grant, timely), postcode (PC4-prefix of exacte PC6 van de gekozen bronwaargenomen bedrijfslocatie), foundedFrom, foundedTo (inclusieve bronvermelde jaartallen), email=business_available, website=available, phone=available, page, limit (max 50), cursor uit het vorige begrensde resultaat | {total, items[], page, limit, hasMore, nextCursor}; total is null bij postcode-, oprichtingsjaar- en beschikbaarheidsfilters |
GET /api/companies/:id | id zoals firmtrove:126726 | het record met optionele postcode van een bedrijfslocatie, bronvermeld oprichtingsjaar, overige velden, signals en withheld |
GET /api/companies/:id/similar | {items[]} met reasons | |
GET /api/facets | zoekfilters zonder postcode, oprichtingsjaar of website-, telefoon- of e-mailbeschikbaarheid | {total, sectors[], provinces[]} |
POST /api/exports | {companyIds[], idempotencyKey} (max 5.000 ids voor Pro, 100 voor Free; dezelfde sleutel geeft dezelfde export terug) | {id, count, remaining, downloadUrl} |
GET /api/exports/:id | CSV (UTF-8, bronvermelding op regel 1) | |
GET /api/suppressions | {people[], items[]}: mensen die zich lieten verwijderen, als sha256 van het e-mailadres in kleine letters of van het telefoonnummer in cijfers met landcode (31612345678); verwijder of onderdruk ze ook bij jou |
MCP
Eindpunt POST https://app.firmtrove.nl/mcp, JSON-RPC 2.0, protocolversie 2025-03-26, dezelfde Bearer-sleutel. Methoden: initialize, ping, tools/list, tools/call. Er is geen streaming-transport; GET geeft 405.
| Tool | Argumenten | Geeft terug |
|---|---|---|
firmtrove_search_companies | q, sector, province, postcode, foundedFrom, foundedTo, email, website, phone, cursor | zoekresultaat zoals REST |
firmtrove_get_company | id | één record |
firmtrove_market_size | sector, province | aantallen per categorie |
firmtrove_find_similar | id | vergelijkbare records |
firmtrove_export | companyIds, idempotencyKey | exportbon met downloadUrl |
firmtrove_removed_people | geen | dezelfde lijst als people in GET /api/suppressions |
firmtrove_dataset_info | geen | available, shareRisk, exportRiskLevels, asOf |
Iemand benaderen
Zet in je eerste bericht aan iemand uit FirmTrove deze zin (artikel 10 van de voorwaarden):
Ik vond uw gegevens via FirmTrove (firmtrove.com). Wilt u daar niet in staan? Via firmtrove.com/sta-ik-erin laat u zich met één klik verwijderen.
Een echte aanroep
Met de API-sleutel van een gratis account.
curl -s -X POST https://app.firmtrove.nl/mcp \
-H "Authorization: Bearer ft_live_…" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"firmtrove_dataset_info","arguments":{}}}'
curl -s -H "Authorization: Bearer ft_live_…" "https://app.firmtrove.nl/api/companies?q=software&province=Utrecht"
{"total":87,"items":[{"id":"firmtrove:126726","name":"Bulxoft Software","city":"Lexmond",
"website":"https://bulxoft.com","province":"Utrecht","shareRisk":"attribution",
"withheld":[{"field":"sector","reason":"source_redistribution_not_approved"}, …]}, …],"page":1,"limit":12}KVK API kosten naast de FirmTrove API
De FirmTrove API is niet de KVK API. De KVK API levert gegevens uit het Handelsregister en kost €6,40 per maand, plus €0,02 per opgevraagd basisprofiel; zoeken is gratis. De FirmTrove API doorzoekt 4.306.825 bedrijfsrecords, waarvan 2.957.640 met KVK-nummer. Free geeft 100 exportrijen per maand, Pro kost €29 per maand exclusief btw en start met 5.000 rijen per kalendermaand, met +2.500 per opeenvolgende betaalde maand tot 25.000. Pro Jaar kost €290 exclusief btw vooraf en heeft 25.000 rijen per kalendermaand vanaf dag één. Heb je het officiële registerprofiel per KVK-nummer nodig, dan is de KVK API de juiste bron.
Limieten en fouten
De postcode is een bronwaargenomen bedrijfslocatie en kan afwijken van het officiële vestigingsadres. Plaats, provincie en postcode kunnen uit onafhankelijk onderbouwde velden komen en vormen samen geen bevestigd geregistreerd adres. Het oprichtingsjaar is de waarde die de bron opgeeft en bewijst geen juridische oprichtings- of inschrijvingsdatum. De zakelijke e-mailfilter vindt alleen het exacte adres dat via de standaard API-, MCP- en CSV-levering beschikbaar is; persoonlijke mailboxen en de aparte exportkeuze daarvoor vallen buiten dit filter.
- CSV, REST en MCP delen je maandtegoed. Browserweergaven kosten geen rijen. Elke rij van een nieuwe CSV-export telt mee; geleverde REST- en MCP-ID’s tellen één keer per UTC-kalendermaand. Per export geldt maximaal 5.000 rijen voor Pro en 100 voor Free, binnen je resterende tegoed. Een zoekopdracht toont maximaal 10.000 resultaten. Postcode-, oprichtingsjaar- en beschikbaarheidsfilters geven een ondergrens en een cursor, geen exact totaal.
401 login_requiredontbrekende of ingetrokken sleutel ·400 search_too_short·400 postcode_filter_invalid·400 founding_year_filter_invalid·400 search_depthverfijn je filters ·400 availability_count_unsupported·400 availability_cursor_required·400 export_too_large·429 quota_exhausted·429 machine_record_quota·409 idempotency_conflictzelfde sleutel, andere selectie ·410 export_withdrawneen bedrijf uit de export is later verwijderd- Per account gelden 30 zoekopdrachten en 60 detailaanvragen per minuut; per IP-adres vier keer die grenzen. Browser, REST en MCP delen deze grenzen. Bij overschrijding beperken we eerst de aanvragen. De derde hernieuwde overtreding blokkeert het account tot handmatige beoordeling; er is geen automatische vrijgave. Volg bij 429 de wachttijd in Retry-After.
Velden
| Veld | Betekenis | Herkomst van de datum |
|---|---|---|
name, city, province, website, size | identiteit van het record | nieuwste bronvermelding van het record |
postcode | bronwaargenomen bedrijfslocatie; kan afwijken van het officiële vestigingsadres | waarnemingsdatum van de gekozen bron |
foundedYear | oprichtingsjaar volgens de bron; geen bewijs van juridische oprichting of inschrijving | waarnemingsdatum van de gekozen bron |
sector | categorie van de bron | nieuwste bronvermelding met categorie |
description, phone | letterlijk citaat van de eigen website | eigen waarnemingsdatum en vervaldatum |
email | zakelijke mailbox in standaardlevering; persoonlijke mailboxen hebben een aparte exportkeuze | verificatiedatum |
signals[] | kind tender, grant of timely met waarde | eigen waarnemingsdatum en vervaldatum |
shareRisk | deelrisico van het record: none of attribution | |
withheld[] | velden die niet geleverd zijn, met reden |
Je gedeelde maandtegoed
Pro: €29 per maand excl. btw. Start met 5.000 rijen, elke opeenvolgende betaalde maand +2.500, tot 25.000 per kalendermaand. Pro Jaar: €290 excl. btw vooraf, met 25.000 per kalendermaand vanaf dag één.
Free heeft 100 rijen per kalendermaand. CSV, REST en MCP delen één tegoed per account, ook met teamleden en meerdere sleutels. Iedere geëxporteerde CSV-rij telt, ook bij een nieuwe export van hetzelfde bedrijf. Via REST en MCP telt een geleverd bedrijfs-ID één keer per kalendermaand, ongeacht de sleutel of aanroep. In de volgende maand telt dat ID opnieuw. Een bestaande export opnieuw downloaden kost geen extra rijen. Zoeken, filteren en bedrijfsrecords bekijken in de browser verbruikt geen tegoed; daarvoor gelden snelheidsgrenzen. Per account gelden 30 zoekopdrachten en 60 detailaanvragen per minuut; per IP-adres gelden vier keer die grenzen. Browser, REST en MCP delen deze snelheidsgrenzen. Bij overschrijding beperken we eerst de aanvragen. De derde hernieuwde overtreding blokkeert het account tot handmatige beoordeling; er is geen automatische vrijgave. Per export geldt maximaal 5.000 rijen voor Pro en 100 voor Free, binnen het resterende tegoed. Het tegoed vernieuwt om 00:00 UTC op de eerste dag van de kalendermaand en ongebruikte rijen vervallen. Bestaande betaalde accounts behouden 25.000 rijen per kalendermaand.