Imports

PrésentationPoints de terminaison

Utilisez l'API d'import pour importer des fiches d'informations et des activités du CRM dans votre compte HubSpot, comme des contacts, des entreprises et des notes. Une fois l'import terminé, vous pouvez accéder aux fiches d'informations et aux activités et les mettre à jour via les différents points de terminaison de l'API du CRM, y compris l'API des contacts, l'API des associations et les API des engagements. Vous pouvez également importer des fiches d'informations et des activités à l'aide de l'outil d'import guidé dans HubSpot.

Avant de commencer l'import, découvrez-en davantage sur les objets et les activités pouvant être importés ainsi que sur les exigences en matière de fichiers et de propriétés.

Démarrer un import

Vous pouvez commencer un import en effectuant une demande POST à /crm/v3/imports avec un corps de demande qui spécifie comment mapper les colonnes de votre fichier d'import aux propriétés de CRM associées dans HubSpot.

Les imports d'API sont envoyés sous forme de demandes de données de formulaire, le corps de la demande contenant les champs suivants :

  • importRequest : un champ de texte qui contient le JSON de demande.
  • files : un champ de fichier qui contient le fichier d'import.

Pour l'en-tête de demande, ajoutez un en-tête Content-Type avec une valeur multipart/form-data.

La capture d'écran ci-dessous illustre ce à quoi pourrait ressembler votre demande lorsque vous utilisez une application telle que Postman :

postman-import-request-no-response0

Formater les données importRequest

Dans le JSON de demande, définissez les détails du fichier d'import, y compris le mappage des colonnes de la feuille de calcul avec les données HubSpot. Votre JSON de demande doit inclure les champs suivants :

  • name : nom de l'import. Dans HubSpot, il s'agit du nom affiché dans l'outil d'import ainsi que du nom que vous pouvez mentionner dans d'autres outils, tels que des listes.
  • importOperations : un champ facultatif utilisé pour indiquer si l'import doit créer et mettre à jour, uniquement créer ou uniquement mettre à jour des fiches d'informations pour un objet ou une activité donné. Incluez objectTypeId pour l'objet/l'activité et si vous souhaitez UPSERT (créer et mettre à jour) CREATE ou UPDATE des fiches d'informations. Par exemple, le champ ressemblerait à ceci dans votre demande : "importOperations": {"0-1": "CREATE"}. Si vous n'incluez pas ce champ, la valeur par défaut utilisée pour l'import sera UPSERT.
  • dateFormat : le format des dates incluses dans le fichier. Par défaut, cette valeur est définie sur MONTH_DAY_YEAR, mais vous pouvez également utiliser DAY_MONTH_YEAR ou YEAR_MONTH_DAY.
  • marketableContactImport : un champ facultatif pour indiquer le statut marketing des contacts dans votre fichier d'import. Ceci est utilisé uniquement lors de l'import de contacts dans des comptes qui ont accès aux contacts marketing. Pour définir les contacts dans le fichier comme marketing, utilisez la valeur true. Pour définir les contacts dans le fichier comme non marketing, utilisez la valeur false. 
  • createContactListFromImport : un champ facultatif pour créer une liste statique de contacts à partir de votre import. Pour créer une liste à partir de votre fichier, utilisez la valeur true.
  • files : un tableau qui contient des informations sur votre fichier d'import.
    • fileName : le nom du fichier d'import.
    • fileFormat : le format du fichier d'import. Pour les fichiers CSV, utilisez la valeur CSV. Pour les fichiers Excel, utilisez la valeur SPREADSHEET.
    • fileImportPage : contient le tableau columnMappings requis pour mapper les données de votre fichier d'import aux données HubSpot. Découvrez-en davantage sur le mappage des colonnes ci-dessous.

Mapper des colonnes de fichiers à des propriétés HubSpot

Dans le tableau columnMappings, incluez une entrée pour chaque colonne de votre fichier d'import, en respectant l'ordre de votre feuille de calcul. Pour chaque colonne, ajoutez les champs suivants :

  • columnObjectTypeId : le nom ou la valeur objectTypeId de l'objet ou de l'activité auquel/à laquelle les données appartiennent. Consultez cet article pour une liste complète des valeurs objectTypeId.
  • columnName : le nom de l'en-tête de colonne.
  • propertyName : le nom interne de la propriété HubSpot vers laquelle les données seront mappées. Pour la colonne commune dans les imports multi-fichiers, propertyName doit avoir la valeur null lorsque le champ toColumnObjectTypeId est utilisé.
  • columnType : utilisé pour spécifier qu'une colonne contient une propriété d'identifiant unique En fonction de la propriété et de l'objectif de l'import, utilisez l'une des valeurs suivantes :
    • HUBSPOT_OBJECT_ID : l'identifiant d'une fiche d'informations. Par exemple, votre fichier d'import de contacts peut contenir un ID de fiche d'informations qui stocke l'ID de l'entreprise à laquelle vous souhaitez associer les contacts.
    • HUBSPOT_ALTERNATE_ID : un identifiant unique autre que l'ID de fiche d'informations. Par exemple, votre fichier d'import de contacts peut contenir une colonne Adresse e-mail qui stocke les adresses e-mail des contacts.
    • ASSOCIATION_KEYS : pour les imports d'associations d'objets identiques uniquement, incluez ce type de colonne pour l'identifiant unique des mêmes fiches d'informations d'objets que vous associez. Par exemple, dans votre demande d'import d'associations de contacts, la colonne [ID de fiche d'informations/adresse e-mail] du contact associé doit avoir un élément columnType ASSOCIATION_KEYS. Découvrez-en davantage sur la configuration de votre fichier d'import pour l'import d'associations d'objets identiques.
  • toColumnObjectTypeId : pour les imports multi-fichiers uniquement, le nom ou l'élément objectTypeId de l'objet auquel appartient la propriété de colonne commune. Incluez ce champ pour la propriété de colonne commune (et la colonne de libellé d'association si elle est utilisée) dans le fichier de l'objet auquel la propriété n'appartient pas. Par exemple, si vous associez des contacts et des entreprises dans deux fichiers avec la propriété de contact Adresse e-mail comme colonne commune, incluez toColumnObjectTypeId pour la colonne Adresse e-mail dans le fichier de l'entreprise.
  • foreignKeyType : pour les imports multi-fichiers uniquement, le type d'association que la colonne commune doit utiliser, spécifié par associationTypeId et associationCategory. Incluez ce champ pour la propriété de colonne commune dans le fichier de l'objet auquel la propriété n'appartient pas. Par exemple, si vous associez des contacts et des entreprises dans deux fichiers avec la propriété de contact Adresse e-mail comme colonne commune, incluez foreignKeyType pour la colonne Adresse e-mail dans le fichier de l'entreprise.
  • associationIdentifierColumn : pour les imports multi-fichiers uniquement, indique la propriété utilisée dans la colonne commune pour associer les fiches d'informations. Incluez ce champ pour la propriété de colonne commune dans le fichier de l'objet auquel la propriété appartient. Par exemple, si vous associez des contacts et des entreprises dans deux fichiers avec la propriété de contact Adresse e-mail comme colonne commune, définissez associationIdentifierColumn sur true pour la colonne E-mail dans le fichier de contact.

Importer un fichier

Voici un exemple de corps de demande pour l'import d'un fichier pour créer des contacts :

// Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] }# This example a local file named 'test_import.csv' # This file contains a list of contact records to import. import requests import json import os url = "https://api.hubapi.com/crm/v3/imports" YOUR_ACCESS_TOKEN = 'xxxxxxx'; # Content-Type header will be set automatically by the requests library headers = { 'authorization': 'Bearer %s' % YOUR_ACCESS_TOKEN } data = { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": True, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } datastring = json.dumps(data) payload = {"importRequest": datastring} current_dir = os.path.dirname(__file__) relative_path = "./test_import.csv" absolute_file_path = os.path.join(current_dir, relative_path) files = [ ('files', open(absolute_file_path, 'rb')) ] print(files) response = requests.request("POST", url, data=payload, files=files, headers=headers) print(response.text.encode('utf8')) print(response.status_code) # Using this endpoint requires using sending multi-part form encoded data. Here is an example curl request: # importing a file named import_file.csv # create a variable for the importRequest JSON myJSON=$(cat <<EOF { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "import_file.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } EOF ) YOUR_ACCESS_TOKEN="xxx-xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" curl -v \ -F "files=@import_file.csv;type=text/csv" \ -F "importRequest=$myJSON;type=application/json" \ -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" \ https://api.hubapi.com/crm/v3/imports

Importer plusieurs fichiers

Vous trouverez ci-dessous un exemple de corps de demande d'import et d'association de contacts et d'entreprises dans deux fichiers, où la propriété de contact Adresse e-mail est la colonne commune dans les fichiers :

// Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "Contact Company import", "dateFormat": "YEAR_MONTH_DAY", "files": [ { "fileName": "contact-import-file.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "associationIdentifierColumn": true } ] } }, { "fileName": "company-import-file.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-2", "columnName": "Company name", "propertyName": "name" }, { "columnObjectTypeId": "0-2", "columnName": "Company domain name", "propertyName": "domain", "columnType": "HUBSPOT_ALTERNATE_ID" }, { "columnObjectTypeId": "0-2", "toColumnObjectTypeId": "0-1", "columnName": "Email", "propertyName": null, "foreignKeyType": { "associationTypeId": 280, "associationCategory": "HUBSPOT_DEFINED" } } ] } } ] }

En cas de succès, la réponse comprendra un importId que vous pourrez utiliser pour récupérer ou annuler l'import. 

Obtenir des imports précédents

Pour récupérer tous les imports depuis votre compte HubSpot, effectuez une demande GET à /crm/v3/imports/. Pour récupérer des informations pour un import spécifique, effectuez une demande GET à /crm/v3/imports/{importId}.

Lorsque vous récupérez des imports, des informations sont renvoyées, y compris le nom de l'import, la source, le format de fichier, la langue, le format de date et les mappages de colonnes. L'élément state de l'import sera également renvoyé et peut être l'un des éléments suivants :

  • STARTED : HubSpot reconnaît que l'import existe, mais son traitement n'a pas encore commencé.
  • PROCESSING : l'import est en cours de traitement.
  • DONE : l'import est terminé. Tous les objets, activités ou associations ont été mis à jour ou créés.
  • FAILED : une erreur n'a pas été détectée lors du démarrage de l'import. L'import n'a pas été terminé.
  • CANCELED : l'utilisateur a annulé l'export alors qu'il se trouvait dans l'un des états STARTED, PROCESSING ou DEFERRED.
  • DEFERRED : le nombre maximal d'imports simultanés (trois) est atteint. L'import commencera une fois que le traitement de l'un des autres sera terminé.

Découvrez-en davantage sur la pagination et la limitation des résultats dans l'onglet Points de terminaison en haut de cet article.

Remarque : Lorsque vous récupérez des imports à l'aide d'un jeton d'accès d'application privée, la réponse inclura uniquement les imports effectués par cette application privée. Les imports effectués dans HubSpot ou via une autre application privée ne seront pas renvoyés.

Cancel an import

To cancel an active import, make a POST request to /crm/v3/imports/{importId}/cancel. 

View and troubleshoot import errors

To view errors for a specific import, make a GET request to /crm/v3/imports/{importId}/errors. Learn more about common import errors and how to resolve them.

For errors such as Incorrect number of columns, Unable to parse JSON or 404 text/html is not accepted:

  • Ensure that there is a column header for each column in your file, and that the request body contains a columnMapping entry for each column. The following criteria should be met:
    • The column order in the request body and import file should match. If the column order doesn't match, the system will attempt to automatically reorder but may be unsuccessful, resulting in an error when the import is started.
    • Every column needs to be mapped. If a column is not mapped, the import request may still be successful, but would result in the Incorrect number of columns error when the import is started.
  • Ensure that the file's name and the fileName field in your request JSON match, and that you've included the file extension in the fileName field. For example, import_name.csv.
  • Ensure that your header includes Content-Type with a value of multipart/form-data.

Remarque : Si vous recevez une erreur, vérifiez s'il y a des en-têtes en double, tels que Content-Type. Cela peut se produire si vous utilisez Postman ou s'il est inclus dans l'en-tête de votre script Python. Supprimez le doublon avant de terminer la demande. 

Limites d'utilisation

Lorsque vous utilisez l'API d'import, vous pouvez importer jusqu'à 80 millions de lignes par jour. Cependant, un fichier d'import est limité à 1 048 576 lignes ou 512 Mo, selon la première éventualité.

Si votre demande dépasse la limite de lignes ou la taille maximale, HubSpot renverra une erreur HTTP 429. Lorsque vous approchez de ces limites, il est recommandé de diviser votre import en plusieurs demandes.  

Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.