Préparer un CSV HubSpot : identifiants, en-têtes et cellules vides

L'intégration de fichiers externes au sein d'un CRM constitue une étape déterminante pour les équipes commerciales et marketing. Un fichier mal calibré entraîne des doublons, des associations erronées entre comptes et interlocuteurs, ou encore des rejets de lignes lors du traitement informatique. Structurer un fichier destiné à HubSpot exige une discipline technique rigoureuse, dictée par les spécifications logicielles de la plateforme et la typologie des objets manipulés.

Ce tutoriel vise des données que vous êtes autorisé à traiter et à importer dans votre compte. La documentation d’import HubSpot demande notamment de confirmer que les contacts attendent vos messages et que le fichier ne contient pas de liste achetée. Une structure technique compatible ne vaut donc pas autorisation d’importer n’importe quelle source. Consultez les règles en vigueur avant l’opération.

Choisir les objets et concevoir l’architecture de la table

Avant d'ouvrir un tableur, l'administrateur ou l'opérateur de données doit définir le périmètre relationnel de l'opération. HubSpot structure ses données selon des entités distinctes nommées objets, parmi lesquelles figurent principalement les contacts, les entreprises, les transactions et les tickets. Un import peut concerner un objet unique ou associer plusieurs objets au sein d'une seule feuille de calcul, à condition de concevoir la table de manière appropriée.

Dans le cadre d'un import combinant des entreprises et des contacts, chaque ligne du tableau doit représenter un contact individuel rattaché à son organisation. Lorsqu'une entreprise compte plusieurs interlocuteurs dans la base, les informations relatives à cette entreprise doivent être répétées à l'identique sur chaque ligne correspondante, tandis que l'adresse email reste propre à chaque contact. Selon les consignes techniques documentées sur la page Format import files de HubSpot, la plateforme accepte les formats CSV, XLSX et XLS. Le fichier ne doit comporter qu'une seule feuille de calcul et une unique ligne d'en-tête située sur la toute première ligne.

L'encodage du fichier représente un point de vigilance récurrent lors de l'export depuis des tableurs configurés en environnement francophone. HubSpot préconise un encodage en UTF-8 pour préserver l'intégrité des caractères accentués, des cédilles et des caractères propres aux langues étrangères. Un mauvais encodage transforme les lettres accentuées en symboles inintelligibles, ce qui altère durablement la lisibilité des fiches et la segmentation ultérieure dans le CRM. De plus, les séparateurs de colonnes doivent être cohérents : un fichier CSV utilise conventionnellement la virgule ou le point-virgule, mais l'éditeur de données doit veiller à ce qu'aucune rupture de délimiteur ne vienne décaler les colonnes.

Nommer les colonnes et aligner les propriétés

Le nommage des en-têtes conditionne la reconnaissance automatique des colonnes par l'assistant d'importation de HubSpot. Si l'intitulé de votre en-tête correspond exactement au libellé visible ou au nom interne de la propriété CRM cible, l'outil réalise l'appariement de manière fluide. À l'inverse, un intitulé approximatif ou ambigu contraint l'utilisateur à un mappage manuel champ par champ, ce qui accroît le temps de manipulation et le risque d'erreur d'affectation.

Pour les propriétés personnalisées créées au sein du CRM, il est conseillé de reproduire l'intitulé exact sans y adjoindre de caractères spéciaux complexes, de doubles espaces ou de retours à la ligne masqués dans la cellule d'en-tête. La typologie de chaque colonne doit respecter scrupuleusement la configuration de la propriété de destination :

• Champs texte : ils reçoivent les libellés libres, les fonctions professionnelles ou les adresses postales, sans contrainte de format strict en dehors de la limite de caractères.
• Champs numériques : ils ne doivent comporter aucun caractère alphabétique, espace ou symbole monétaire. Une valeur comme 50000 est valide, tandis que 50 000 € provoquera un rejet lors de l'analyse du champ.
• Propriétés de type date : HubSpot recommande d'uniformiser le formatage sur l'ensemble de la colonne, par exemple sous la structure AAAA-MM-JJ ou JJ/MM/AAAA, en veillant à conserver des séparateurs identiques pour toutes les lignes.
• Menus déroulants et cases à cocher : la valeur textuelle insérée dans chaque cellule du fichier doit coïncider lettre pour lettre avec les options internes configurées dans le CRM, sous peine de refus de la valeur lors de l'import.

Exemple illustratif de restructuration d'en-têtes

Pour illustrer la préparation des colonnes, prenons le cas d'un fichier brut issu d'une extraction tierce destiné à alimenter simultanément des fiches d'entreprises et des fiches de contacts. Le tableau suivant présente la conversion technique recommandée pour sécuriser le mappage automatique dans HubSpot.

Définir les identifiants uniques et sécuriser le rapprochement

L'utilisation d'identifiants de rapprochement constitue le mécanisme indispensable pour actualiser des fiches existantes sans générer de doublons. Comme l'indique la documentation technique sur la déduplication des fiches sur HubSpot, la plateforme s'appuie par défaut sur l'adresse e-mail pour identifier et dédupliquer les fiches de contacts, et sur le nom de domaine de l'entreprise pour les fiches de sociétés.

Lorsqu'un fichier est importé sans identifiant unique, chaque ligne est susceptible de créer un nouvel enregistrement indépendant dans le CRM, ce qui fragmente les historiques de relation client. Toutefois, l'usage du seul nom de domaine pour les entreprises comporte des limites opérationnelles. Par exemple, deux établissements régionaux, deux filiales ou deux marques distinctes partageant le même site internet institutionnel risquent d'être fusionnés involontairement si seul le domaine web sert de pivot. De surcroît, la documentation rappelle que les entreprises créées via API ne sont pas systématiquement dédupliquées par domaine selon les mêmes règles qu'un import de fichier.

Pour sécuriser une opération de mise à jour sur une base déjà installée, la méthode la plus fiable consiste à utiliser l'identifiant interne généré par le CRM, désigné sous le terme de Record ID ou ID d'enregistrement. Si votre objectif est d'enrichir ou de corriger des données existantes, vous devez d'abord exporter vos contacts ou vos entreprises depuis HubSpot en incluant la colonne de l'ID d'enregistrement. Vous effectuez ensuite vos modifications tabulaires en conservant précieusement cette colonne. Lors de la réimportation, HubSpot utilise cet ID pour faire correspondre chaque ligne à la fiche exacte, neutralisant ainsi tout risque de création de doublon ou d'écrasement sur une mauvaise entité.

Gérer les cellules vides et les données incomplètes

La présence de valeurs manquantes dans un fichier tabulaire soulève fréquemment des interrogations sur le devenir des données déjà stockées dans le CRM. Selon les règles de fonctionnement documentées par HubSpot, lors d'un import classique de fichier, la plateforme ignore les cellules vides et n'efface pas automatiquement les valeurs préexistantes enregistrées dans les propriétés des fiches.

Cette règle par défaut protège vos données en place, mais elle impose une rigueur absolue dans le nettoyage des cellules sans information. Une distinction majeure doit être opérée entre une cellule réellement vide et une cellule polluée par des caractères invisibles :

• Espaces résiduels et tabulations : une cellule contenant un simple espace n'est pas considérée comme vide par tous les moteurs de traitement. Elle peut être interprétée comme une chaîne de caractères et écraser une valeur utile par un blanc non désiré.
• Mentions textuelles d'absence : les fichiers bruts comportent fréquemment des mentions telles que « N/A », « Inconnu », « Non renseigné » ou des tirets. Si ces mentions sont importées dans un champ texte, elles s'affichent textuellement dans la fiche CRM. Dans un champ numérique ou de date, elles peuvent provoquer une erreur de propriété. Selon le type d’erreur, la fiche peut être importée sans la valeur fautive ou la ligne peut être rejetée ; consultez le rapport d’import.
• Guillemets et délimiteurs orphelins : lors de manipulations dans des tableurs, des guillemets non refermés peuvent fusionner accidentellement plusieurs lignes ou colonnes lors de la conversion en CSV.

Pour assainir votre fichier avant l'import, appliquez un filtre global sur l'ensemble des colonnes afin de repérer les mentions d'absence textuelles et supprimez-les intégralement pour ne laisser que des cellules totalement vides. Pour effacer volontairement une propriété existante, n’utilisez pas une cellule vide en supposant qu’elle la supprimera. La documentation HubSpot renvoie à une modification des propriétés ou à une action de workflow adaptée, selon les fonctionnalités disponibles dans le compte.

Tester avant l'import complet : protocole d'échantillonnage

Lancer l'import direct d'un fichier de plusieurs milliers de lignes sans validation préalable expose l'entreprise à des opérations de nettoyage manuelles fastidieuses. Ne supposez pas qu’un import pourra être annulé intégralement : les nouvelles fiches et les valeurs modifiées doivent être distinguées, et une suppression des fiches créées ne restaure pas les anciennes valeurs des fiches mises à jour. Un protocole d'essai en trois phases permet de circonscrire les risques techniques.

1. Isolement d'un lot d'essai : extrayez un échantillon restreint de dix lignes issues de votre fichier final. Veillez à ce que cet échantillon contienne des cas de figure variés : un contact avec une entreprise associée, un contact sans numéro de téléphone direct, une entreprise dont le nom comporte des accents ou des caractères spéciaux, et au moins une ligne comportant des cellules vides légitimes.
2. Exécution de l'import test et lecture du rapport : importez ce lot de dix lignes dans HubSpot. À la fin de l'opération, téléchargez systématiquement le fichier de journalisation des erreurs mis à disposition par la plateforme. Ce document détaille chaque rejet ligne par ligne en précisant la cause exacte : syntaxe d'email invalide, valeur hors liste pour une propriété d'énumération ou format de date non reconnu.
3. Vérification visuelle directe dans le CRM : ouvrez chacune des fiches créées ou mises à jour dans HubSpot. Contrôlez que le contact est correctement associé à son entreprise, que les numéros de téléphone sont lisibles sans décalage de champ, et que les propriétés personnalisées affichent la valeur attendue.

Une fois les éventuelles erreurs corrigées sur la matrice globale et validées sur ce lot d'essai, vous pouvez lancer l'import de l'ensemble de votre base. Conservez toujours le fichier source original non modifié ainsi que le rapport d'import final fourni par HubSpot pour assurer la traçabilité de vos opérations de données.

Déléguer la structuration et la fiabilisation de vos fichiers

La normalisation technique de fichiers de prospection, le dédoublonnage multicritère, la détection des syntaxes défaillantes et l'alignement sur les modèles de données des CRM constituent une spécialité à part entière. Une mauvaise préparation en amont compromet l'efficacité des campagnes d'envoi et dégrade la visibilité des équipes commerciales sur leur portefeuille.

Composée de 7 spécialistes de la donnée B2B, l'équipe de La Fabrique B2B accompagne les entreprises dans la structuration, l'enrichissement et le nettoyage sur mesure de leurs bases de contacts et d'entreprises. Nous intervenons sur devis personnalisé pour transformer des fichiers bruts hétérogènes en livrables rigoureusement calibrés pour vos outils d'activation commerciale ou votre CRM.