L'API HubSpot permet de lire, créer et modifier presque toutes les données du CRM (contacts, entreprises, transactions, tickets, objets personnalisés, produits, activités) depuis un autre logiciel, et d'être prévenu en temps réel des changements grâce aux webhooks. L'accès se fait par une app privée (jeton d'accès) pour une intégration propre à votre portail, ou par OAuth pour une application installée sur plusieurs portails. Avant de développer, vérifiez toujours qu'un connecteur existant ne couvre pas déjà votre besoin.
Ce guide s'adresse aux DSI, responsables CRM et chefs de projet qui doivent décider comment relier HubSpot au reste du système d'information.
L'API HubSpot en bref : objets, endpoints, authentification
L'API HubSpot est une API REST qui échange des données au format JSON. Elle est organisée en grandes familles :
| Famille | Ce qu'elle permet | Exemples d'usage |
|---|---|---|
| Objets CRM | Lire, créer, mettre à jour, archiver contacts, entreprises, transactions, tickets, produits, lignes de produits, devis, objets personnalisés | Créer un client depuis l'ERP, mettre à jour un statut de commande |
| Associations | Relier les enregistrements entre eux, avec des libellés d'association | Rattacher un contact à plusieurs entreprises avec un rôle |
| Recherche | Filtrer les enregistrements selon leurs propriétés | Retrouver une entreprise par son SIREN avant de la créer |
| Propriétés et schémas | Créer des propriétés et des objets personnalisés par programme | Déployer un modèle de données identique sur plusieurs portails |
| Engagements | Enregistrer emails, appels, réunions, notes, tâches | Historiser les appels d'un outil de téléphonie |
| Marketing et CMS | Formulaires, emails, listes, pages, blog, HubDB | Alimenter une table HubDB depuis un catalogue externe |
| Imports et exports | Charger ou extraire de gros volumes | Reprise de données lors d'une migration |
Côté authentification, les anciennes clés d'API ne sont plus utilisées. Deux mécanismes coexistent : le jeton d'accès d'une app privée, créé dans les paramètres du portail avec des droits limités aux périmètres nécessaires, et OAuth, utilisé par les applications publiques et les connecteurs de la marketplace. Dans tous les cas, appliquez le principe du moindre privilège : une intégration qui ne fait que lire les transactions n'a pas besoin de droits d'écriture sur les contacts.
Apps privées, OAuth et webhooks
Les apps privées
C'est le choix par défaut pour une intégration propre à votre entreprise : un connecteur maison entre HubSpot et votre ERP, un script de synchronisation, un entrepôt de données. Le jeton est lié au portail, les périmètres sont choisis finement, et l'activité est journalisée. Le jeton doit être stocké dans un coffre de secrets, jamais dans le code, et renouvelé régulièrement.
OAuth et les applications publiques
OAuth s'impose quand une même application doit être installée sur plusieurs portails, par exemple un éditeur de logiciel qui veut proposer une intégration HubSpot à ses clients. L'utilisateur autorise l'application, qui reçoit un jeton propre à chaque portail.
Les webhooks
Plutôt que d'interroger HubSpot toutes les minutes pour savoir si quelque chose a changé, les webhooks envoient une notification à votre serveur quand un enregistrement est créé, modifié ou supprimé. Ils réduisent le nombre d'appels et rendent la synchronisation quasi instantanée. Dans les workflows, l'action « envoyer un webhook » permet aussi de déclencher un appel vers un système externe à une étape précise d'un processus, par exemple à la signature d'une transaction.
Limites d'appels et bonnes pratiques
HubSpot limite le nombre d'appels pour protéger la plateforme. Selon la documentation officielle des limites d'usage, une app privée est limitée à 190 requêtes par tranche de 10 secondes sur les éditions Professional et Enterprise, avec un plafond quotidien par portail qui dépend de l'édition ; les applications publiques OAuth sont limitées à 110 requêtes par 10 secondes et par portail installé. Un module complémentaire permet de relever ces plafonds pour les apps privées.
Dans la pratique, ces limites sont rarement un problème si l'intégration est bien conçue :
- utilisez les endpoints par lots (batch) pour créer ou modifier jusqu'à plusieurs dizaines d'enregistrements en un appel ;
- préférez les webhooks à l'interrogation répétée ;
- ne synchronisez que les propriétés utiles et seulement quand elles changent ;
- gérez les erreurs 429 (trop de requêtes) avec une reprise progressive ;
- recherchez avant de créer, sur une clé unique (identifiant ERP, SIREN, email), pour éviter les doublons ;
- journalisez chaque échange pour pouvoir diagnostiquer un écart de données.
Pensez aussi au versionnement : HubSpot fait évoluer son API et publie des versions datées. Prévoyez dans votre contrat de maintenance la veille sur les dépréciations annoncées.
À retenir
- L'API HubSpot couvre objets CRM, associations, recherche, engagements, marketing et CMS.
- App privée pour une intégration propre à votre portail, OAuth pour une application installée chez plusieurs clients.
- Les webhooks évitent l'interrogation répétée et accélèrent la synchronisation.
- Appels par lots, clé unique de rapprochement et gestion des erreurs : trois réflexes pour une intégration robuste.
- Avant de développer, vérifiez si un connecteur ou une plateforme d'intégration couvre le besoin.
API, connecteur natif ou iPaaS : comment choisir
Le développement par API n'est qu'une des trois options. Le bon choix dépend de la spécificité du besoin et de votre capacité à maintenir le code.
| Option | Quand la choisir | Limites |
|---|---|---|
| Connecteur de la marketplace | Outil courant (messagerie, téléphonie, e-commerce, comptabilité), besoins standards | Mapping et règles parfois peu personnalisables |
| Plateforme d'intégration (iPaaS) | Plusieurs systèmes à orchestrer, transformations de données, équipe sans développeurs dédiés | Abonnement supplémentaire, logique répartie dans un outil tiers |
| Développement par API | Règles métier spécifiques, gros volumes, besoin de contrôle total | Hébergement, supervision et maintenance à assurer |
Commencez toujours par explorer les applications intégrables à HubSpot : beaucoup de besoins sont déjà couverts. Notre article pour connecter vos outils au CRM HubSpot présente les intégrations les plus courantes.
Trois intégrations types menées par API
1. ERP vers HubSpot
Remonter dans HubSpot les clients, commandes, factures et encours d'un ERP, et créer dans l'ERP les clients gagnés. L'API des objets et des associations, couplée aux webhooks, permet une synchronisation fiable dans les deux sens. Notre guide pour connecter HubSpot à votre ERP détaille l'architecture.
2. Produit SaaS vers HubSpot
Envoyer dans HubSpot les données d'usage d'un logiciel (activation, connexions, fonctions utilisées) pour déclencher des actions commerciales ou de succès client. Les propriétés calculées et un objet personnalisé « abonnement » structurent ces données.
3. HubSpot vers un entrepôt de données
Exporter les données CRM vers un entrepôt pour croiser ventes, finance et produit dans un outil de BI. Selon le volume, l'API, la synchronisation de données de Data Hub (ex-Operations Hub) ou un connecteur d'entrepôt seront plus adaptés.
FAQ
L'API HubSpot est-elle disponible sur toutes les éditions ?
Oui, l'API est accessible sur toutes les éditions, y compris gratuite, mais les données accessibles dépendent des fonctions incluses dans votre abonnement. Par exemple, les objets personnalisés ne sont disponibles que sur les éditions Enterprise.
Faut-il un développeur pour utiliser l'API HubSpot ?
Pour une intégration robuste, oui : authentification, gestion des erreurs, supervision et maintenance demandent des compétences de développement. Pour des besoins simples, un connecteur ou une plateforme d'intégration sans code peut suffire.
Peut-on déclencher un appel API depuis un workflow HubSpot ?
Oui, avec l'action webhook des workflows ou avec une action de code personnalisé, disponible avec Data Hub. C'est utile pour prévenir un système externe à une étape précise d'un processus.
Comment sécuriser une intégration API ?
Limitez les périmètres du jeton au strict nécessaire, stockez-le dans un coffre de secrets, renouvelez-le régulièrement, vérifiez la signature des webhooks reçus et journalisez les échanges. Documentez aussi qui est responsable de l'intégration.
Connecter HubSpot à votre système d'information
L'API HubSpot ouvre presque toutes les portes, mais une intégration réussie tient d'abord au cadrage : quelle donnée, quel outil maître, quel déclencheur, quelle supervision. Copernic conçoit et maintient ces intégrations depuis plus de 10 ans, de la cartographie des flux au monitoring. Découvrez notre accompagnement d'intégrateur HubSpot pour vos projets d'API, ou échangez directement avec nous : Parler à un expert.