Dernière modification : 22 août 2025
Utilisez l’outil Fichiers de HubSpot pour gérer et stocker des fichiers dans HubSpot. Les fichiers hébergés dans HubSpot peuvent être chargés et utilisés dans HubSpot et dans le contenu externe. Ils peuvent également être joints à des fiches d’informations à l’aide de l’API des engagements. Si votre entreprise conçoit son site web à l’aide du CMS Hub, vous pouvez utiliser l’API de fichiers pour charger et stocker des éléments dans HubSpot. Ces fichiers peuvent ensuite être proposés et partagés via CMS Hub. Vous pouvez accéder à l’outil Fichiers depuis HubSpot ou via l’API de fichiers. Découvrez ci-dessous l’API de fichiers et apprenez à charger et supprimer des fichiers. Pour une liste complète des points de terminaison de l’API de fichiers, consultez la documentation de référence.

​
Charger un fichier

Les fichiers peuvent être chargés à l’aide d’une demande POST multipart/form-data à files/v3/files avec les champs suivants. Si un ID de dossier spécifique n’est pas requis lors du chargement, il est recommandé de charger des fichiers dans un dossier et non dans le répertoire racine. Les exigences de dossier lors du chargement peuvent changer à l’avenir.
ChampDescription
fileLe fichier à charger (obligatoire).
optionsUn objet JSON qui contrôle la confidentialité et l’indexabilité du fichier et contient deux champs : access, qui est obligatoire, et ttl, qui indique une période après laquelle le fichier sera automatiquement supprimé. Si vous utilisez le champ ttl :
  • La période minimale qui doit être définie est de 1 jour.
  • La période maximale qui peut être fixée est de 1 an.
  • Après la période définie, le fichier sera définitivement supprimé. Après la suppression, le fichier ne pourra pas être récupéré ou restauré.

folderIdL’ID du dossier dans lequel le fichier sera téléchargé. Ce champ ou folderPath doit être fourni dans votre demande (mais pas les deux).
folderPathLe chemin du dossier dans lequel le fichier sera téléchargé. Ce champ ou folderId doit être fourni dans votre demande (mais pas les deux).
fileNameLe nom du fichier. Si aucun nom n’est spécifié, un nom sera généré à partir du contenu du fichier.
charsetHunchUn encodage défini de caractères pour le fichier chargé. Si ce champ n’est pas renseigné, il sera dérivé du fichier.
Par exemple, si vous souhaitez télécharger un fichier avec les critères suivants sur votre compte HubSpot :
  • Nom du fichier : cat.png
  • Dossier de destination dans le gestionnaire de fichiers HubSpot : /library/cat_archive
  • Accessibilité des fichiers dans HubSpot : accès privé
Les en-têtes et le corps de la demande suivants doivent faire partie de votre demande : 
curl --request POST \
  --url 'https://api.hubapi.com/files/v3/files?=' \
  --header 'Authorization: Bearer pat-na1-00000000-0000-0000-0000-000000000000' \
  --header 'Content-type: multipart/form-data' \
  --form file=@/Users/person/Downloads/cat.png \
  --form 'options={"access": "PRIVATE"}' \
  --form folderPath=/library/cat_archive
La réponse résultante inclura les éléments id et parentFolderId du fichier téléchargé, que vous pouvez utiliser pour récupérer le fichier via une demande GET. 
// 201 Response from successful file upload
{
  "id": "122692044085",
  "createdAt": "2023-06-28T17:56:45.393Z",
  "updatedAt": "2023-06-28T17:56:45.393Z",
  "archived": false,
  "parentFolderId": "122692510820",
  "name": "cat",
  "path": "/library/cat_archive/cat.png",
  "size": 24574,
  "height": 219,
  "width": 225,
  "encoding": "png",
  "type": "IMG",
  "extension": "png",
  "defaultHostingUrl": "https://12345.fs1.hubspotusercontent-na1.net/hubfs/12345/library/cat_archive/cat.png",
  "url": "https://12345.fs1.hubspotusercontent-na1.net/hubfs/12345/library/cat_archive/cat.png",
  "isUsableInContent": true,
  "access": "PRIVATE"
}

​
Consulter le statut de téléchargement d’un fichier

Si vous importez un fichier à partir d’une URL vers votre gestionnaire de fichiers via une demande POST vers files/v3/files/import-from-url/async, vous pouvez consulter le statut de téléchargement du fichier. Pour ce faire, effectuez une demande GET vers files/v3/files/import-from-url/async/tasks/{taskId}/status. Après avoir fait cette demande, vous recevrez l’une des réponses suivantes :
  • PENDING : le fichier est dans la file d’attente pour être téléchargé. Le processus d’import n’a pas encore commencé.
  • PROCESSING : le fichier est en cours de téléchargement.
  • CANCELED : le téléchargement a été annulé et le fichier ne sera pas téléchargé. Pour importer le fichier dans votre compte HubSpot, vous devrez le télécharger à nouveau.
  • COMPLETE : le fichier a correctement été téléchargé vers l’outil Fichiers. Le fichier téléchargé apparaîtra dans votre outil Fichiers.

​
Afficher les détails d’un fichier

Pour consulter les détails d’un fichier chargé dans l’outil Fichiers, effectuez une demande GET à files/v3/files/{fileId}. Cela renverra le fichier avec des informations telles que le nom, la hauteur et la largeur, l’encodage ou encore l’URL. Par exemple, pour récupérer les détails d’un fichier : Si un fichier est défini comme privé, l’URL renverra une erreur 404. Pour obtenir une URL visible du fichier, vous pouvez effectuer une demande GET à /files/v3/files/{fileId}/signed-url. Lors de cette demande, vous pouvez inclure des paramètres property pour renvoyer des spécifiques telles que la hauteur et la largeur.

​
Supprimer un fichier

Pour supprimer un fichier, effectuez une demande DELETE à files/v3/files/{fileId}. Le fichier sera marqué comme supprimé et son contenu sera inaccessible. Pour supprimer définitivement un fichier, effectuez une demande DELETE à files/v3/files/{fileId}/gdpr-delete. Le contenu et les métadonnées du fichier seront définitivement supprimés sous 7 jours. Si un fichier n’est pas supprimé conformément au RGPD, son contenu restera sur les serveurs de HubSpot avec un statut privé et personne ne pourra y accéder. Pour assurer la suppression complète du contenu du fichier, utilisez la fonctionnalité de suppression conformément au RGPD.

​
Créer un dossier

Pour créer un dossier, effectuez une demande POST à files/v3/folders. Lors de la demande, vous pouvez inclure les champs ci-dessous.
ChampObligatoireDescription
nameOui : le nom du dossier que vous souhaitez créer.
parentFolderIdNon : pour créer le dossier dans un dossier existant, incluez ce champ avec l’ID du dossier existant. parentFolderId et parentFolderPath ne peuvent pas être définis en même temps.
parentFolderPathNon : pour créer le dossier dans un dossier existant, incluez ce champ avec le chemin du dossier existant. parentFolderId et parentFolderPath ne peuvent pas être définis en même temps.
//Example request body of POST request to /files/v3/folders
{
  "name": "myNewFolder",
  "parentFolderId": 12345
}

​
Modifications de la version 3

Si vous utilisez la version précédente de cette API, la version 3 présente les modifications suivantes :
  • Tous les fichiers chargés via l’API seront visibles dans le tableau de bord des fichiers et le sélecteur de fichiers. Les fichiers cachés ne peuvent pas être créés. Cependant, les fichiers privés et non indexables peuvent toujours être créés.
  • Les fichiers de listing ne renverront pas de fichiers masqués ou supprimés. Toutefois, un vaste éventail de filtres peut être appliqué. Les fichiers masqués peuvent toujours être consultés selon l’ID, mais nécessitent un nouveau domaine : files_ui_hidden.read.
  • Plusieurs fichiers ne peuvent pas être téléchargés avec une seule demande.
  • Les actions de mise à jour de dossier, comme le déplacement et le renommage, sont désormais asynchrones. Chaque demande renvoie un jeton qui peut être utilisé pour vérifier le statut de la modification du dossier.
  • Les points de terminaison qui créent ou remplacent des fichiers nécessitent des niveaux d’accès pour les fichiers. Ces niveaux d’accès sont les suivants :
    • PUBLIC_INDEXABLE** :** le fichier est accessible publiquement par toute personne disposant de l’URL. Les moteurs de recherche peuvent indexer le fichier.
    • PUBLIC_NOT_INDEXABLE** :** le fichier est accessible publiquement par toute personne disposant de l’URL. X-Robots-Tag : l’en-tête non indexable sera envoyé lors de la récupération du fichier et les moteurs de recherche n’indexeront pas le fichier.
    • PRIVATE : le fichier n’est pas accessible publiquement. Nécessite une URL signée pour afficher le contenu. Les moteurs de recherche ne peuvent pas indexer le fichier.
  • Les points de terminaison qui créent des fichiers permettent la détection de doublons dans le cadre des options de chargement du fichier.
    • ENTIRE_PORTAL** :** permet de rechercher un fichier en double dans le compte.
    • EXACT_FOLDER** :** permet de rechercher un fichier en double dans le dossier indiqué.
    • NONE** :** n’exécutez aucune vérification de doublon.
    • REJECT** :** rejetez le chargement si un doublon est trouvé.
    • RETURN_EXISTING** :** si un fichier en double est trouvé, ne chargez aucun nouveau fichier et renvoyez le doublon.
    • La détection des doublons fonctionne selon duplicateValidationScope, qui détermine la recherche d’un doublon.
    • Elle applique également duplicateValidationStrategy, qui précise ce qui se passe si un doublon est trouvé.