HubSpot-bedrijven verrijken met KVK-data

Welke properties je aanmaakt

HubSpot heeft name, domain, city en numberofemployees. Die zijn gevuld met wat sales heeft ingetypt of wat HubSpot uit een e-maildomein afleidde. Registerdata hoort daar niet doorheen. Maak eigen properties aan, met een duidelijke herkomst.

enriched_at lijkt overbodig tot het moment dat iemand vraagt hoe oud die data is. Zonder timestamp kun je niet selectief opnieuw verrijken en verrijk je dus elke maand alles, wat recht in je quota loopt.

Het integratiepunt: workflow, coded action of private app

Er zijn drie plekken waar de call vandaan kan komen, en ze verschillen in wat ze kosten en wat ze aankunnen.

Workflow met webhook-actie. Enroll bedrijven waar kvk_number bekend is en enriched_at leeg. HubSpot POST’t naar jouw endpoint, jij doet de lookup en schrijft terug via de CRM API. Simpel, en je logica staat in je eigen code.

Coded action. Draait in HubSpot zelf, geen eigen server nodig. Vraagt Operations Hub Professional, en je zit vast aan de uitvoeringslimieten van die runtime. Prima voor één lookup per record, niet voor een backfill.

Private app op CRM-webhooks. Je abonneert op company.propertyChange voor kvk_number. Dan gebeurt de verrijking op het moment dat het nummer verandert, ongeacht welk abonnement je hebt. De payload is een array van events:

[
  {
    "subscriptionType": "company.propertyChange",
    "objectId": 512,
    "propertyName": "kvk_number",
    "propertyValue": "68750110",
    "occurredAt": 1755820800000
  }
]

Verwerk die array asynchroon. HubSpot bundelt events en verwacht snel een 2xx: een handler die synchroon op onze API wacht, loopt in een piek tegen timeouts aan en HubSpot stuurt hetzelfde event dan opnieuw.

Terugschrijven doe je gebundeld, niet per record:

POST /crm/v3/objects/companies/batch/update

met maximaal honderd records per aanroep. Aan onze kant hoort daar POST /v1/lookup/batch bij, met { "kvkNumbers": [...], "enrich": true }. Zo blijven beide kanten binnen hun limiet.

Waar de invoer vandaan komt

Het KVK-nummer moet ergens binnenkomen. Twee routes:

• Je eigen formulier, met onze widget aan het inputveld. De bezoeker zoekt op naam, kiest een bedrijf, jij submit het KVK-nummer mee naar de HubSpot Forms API.
• Handmatig door sales, in het bedrijfsrecord. Dan is een validatie achteraf nodig, want een handmatig ingetypt nummer is precies zo betrouwbaar als het overtypen suggereert.

Wat niet werkt: de widget aan een ingesloten HubSpot-formulier hangen dat in een iframe rendert. Je script komt niet bij dat inputveld. Controleer eerst hoe jouw embed rendert voordat je autocomplete op een HubSpot-formulier belooft. Rendert het als iframe, dan bouw je het formulier zelf en verstuur je naar de Forms API.

Schrijf het nummer in beide gevallen naar een property die alleen jouw integratie aanraakt. Een veld dat zowel sales als een sync bewerkt, wordt een discussie over welke waarde klopt, en het register verliest die discussie altijd van wie het laatst heeft getypt.

Wat er in productie stukgaat

Domeindeduplicatie voegt je groepsstructuur samen. HubSpot gebruikt het domein als sleutel voor automatische koppeling. Een holding, een werkmaatschappij en een franchise-vestiging delen vaak één website. HubSpot houdt daar één bedrijf aan over, terwijl je er drie KVK-nummers voor hebt. Sleutel je eigen dedupe op kvk_number, niet op domein, en accepteer dat je in HubSpot soms twee records met hetzelfde domein wilt.

De workflow triggert zichzelf. Enrolt op “kvk_number is bekend” en schrijft daarna properties terug op hetzelfde record? Dan re-enrollt hij bij de volgende wijziging. Zet re-enrollment expliciet uit en filter op enriched_at is unknown.

Een bedrijf geeft 404. Uitgeschreven inschrijvingen verdwijnen uit het register. Behandel NOT_FOUND niet als fout maar als informatie: zet company_active op false en enriched_at op nu, anders probeert je workflow het elke run opnieuw.

De eerste backfill eet je maandquota op. Vijfduizend bedrijven verrijken is vijfduizend lookups. Filter eerst op de records waar het daadwerkelijk iets oplevert, en spreid de rest. HubSpot rekent zijn eigen limiet per tien seconden af, dus een batch van honderd records per call houdt beide kanten kalm.

Voor de bredere aanpak van CRM-verrijking staat er een uitgebreider stuk in CRM company data enrichment.