Formulaire HubSpot sur un site externe : intégrer, collecter ou utiliser l’API ?

Intégration, collecte automatique ou API : quelle différence ?

Choisissez selon le contrôle nécessaire sur le formulaire. Le nom de votre hébergeur ou du constructeur de site renseigne moins que le HTML produit, le moment où le formulaire apparaît et le code qui traite son envoi.

Notre conseil : retenir la méthode la plus simple qui couvre vos besoins. Si votre outil de formulaire possède déjà une intégration HubSpot prise en charge, examinez sa gestion des champs avant de commander un développement. Cette intégration explicite et la détection automatique par HubSpot sont deux mécanismes différents.

Comment intégrer un formulaire HubSpot sur un site externe ?

Vous n’avez pas besoin de déplacer votre site dans HubSpot. L’outil fournit un code d’intégration pour une page externe et un lien de partage vers un formulaire autonome.

1. Ouvrez Marketing → Formulaires, modifiez le formulaire voulu et publiez ou mettez à jour sa configuration.
2. Récupérez le code d’intégration dans les options de partage. Selon l’interface documentée : Vérifier et mettre à jour → Mettre à jour → Obtenir le code d’intégration, ou Actions → Partager → Code d’intégration depuis la liste.
3. Collez ce code dans le module HTML ou d’intégration de votre page externe.
4. Installez le code de suivi HubSpot pour les statistiques du formulaire intégré. Ajoutez le domaine externe aux paramètres de suivi.
5. Ouvrez l’URL publiée et effectuez la vérification décrite plus bas.

Source : autre chemin documenté pour retrouver le code de partage.

Le nouvel éditeur permet-il le HTML brut et le CSS personnalisé ?

Le nouvel éditeur ne propose pas le réglage « raw HTML » de l’ancien éditeur. Son code développeur avancé, qui permet une personnalisation par une feuille CSS externe, exige Marketing Hub ou Content Hub Professional ou Enterprise. Cette condition concerne le code développeur avancé, pas toute intégration standard.

Source : étapes d’intégration, statistiques et différences entre éditeurs.

Notre conseil : reprendre le code actuel depuis votre compte, sans le reconstituer à partir d’un ancien tutoriel. Conservez la référence du compte, du formulaire et de la page pour identifier ce qui devra être vérifié après une modification.

HubSpot peut-il récupérer votre formulaire HTML existant ?

Oui, s’il respecte les conditions des formulaires externes à HubSpot. Le code de suivi doit se charger et la collecte doit être activée. Dans les paramètres, ouvrez Marketing → Formulaires → Formulaires externes à HubSpot, puis activez la collecte des données des formulaires du site.

Un formulaire affiché sur un site externe n’est pas automatiquement compatible. La FAQ HubSpot cite notamment ces obstacles :

• Absence de balise <form> ou formulaire placé dans une iframe.
• Champ email qui n’est pas de type type="email", ou absence du bouton standard <input type="submit">.
• JavaScript attaché à l’événement d’envoi ou au clic sur le bouton.
• Formulaire ajouté après le chargement initial, ou application monopage.
• Champs sensibles ; les données des champs masqués ne sont pas collectées.

Source : conditions de détection des formulaires externes.

Pourquoi certaines soumissions sont-elles incomplètes ou certains champs vides ?

La collecte peut enregistrer le clic avant que la validation du formulaire externe réussisse : une tentative incomplète peut donc être conservée. La correspondance avec les propriétés est automatique, non réglable manuellement dans cet outil et limitée aux propriétés de texte sur une ligne. Une valeur non rapprochée peut rester visible dans la soumission sans remplir la fiche contact.

Source : comportement de la collecte et correspondance des champs.

Que choisir pour React, une SPA ou un site créé avec l’IA ?

Examinez le fonctionnement réel du site. Un constructeur IA peut produire du HTML statique, une application rendue dans le navigateur ou un formulaire relié à un autre service. La mention « créé avec l’IA » ne suffit pas pour conclure à une compatibilité.

Source : restrictions de la collecte automatique sur les formulaires dynamiques.

Pour un formulaire intégré, HubSpot recommande aussi de contrôler les conflits JavaScript, les identifiants de formulaire dupliqués et les constructeurs qui recréent son conteneur. L’intégration reste à adapter correctement à une application dynamique.

Source : diagnostic d’un formulaire intégré sur un site externe.

Nos vérifications proposées : chargement direct, arrivée depuis une autre route, réouverture de la fenêtre et affichage mobile. Vérifiez qu’une seule instance voulue est présente dans chaque parcours. Ces contrôles sont à effectuer sur votre site ; ils ne constituent pas une certification de compatibilité d’un framework.

Quel événement confirme l’envoi d’un nouveau formulaire ?

Pour les formulaires créés avec le nouvel éditeur, HubSpot documente hs-form-event:on-submission:success et hs-form-event:on-submission:failed. Ils diffèrent des anciens callbacks. Un clic ou un événement de chargement du formulaire ne confirme pas un envoi réussi.

Les événements identifient formId et instanceId ; getConversionId() est disponible après une soumission réussie. L’écouteur on-ready doit être installé avant l’exécution de l’intégration pour ne pas manquer l’événement.

Source : événements et instances du nouvel éditeur.

Notre recommandation : préciser si votre mesure représente un clic, une soumission acceptée ou un prospect enregistré. Comptez une seule fois le résultat recherché. Cette documentation sert à votre implémentation ; le présent article ne charge aucun formulaire HubSpot actif.

Quand utiliser l’API Forms de HubSpot ?

L’API mérite d’être étudiée pour conserver une interface personnalisée et contrôler explicitement les données envoyées. HubSpot documente un endpoint sans authentification compatible avec les requêtes AJAX interdomaines et un endpoint authentifié avec des limites de débit plus élevées.

Source : soumissions sans authentification et CORS.

Source : soumissions authentifiées.

La requête peut transmettre les champs et un contexte, notamment pageUri, pageName et hutk, ainsi que legalConsentOptions. La cible est définie par l’identifiant du compte HubSpot et le GUID du formulaire.

Source : structure de la requête de soumission.

Exemple de données pour l’endpoint public

Voici la structure illustrative d’un contact avec email et prénom. Pour votre implémentation, utilisez le bon compte, le bon formulaire, tous ses champs requis et la configuration de consentement applicable.

{
  "fields": [
    {
      "objectTypeId": "0-1",
      "name": "email",
      "value": "person@example.com"
    },
    {
      "objectTypeId": "0-1",
      "name": "firstname",
      "value": "Alex"
    }
  ],
  "context": {
    "pageUri": "https://example.com/demande-demo",
    "pageName": "Demander une démo"
  }
}

Envoyez le JSON à l’endpoint public de soumission v3 avec vos portalId et formGuid. N’envoyez pas l’adresse fictive de l’exemple. Le jeton de suivi absent ici est expliqué plus bas : une valeur inventée ne reconstituerait pas l’historique du visiteur.

Source : schéma des données envoyées.

Pourquoi les mêmes champs peuvent-ils être traités différemment selon l’endpoint ?

L’amendement publié par les développeurs HubSpot indique qu’une nouvelle intégration non authentifiée envoyant une propriété CRM absente de la définition du formulaire peut recevoir FIELD_NOT_IN_FORM_DEFINITION. Il documente aussi des exceptions historiques. L’endpoint sécurisé peut accepter des propriétés CRM existantes non listées dans le formulaire ; l’intégrateur reste responsable de la validation des entrées.

HubSpot recommande néanmoins d’inclure les champs envoyés dans la définition du formulaire. Nous conseillons de maintenir une liste explicite des champs autorisés, surtout si un endpoint serveur authentifié reçoit les saisies d’un site public.

Source : annonce expliquant les différences de validation.

La référence actuelle marque skipValidation comme obsolète, même si certains exemples générés l’affichent encore. Notre exemple l’omet. Analysez la réponse réelle d’une requête refusée plutôt que recopier un ancien paramètre de contournement de validation.

Source : paramètre obsolète et réponses de l’API.

Que transmettre au développeur ?

Notre brief proposé précise le résultat attendu :

Collecte automatique et API peuvent-elles enregistrer deux fois la même demande ?

Oui. La FAQ communautaire HubSpot décrit le cas d’un envoi capturé automatiquement puis transmis par API : un seul contact possède alors deux soumissions.

Source : avertissement sur le cumul des deux mécanismes.

Notre diagnostic : comparer les horaires et les formulaires concernés, puis vérifier si les deux mécanismes sont actifs. Retenez un chemin de collecte voulu pour ce formulaire. Avant de modifier un réglage global du compte, recensez les autres formulaires qui pourraient en dépendre.

Vérifiez le CAPTCHA avant de retenir l’API

HubSpot indique que les soumissions par l’API Forms ou d’autres intégrations ne sont pas acceptées lorsque le CAPTCHA est activé sur le formulaire cible. Choisissez ensemble la méthode et sa protection antispam. Ne désactivez pas simplement une protection en production pour faire réussir une requête.

Source : restriction du CAPTCHA pour les soumissions API.

Dans un développement personnalisé, nous conseillons de documenter ensemble la validation, la protection contre les abus et le message d’erreur affiché au visiteur. Une requête qui réussit dans une console ne valide pas à elle seule le formulaire complet.

Le prospect est reçu, mais son historique ou son consentement email manque : pourquoi ?

Recevoir une demande, retrouver les pages visitées et inscrire une personne aux emails marketing sont trois résultats distincts. Vérifiez celui dont vous avez besoin.

Contexte de page et cookie du visiteur ne jouent pas le même rôle

HubSpot indique qu’un envoi côté serveur ou par proxy sans cookie de suivi peut ne pas être rapproché des visites précédentes. Un contact peut également convertir sans accepter les cookies, sans activité de pages vues enregistrée. Sur un navigateur partagé, les tests peuvent mélanger des identités ou modifier des propriétés selon les réglages du formulaire.

Source : cookies, envois serveur et identité sur un appareil partagé.

Pour notre demande de démo, relevez l’URL et le nom de la page, puis vérifiez la disponibilité du véritable jeton du visiteur dans votre configuration de suivi. N’inventez pas de hutk et ne considérez pas pageUri comme une preuve de récupération de l’historique complet. Utilisez une nouvelle session de navigateur lorsque le scénario de test le nécessite.

Une case cochée n’est pas automatiquement un consentement email appliqué

Les options HubSpot relient les choix de communication aux types d’abonnement. Dans la configuration documentée de consentements séparés, un formulaire peut être accepté sans inscrire le contact aux communications si la case correspondante n’est pas cochée. L’exigence de consentement au traitement est distincte.

Source : options de consentement et types d’abonnement.

Notre contrôle : utiliser de nouveaux contacts de test, effectuer chaque choix prévu et lire le statut de l’abonnement correspondant. Pour l’API, spécifiez comment le choix du visiteur alimente les données de consentement. Un « oui » enregistré dans une propriété personnalisée sans rapport ne prouve pas que l’abonnement a été correctement configuré.

Comment vérifier qu’une demande du site arrive correctement dans HubSpot ?

Inspectez la soumission et la fiche CRM. Le message de remerciement du site ne prouve pas que toutes les valeurs sont arrivées. Voici notre procédure de vérification proposée.

1. Écrivez le résultat attendu. Utilisez une adresse de test que vous contrôlez et des valeurs reconnaissables. Notez le formulaire, le contact et les propriétés cibles. Distinguez création d’un nouveau contact et mise à jour d’une fiche existante.
2. Utilisez la page publiée. Envoyez une seule fois depuis la véritable URL externe. Relevez l’heure, la page et la méthode de transmission.
3. Ouvrez la soumission. Comparez les données reçues aux données saisies. Vérifiez qu’un seul envoi n’a pas créé deux entrées par des chemins différents. Inspectez le spam si nécessaire.
4. Ouvrez la fiche contact. Comparez chaque propriété et vérifiez qu’aucune ancienne valeur n’a été écrasée involontairement. Contrôlez séparément les visites et les abonnements requis.
5. Essayez une saisie invalide. Laissez un champ obligatoire incomplet, observez le site et ce qui a été enregistré, puis effectuez un envoi valide.
6. Recommencez après navigation. Si le site utilise des routes côté navigateur ou une fenêtre modale, testez ce parcours et l’affichage sur un écran de téléphone.
7. Vérifiez la suite. Si une notification ou une relance est attendue, vérifiez-la séparément et identifiez la personne qui traitera la demande.

Les formulaires HubSpot peuvent relier les champs à des propriétés CRM. Leurs réglages peuvent aussi définir les nouveaux contacts comme contacts marketing lorsque cette fonction est disponible. Contrôlez ce statut explicitement : collecte, statut marketing et relance ne sont pas une seule opération.

Source : propriétés des formulaires et réglages des contacts.

Conservez une ligne de suivi avec la page, la méthode, la valeur attendue, la valeur observée, l’heure et le responsable. Réutilisez-la après une modification du formulaire ou une mise à jour du site.

Le formulaire semble fonctionner, mais un prospect ou un champ manque : que contrôler ?

« La demande est classée en spam. »

Pour un formulaire intégré, relevez le domaine exact dans les détails du spam et ajoutez le domaine approprié aux paramètres de suivi. Certains constructeurs passent par un domaine intermédiaire ou une iframe. Examinez ensuite les soumissions légitimes concernées.

Source : domaines non enregistrés et domaines intermédiaires.

« Mon formulaire existant n’apparaît pas dans HubSpot. »

Un formulaire externe apparaît dans la liste après une première soumission effectivement collectée. Vérifiez sa compatibilité et le suivi avant de supposer qu’il faut le créer manuellement dans cette liste.

Source : apparition du formulaire externe après une soumission.

« La soumission existe, mais la page d’origine manque. »

Examinez les données et le contexte envoyés. HubSpot cite l’absence de paramètres de page dans les soumissions API parmi les causes possibles d’informations de page manquantes.

Source : diagnostic des soumissions et des informations de page.

« Le formulaire intégré est vide ou casse après une mise à jour. »

Comparez le code publié au code fourni par HubSpot. Examinez les conflits JavaScript, la CSP, le contenu mixte, les identifiants dupliqués et la recréation dynamique du conteneur.

Source : contrôles pour les formulaires intégrés.

« L’API renvoie une erreur, mais le site affiche un succès. »

Notre recommandation : faire dépendre l’état affiché de la réponse réelle. Conservez une erreur expurgée des données sensibles et l’heure ; distinguez erreur de validation et limite de débit avant de programmer une nouvelle tentative.

Source : réponses et erreurs documentées.

Si la demande est reçue mais qu’un email ou une notification échoue ensuite, isolez cette étape. Identifiez où le parcours s’arrête avant de reconstruire une collecte qui fonctionne.

Questions fréquentes sur les formulaires HubSpot sur un site externe

Faut-il héberger son site chez HubSpot ?

Non. HubSpot fournit un code pour les pages externes et un lien vers un formulaire autonome. Votre site peut rester chez son hébergeur actuel.

Peut-on convertir un formulaire externe détecté en formulaire HubSpot ?

HubSpot propose Actions → Copier vers HubSpot. Vérifiez et publiez le formulaire copié, puis remplacez l’ancien formulaire du site par le nouveau code d’intégration. La copie dans HubSpot ne remplace pas le code de votre site à elle seule.

Source : copie du formulaire et remplacement sur le site.

L’API Forms exige-t-elle toujours un jeton privé ?

Non. HubSpot documente un endpoint sans authentification et un endpoint authentifié. Choisissez explicitement la méthode ; n’exposez pas de jeton privé dans le code du site.

Un formulaire HubSpot intégré est-il un formulaire externe à HubSpot ?

Ce sont deux catégories différentes. L’intégration affiche un formulaire créé dans HubSpot. La collecte externe détecte un formulaire compatible créé ailleurs. Leurs conditions et leur traitement des champs diffèrent.

Installer le script de suivi garantit-il la réception de tous les prospects ?

Non. La collecte automatique dépend du fonctionnement compatible du formulaire et du chargement du script. Vérifiez un véritable envoi et les valeurs enregistrées avant de considérer l’intégration comme terminée.

Références de ces réponses techniques : intégration externe, collecte des formulaires existants et endpoint sans authentification.

Méthode et guides HubSpot complémentaires

Ce guide s’appuie sur la documentation officielle et les annonces développeurs HubSpot vérifiées le 18 octobre 2026. Les critères de choix, le brief et les vérifications sont nos recommandations. Aucun envoi authentifié vers HubSpot ni benchmark de framework n’a été effectué pour cet article.

Pour les fonctions, les offres et les coûts, consultez notre avis HubSpot. Pour agir sur les fiches depuis une conversation, lisez le guide du connecteur HubSpot ChatGPT. Pour choisir un outil de création de pages, consultez notre avis Leadpages.