Aan de slag met de FirmTrove API en MCP

Maak een gratis FirmTrove-account en maak bij Koppelingen een toegangssleutel. Gebruik die sleutel voor REST-verzoeken of voeg het MCP-eindpunt toe aan je AI-assistent.

Alles in deze handleiding is uitgevoerd met een gratis testaccount tegen het gehoste product. Sleutels zijn weggelaten. Dezelfde limieten en labels gelden als in de browser.

Stap 1: account en sleutel

1. Maak een gratis account op app.firmtrove.nl en bevestig je e-mailadres via de link die je ontvangt.
2. Ga naar Mijn account → Koppelingen en maak een sleutel met een herkenbare naam. De sleutel begint met ft_live_, wordt één keer getoond en wordt gehasht opgeslagen. Maximaal vijf actieve sleutels; intrekken werkt per direct.

Stap 2: een REST-zoekopdracht

curl -s -H "Authorization: Bearer ft_live_…" \
  "https://app.firmtrove.nl/api/companies?q=software&limit=1"

Antwoord op de testdag: {"total":282,"items":[…],"page":1,"limit":1}. Elk item bevat de velden, een provenance-object per veld (bron, beleidsversie, waarnemingsdatum, vervaldatum, bewijs, vermelding, label), een lijst signals en een lijst withheld. Zoeken vereist minimaal drie tekens en doorzoekt naam en plaats; filter op sector met een categorie uit /api/facets.

Stap 3: een export

curl -s -X POST https://app.firmtrove.nl/api/exports \
  -H "Authorization: Bearer ft_live_…" -H "Content-Type: application/json" \
  -d '{"companyIds":["flintlead:454977"],"idempotencyKey":"mijn-selectie-2026-09-11"}'

Antwoord: {"id":"…","count":1,"remaining":99,"downloadUrl":"/api/exports/…"}. Dezelfde sleutel met dezelfde selectie geeft dezelfde export terug (replayed:true) zonder je tegoed opnieuw te belasten; dezelfde sleutel met een andere selectie geeft 409 idempotency_conflict. Het CSV-bestand begint met de bronvermelding en bevat de kolommen id, name, city, province, sector, website, email, description, provenance en withheld.

Stap 4: MCP vanuit een AI-assistent

Het eindpunt is POST https://app.firmtrove.nl/mcp (JSON-RPC 2.0, protocolversie 2025-03-26) met dezelfde Bearer-sleutel. Er is geen streaming-transport. Configureer je client met dat eindpunt en de header; het MCP-protocol zelf heeft geen tweede taalmodel nodig. De zes tools:

• firmtrove_search_companies (q, sector, province)
• firmtrove_get_company (id)
• firmtrove_market_size (sector, province)
• firmtrove_find_similar (id)
• firmtrove_export (companyIds, idempotencyKey)
• firmtrove_dataset_info

{"jsonrpc":"2.0","id":4,"method":"tools/call",
 "params":{"name":"firmtrove_search_companies","arguments":{"q":"installatie"}}}

Geteste uitkomst: 1.608 records, twaalf items op de eerste pagina, eerste item “Bakker Installatietechniek B.V.”. firmtrove_dataset_info gaf het aantal beschikbare records met de labelverdeling en de exportniveaus none en attribution.

Limieten en foutcodes

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 export geldt maximaal 5.000 rijen voor Pro en 100 voor Free, binnen het resterende tegoed. Het tegoed vernieuwt op de eerste dag van de kalendermaand en ongebruikte rijen vervallen. Bestaande betaalde accounts behouden 25.000 rijen per kalendermaand.

Wat nog niet kan

Geen streaming (SSE) voor MCP, geen OAuth-koppeling voor assistenten (alleen Bearer-sleutels), geen provinciefilter met inhoud, en geen XLSX-export. Alles wat hier staat is getest; wat hier niet staat, is niet toegezegd.

De volledige velddictionary staat op de API-pagina.

Welke limieten gelden voor je eerste export?

Free geeft 100 exportrijen per maand. Pro kost €29 per maand exclusief btw en geeft 5.000 tot 25.000 rijen per kalendermaand. De abonnementen bepalen hoeveel je kunt meenemen.

Hoe controleer je de uitkomst van een zoekopdracht?

Open dezelfde selectie in het product en vergelijk de bedrijfsnamen. De documentatie voor ontwikkelaars beschrijft de verzoeken. Voor een controle van een inschrijving zoek je het bedrijf rechtstreeks op bij KVK.

Veelgestelde vragen

Kan ik gratis beginnen?

Ja. Free heeft 100 exportrijen per kalendermaand en toegang tot REST en MCP.

Waar maak ik een toegangssleutel?

Ga naar Mijn account en open Koppelingen. Bewaar de sleutel in een geheimenbeheerder.

Hoeveel sleutels kan ik hebben?

Je kunt maximaal 5 actieve sleutels per account hebben. Je kunt een sleutel direct intrekken.

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.

Meer van dit soort uitleg in je Google-resultaten? Zet FirmTrove als voorkeursbron.