Enrichir HubSpot avec les données du registre néerlandais

Les propriétés à créer

HubSpot fournit name, domain, city et numberofemployees. Ces champs contiennent ce que les commerciaux ont saisi ou ce que HubSpot a déduit d’un domaine de messagerie. Les données du registre n’ont rien à y faire. Créez vos propres propriétés, avec une provenance claire.

enriched_at ressemble à une lourdeur inutile jusqu’au jour où quelqu’un demande l’ancienneté des données. Sans horodatage, impossible de ré-enrichir de façon ciblée : vous ré-enrichissez tout chaque mois et vous percutez votre quota.

Le point d’intégration : workflow, action codée ou application privée

L’appel peut partir de trois endroits, qui diffèrent par leur coût et par ce qu’ils savent gérer.

Workflow avec une action webhook. Inscrivez les entreprises dont kvk_number est connu et enriched_at est vide. HubSpot envoie un POST à votre endpoint, vous effectuez la recherche et réécrivez via l’API CRM. Simple, et votre logique reste dans votre propre code.

Action codée. S’exécute dans HubSpot, sans serveur à vous. Exige Operations Hub Professional et hérite des limites d’exécution de cet environnement. Convient pour une recherche par enregistrement, mais pas pour un rattrapage de masse.

Application privée sur les webhooks CRM. Abonnez-vous à company.propertyChange pour kvk_number. L’enrichissement se déclenche alors dès que le numéro change, sur n’importe quelle offre. Le contenu de la requête est un tableau d’événements :

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

Traitez ce tableau de façon asynchrone. HubSpot regroupe les événements et attend un 2xx rapide : un gestionnaire qui reste bloqué sur notre API pendant un pic finit en délai dépassé, et HubSpot renvoie alors le même événement.

Réécrivez par lots, pas enregistrement par enregistrement :

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

avec au plus cent enregistrements par appel. De notre côté, cela s’associe à POST /v1/lookup/batch avec un corps { "kvkNumbers": [...], "enrich": true }. Les deux côtés restent ainsi dans leurs limites.

D’où vient la donnée d’entrée

Le numéro KvK doit entrer dans le CRM d’une manière ou d’une autre. Deux voies :

• Votre propre formulaire, avec notre widget branché sur le champ. Le visiteur cherche par nom, choisit une entreprise, et vous transmettez le numéro KvK à l’API Forms de HubSpot.
• La saisie manuelle par les commerciaux sur la fiche entreprise. Elle nécessite une validation ensuite, car un numéro tapé à la main est aussi fiable que n’importe quelle ressaisie manuelle.

Ce qui ne fonctionne pas : brancher le widget sur un formulaire HubSpot intégré qui s’affiche dans un iframe. Votre script ne peut pas atteindre ce champ. Vérifiez comment s’affiche votre intégration avant de promettre l’autocomplétion sur un formulaire HubSpot. Si c’est une iframe, construisez le formulaire vous-même et envoyez-le à l’API Forms.

Dans tous les cas, écrivez le numéro dans une propriété que seule votre intégration touche. Un champ modifié à la fois par les commerciaux et par une synchronisation devient une dispute sur la valeur correcte, et le registre perd toujours cette dispute face à la dernière personne qui a tapé.

Ce qui casse réellement en production

La déduplication par domaine écrase la structure de votre groupe. HubSpot utilise le domaine comme clé d’association automatique. Une holding, sa société opérationnelle et un point de vente franchisé partagent souvent le même site web. HubSpot se retrouve avec une seule entreprise là où vous avez trois numéros KvK. Faites votre propre déduplication sur kvk_number, pas sur le domaine, et acceptez d’avoir parfois deux fiches HubSpot sur le même domaine.

Le workflow se déclenche lui-même. Si vous inscrivez sur « kvk_number est connu » puis réécrivez des propriétés sur la même fiche, elle est réinscrite au changement suivant. Désactivez explicitement la réinscription et filtrez sur enriched_at is unknown.

Une entreprise renvoie 404. Les entrées radiées quittent le registre. Traitez NOT_FOUND comme une information plutôt que comme une erreur : mettez company_active à false et enriched_at à maintenant, sinon votre workflow la retente à chaque passage.

Le premier rattrapage avale votre quota mensuel. Enrichir cinq mille entreprises, c’est cinq mille recherches. Filtrez sur les enregistrements pour lesquels cela change réellement quelque chose et étalez le reste. HubSpot applique sa propre limite par tranche de dix secondes : des lots de cent enregistrements par appel respectent les limites des deux côtés.

Pour l’approche globale de l’enrichissement CRM, voir l’article complet : enrichissement des données d’entreprise dans le CRM.