Gratis starten
Producten BedrijfsherkenningWidgetFlows en leadformulierenMeldingen Oplossingen SalesMarketingBureaus Middelen HulpcentrumScript installerenPrivacy en AVG Meer Prijzen Integraties Inloggen
Hulpcentrum › Meldingen en koppelingen

API, webhooks en MCP

Gegevens ophalen met de REST API, gebeurtenissen ontvangen met webhooks en Leadspotr koppelen aan AI-assistenten.

Met de API, webhooks en MCP koppel je Leadspotr aan je eigen systemen en aan AI-assistenten. Je beheert ze bij /admin/developers. De volledige documentatie staat in de app, onder Documentatie op die pagina.

Een token maken

Voor de API en MCP heb je een token nodig. Een token hoort bij je workspace.

  1. Ga naar /admin/developers.
  2. Vul een naam in, bijvoorbeeld CRM-sync.
  3. Kies de rechten (scopes) die nodig zijn:
Recht Wat
companies:read Bedrijven en bedrijfskaarten lezen
visits:read Bezoeken lezen
leads:read Leads lezen (persoonsgegevens)
leads:write Leads aanmaken (identify)
sites:read Sites, snippet en trackingdomein lezen
sites:write Sites en trackingdomein beheren
  1. Klik op Token maken en kopieer het token. Je ziet het maar één keer.

Geef een token alleen de rechten die echt nodig zijn. Met Intrekken maak je een token direct ongeldig. Alleen de eigenaar van de workspace kan tokens maken en intrekken.

REST API

  • Base URL: https://app.leadspotr.nl/api/v1
  • Authenticatie: Authorization: Bearer <token> en Accept: application/json
  • Limiet: 120 verzoeken per minuut per workspace

Endpoints

Endpoint Recht Wat
GET /me – Workspace en rechten van het token
GET /companies companies:read Herkende bedrijven met bezoeken, pagina's en score. Standaard de laatste 7 dagen. Filters: from, to, confidence=high|medium, per_page.
GET /companies/{id} companies:read Bedrijfskaart met de bezoeken in je workspace
GET /companies/lookup?domain=… companies:read Bedrijfskaart op domein. Onbekend: 202, de kaart wordt gemaakt. Probeer het later opnieuw.
GET /visits visits:read Bezoeken met kanaal, campagne en pagina's. Standaard vandaag. Filters: from, to, company_id, identified=1.
GET /leads, GET /leads/{id} leads:read Leads. Filter: updated_since.
POST /identify leads:write Lead aanmaken of bijwerken, bijvoorbeeld vanuit je CRM
GET /sites, GET /sites/{id} sites:read Sites met snippet, installatiestatus en trackingdomein
POST /sites, PATCH /sites/{id} sites:write Site aanmaken of wijzigen, binnen de sitelimiet van je plan
PUT /sites/{id}/tracking-domain sites:write Eigen trackingdomein instellen. null haalt het weg.
POST /sites/{id}/tracking-domain/check sites:write Trackingdomein opnieuw controleren

Voorbeeld

Bedrijven met hoge betrouwbaarheid ophalen:

curl "https://app.leadspotr.nl/api/v1/companies?confidence=high" \
  -H "Authorization: Bearer $LEADSPOTR_TOKEN" \
  -H "Accept: application/json"

Een lead doorgeven vanuit je eigen systeem:

curl -X POST "https://app.leadspotr.nl/api/v1/identify" \
  -H "Authorization: Bearer $LEADSPOTR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "Jan Jansen", "company": "Bedrijf B.V.", "form": "Webinar", "consent": true}'

consent is verplicht. Daarmee bevestig je dat deze persoon toestemming gaf.

Webhooks

Een webhook stuurt een bericht naar jouw systeem zodra er iets gebeurt. Handig voor Zapier, Make, n8n of je eigen backend.

Gebeurtenissen

Event Wanneer
company.identified Bedrijf herkend (score middel of hoog), één keer per bedrijf per dag
lead.created Nieuwe lead
form.submitted Formulier met bedrijfsgegevens
label.added Label toegekend aan een bedrijf of lead
widget.request Aanvraag via de widget (bel mij, afspraak, bericht, flow, chat)
ping Testbericht

Een webhook toevoegen

  1. Ga naar /admin/developers, onder Webhooks.
  2. Vul de URL in, bijvoorbeeld https://jouw-app.nl/webhooks/leadspotr.
  3. Kies de events en klik op Webhook toevoegen.
  4. Klik op Testbericht om een ping te sturen.

Wat je ontvangt

Elke webhook is een POST met JSON:

{
  "id": "…",
  "event": "company.identified",
  "created_at": "…",
  "workspace": "…",
  "data": { … }
}

Antwoord met een 2xx-status. Anders proberen we het opnieuw, tot 5 keer: na 1, 5, 15 en 60 minuten. Na 20 mislukte afleveringen op rij gaat de webhook uit. Bij /admin/developers zie je de laatste status en hoe vaak het mislukte. Met Aanzetten zet je hem weer aan.

De handtekening controleren

Elk bericht heeft een header Leadspotr-Signature: t=<timestamp>,v1=<hmac>. De v1 is een HMAC-SHA256 met het geheim van de webhook over "<timestamp>.<ruwe body>". Het geheim vind je bij de webhook, onder Geheim voor de handtekening.

Weiger berichten met een ongeldige handtekening of een timestamp ouder dan 5 minuten. In PHP:

[$t, $v1] = sscanf($request->header('Leadspotr-Signature'), 't=%d,v1=%s');
$expected = hash_hmac('sha256', $t.'.'.$request->getContent(), $secret);
abort_unless(hash_equals($expected, $v1) && abs(time() - $t) < 300, 401);

In Node.js:

const crypto = require('crypto');

function verify(header, rawBody, secret) {
  const [, t, v1] = header.match(/t=(\d+),v1=([a-f0-9]+)/) || [];
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && v1 && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Gebruik de ruwe body, niet de JSON nadat die is ingelezen en opnieuw opgebouwd.

MCP (AI-assistenten)

Met MCP (Model Context Protocol) kan een AI-assistent zelf in Leadspotr zoeken. Je vraagt dan bijvoorbeeld: "Welke bouwbedrijven bekeken deze week onze prijzenpagina?"

  • Adres: https://app.leadspotr.nl/mcp (Streamable HTTP)
  • Authenticatie: hetzelfde token als de API, als header Authorization: Bearer <token>

Voeg in je MCP-client een server van het type HTTP toe met deze gegevens:

Naam:    leadspotr
URL:     https://app.leadspotr.nl/mcp
Header:  Authorization: Bearer <jouw token>

Waar je dit invult, verschilt per client. Kijk in de documentatie van je AI-assistent bij MCP-servers toevoegen.

Beschikbare tools:

Tool Wat
search_companies Herkende bedrijven zoeken
get_company Een bedrijfskaart met bezoeken
recent_visits Recente bezoeken
list_leads Leads
lookup_domain Een bedrijfskaart op domein
list_sites Je sites
create_site Een site aanmaken
set_tracking_domain Een eigen trackingdomein instellen
check_tracking_domain Een trackingdomein controleren

De tools geven alleen terug wat de rechten van het token toestaan. Wil je dat de assistent alleen bedrijven ziet en geen persoonsgegevens? Maak dan een token met alleen companies:read en visits:read.

Tip: maak voor elke koppeling een eigen token. Dan zie je bij /admin/developers welk token wanneer is gebruikt, en kun je er één intrekken zonder de rest te raken.

VorigeHubSpot en Pipedrive koppelen