Exports

Exigences de portée

Utilisez l’API d’exports pour exporter des fiches d’informations et des données de propriété depuis votre compte HubSpot, récupérez une URL pour télécharger un fichier d’export ou voir le statut d’un export. Dans HubSpot, vous pouvez également exporter des fiches d’informations ou afficher un journal des exports passés dans votre compte.

Lancer un export

Pour démarrer un export, effectuez une requête POST à /crm/v3/exports/export/async. Le corps de votre requête doit indiquer des informations telles que le format de fichier, l’objet et les propriétés que vous souhaitez exporter ainsi que le type d’export que vous effectuez (par exemple : l’export d’une vue d’objet ou d’une liste). Vous pouvez également filtrer les données de propriété à exporter en fonction d’opérateurs spécifiques. Pour les exports de vues et de listes, vous pouvez inclure les champs suivants dans votre requête :

Paramètre	Description
`exportType`	Le type d’export, soit `VIEW` (exporte une vue depuis une page index d’objet), soit `LIST` (exporte une liste).
`format`	Le format du fichier. Les options sont : `XLSX`, `CSV` ou `XLS`.
`exportName`	Le nom de l’export.
`language`	La langue du fichier d’export. Les options sont : `DE`, `EN`, `ES`, `FI`, `FR`, `IT`, `JA`, `NL`, `PL`, `PT` ou `SV`. En savoir plus sur les langues prises en charge.
`objectType`	Le nom ou l’ID de l’objet que vous exportez. Pour les objets standards, vous pouvez utiliser le nom de l’objet (par ex : `CONTACT`), mais pour les objets personnalisés, vous devez utiliser la valeur `objectTypeId`. Vous pouvez récupérer cette valeur en faisant une requête `GET` à `/crm/v3/schemas`.
`associatedObjectType`	Les noms ou ID des objets associés à inclure dans l’export. Vous pouvez exporter jusqu’à quatre objets associés par requête. Pour les objets associés, l’export contiendra les ID de fiche d’informations associés à cet objet. Si vous n’exportez qu’un seul objet associé ou si vous définissez le champ `includePrimaryDisplayPropertyForAssociatedObjects` sur `true`, les valeurs des propriétés d’affichage primaire des fiches seront également exportées (par exemple, `name` pour les entreprises).
`objectProperties`	Une liste des propriétés que vous voulez inclure dans votre export. Par défaut, les noms et les valeurs des propriétés sont affichés comme des libellés lisibles, mais vous pouvez demander des noms et des valeurs internes en utilisant le paramètre `exportInternalValuesOptions`.
`includePrimaryDisplayPropertyForAssociatedObjects`	Ajoutez ce champ avec la valeur `true` pour exporter les valeurs de la propriété d’affichage principale pour toutes les fiches d’informations associées (par exemple, `name` pour les entreprises). Si vous n’exportez qu’un seul objet associé (indiqué par le champ `associatedObjectType`), la valeur par défaut est `true`. Si vous exportez plus d’un objet associé, la valeur est définie par défaut sur `false`.
`includeLabeledAssociations`	Ajoutez ce champ avec la valeur `true` pour exporter des libellés d’association décrivant la relation entre les fiches d’informations associées.
`exportInternalValuesOptions`	Ajoutez ce tableau pour exporter les valeurs internes des noms de propriétés et/ou des valeurs de propriétés. Dans le tableau, ajoutez `NAMES` pour exporter les noms internes des propriétés (affichés en tant qu’en-têtes de colonne) et/ou `VALUES` pour exporter les valeurs propriété internes (par exemple, des valeurs numériques pour les étapes de pipeline personnalisées ou des horodatages au lieu de dates lisibles).
`overrideAssociatedObjectsPerDefinitionPerRowLimit`	Incluez ce champ avec la valeur `true` pour remplacer la limite par défaut de 1 000 associations par ligne.

Exporter une vue

Si vous exportez une vue de page d’index, votre valeur exportType doit être VIEW, et vous pouvez inclure le champ suivant pour filtrer et trier les fiches d’informations que vous exportez :

Paramètre	Description
`publicCrmSearchRequest`	Indique quelles données doivent être exportées en fonction de certaines valeurs de propriétés et requêtes de recherche. Vous pouvez inclure les éléments suivants dans l’objet : `filters` : les propriétés et les valeurs de propriété selon lesquelles filtrer les fiches d’informations. `sorts` : l’ordre de tri des valeurs d’une propriété, croissant, `ASC` ou décroissant, `DES`. `query` : une chaîne pour rechercher les valeurs des fiches d’informations.

Par exemple, pour exporter une vue des contacts et des fiches d’informations d’entreprise associées, filtrée par la propriété email et avec les valeurs internes des noms et valeurs des propriétés, votre requête peut ressembler à ce qui suit :

JSON

///Example request body
{
  "exportType": "VIEW",
  "exportName": "All contacts",
  "format": "xlsx",
  "language": "DE",
  "objectType": "CONTACT",
  "exportInternalValuesOptions": ["NAMES", "VALUES"],
  "objectProperties": ["email", "firstname", "lastname"],
  "associatedObjectType": "COMPANY",
  "publicCrmSearchRequest": {
    "filters": [
      {
        "value": "hello@test.com",
        "propertyName": "email",
        "operator": "EQ"
      }
    ],
    "query": "hello",
    "sorts": [
      {
        "propertyName": "email",
        "order": "ASC"
      }
    ]
  }
}

Exporter une liste

Si vous exportez une liste, votre valeur exportType doit être LIST, mais vous devez également indiquer la liste que vous exportez avec le champ suivant :

Paramètre	Description
`listId`	L’ID de liste ILS de la liste à exporter. Vous pouvez trouver la valeur de l’ID de liste ILS via les détails de la liste dans HubSpot. Accédez à Contacts > Listes, survolez la liste dans le tableau, puis cliquez sur Détails. Dans le panneau de droite, cliquez sur Copier l’ID de liste à côté de la valeur ID de liste ILS. Les listes de contacts ont deux valeurs d’ID différentes, mais vous devez utiliser la valeur d’ID de liste ILS dans votre requête.

Par exemple, pour exporter une liste contenant les adresses e-mail des contacts, votre requête peut ressembler à ce qui suit :

JSON

///Example request body
{
  "exportType": "LIST",
  "listId": 1234567,
  "exportName": "Marketing email contacts",
  "format": "xlsx",
  "language": "EN",
  "objectType": "CONTACT",
  "objectProperties": ["email"]
}

Récupérer les exports

Lorsque vous terminez un export, l’id de l’export sera renvoyé dans la réponse. Pour récupérer un export depuis votre compte HubSpot, effectuez une requête GET à /crm/v3/exports/export/async/tasks/{exportId}/status. Lors de la récupération des exports, le status de l’export sera également renvoyé. Les statuts possibles sont : COMPLETE, PENDING, PROCESSING ou CANCELED. Pour les exports avec un statut COMPLETE, une URL est renvoyée que vous pouvez utiliser pour télécharger le fichier exporté. L’URL de téléchargement expirera cinq minutes après la fin de la requête. Une fois expirée, vous pouvez effectuer une autre requête GET pour générer une nouvelle URL unique.

Remarque :

Avant l’expiration, l’URL de téléchargement de l’export est accessible sans autorisation supplémentaire. Pour protéger vos données, procédez avec prudence lorsque vous partagez une URL ou effectuez une intégration avec HubSpot via cette API.

Limites d’utilisation

Les limites suivantes s’appliquent :

Vous pouvez effectuer jusqu’à trente exports dans une fenêtre de 24 heures consécutives, et un export à la fois. Les exports supplémentaires seront mis en file d’attente jusqu’à ce que l’export précédent soit terminé.
Si vous effectuez un export volumineux, vous pouvez recevoir plusieurs fichiers livrés dans un fichier zip. Cela se produira pour les fichiers CSV ou XLSX de plus de 1 000 000 lignes et de fichiers XLS de plus de 65 535 lignes. Les fichiers CSV sont également automatiquement compressés si la taille du fichier est supérieure à 2 Mo, même s’il contient moins de 1 000 000 de lignes.
Par défaut, le nombre d’associations par ligne est limité à 1 000. Si vous souhaitez dépasser cette limite, incluez le overrideAssociatedObjectsPerDefinitionPerRowLimit champ contenant la valeur true.

Compte et paramètres

Gestion des applications

Authentification

Automatisation

CMS

Préférences de communication

Conversations

CRM

Data Studio

Événements

Fichiers

Marketing

Rendez-vous

Chiffre d'affaires

Webhooks

Journal des webhooks

Lancer un export

Exporter une vue

Exporter une liste

Récupérer les exports

Remarque :

Limites d’utilisation

​Lancer un export

​Exporter une vue

​Exporter une liste

​Récupérer les exports

​Remarque :

​Limites d’utilisation

Lancer un export

Exporter une vue

Exporter une liste

Récupérer les exports

Remarque :

Limites d’utilisation