Letzte Änderung: 22. August 2025
Verwenden Sie das Dateien-Tool von HubSpot, um Dateien in HubSpot zu verwalten und zu speichern. In HubSpot gehostete Dateien können hochgeladen und in HubSpot und externen Inhalten verwendet werden. Sie können auch über die Interaktionen-API an Datensätze angehängt werden. Wenn Ihr Unternehmen seine Website mit dem CMS-System von HubSpot erstellt, können Sie die Dateien-API verwenden, um Elemente in HubSpot hochzuladen und zu speichern. Diese Dateien können dann über Content Hub bereitgestellt und geteilt werden. Sie können das Dateien-Tool innerhalb von HubSpot oder mithilfe der Dateien-API aufrufen. Im Folgenden erfahren Sie mehr über die Dateien-API und wie Sie Dateien hochladen und löschen. Eine vollständige Liste der Dateien-API-Endpunkte finden Sie in der Referenzdokumentation.

​
Eine Datei hochladen

Dateien können mithilfe einer multipart/form-data-POST-Anfrage an files/v3/files mit den folgenden Feldern hochgeladen werden. Beim Upload ist zwar keine bestimmte Ordner-ID erforderlich, es wird jedoch empfohlen, Dateien in einen Ordner hochzuladen und nicht in das Stammverzeichnis. Die Ordneranforderungen beim Upload können sich in Zukunft ändern.
FeldBeschreibung
fileDie Datei, die hochgeladen wird (erforderlich).
optionsEin JSON-Objekt, das den Datenschutz und die Indexierbarkeit der Datei steuert und zwei Felder enthält: access, das erforderlich ist, und ttl, das einen Zeitraum angibt, nach dem die Datei automatisch gelöscht wird. Wenn Sie das ttl-Feld verwenden:
  • Die Mindestdauer, die festgelegt werden muss, beträgt 1 Tag.
  • Der maximale Zeitraum, der festgelegt werden kann, beträgt 1 Jahr.
  • Nach dem festgelegten Zeitraum wird die Datei vollständig gelöscht. Nach dem Löschen kann die Datei nicht wiederhergestellt werden.

folderIdDie ID des Ordners, in den die Datei hochgeladen wird. Entweder dieses Feld oder folderPath muss in Ihrer Anfrage angegeben werden (aber nicht beides).
folderPathDer Pfad des Ordners, in den die Datei hochgeladen wird. Entweder dieses Feld oder folderId muss in Ihrer Anfrage angegeben werden (aber nicht beides).
fileNameDer Name der Datei. Wird kein Name angegeben, wird ein Name aus dem Inhalt der Datei generiert.
charsetHunchZeichensatzcodierung für die hochgeladene Datei. Falls nicht angegeben, wird sie aus der Datei abgeleitet.
Im folgenden Beispiel soll eine Datei mit den folgenden Kriterien in Ihren HubSpot-Account hochgeladen werden:
  • Dateiname: cat.png
  • Zielordner im HubSpot-Datei-Manager: /library/cat_archive
  • Zugriff auf die Datei in HubSpot: privat zugänglich
Die folgenden Header und der Anfragetext müssten Teil Ihrer Anfrage sein: 
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
Die resultierende Antwort enthält die id und parentFolderId der hochgeladenen Datei, mit der Sie die Datei über eine GET-Anfrage abrufen können. 
// 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"
}

​
Den Upload-Status einer Datei überprüfen

Wenn Sie eine Datei mithilfe einer POST-Anfrage an files/v3/files/import-from-url/async von einer URL in Ihren Datei-Manager importieren, können Sie den Upload-Status der Datei überprüfen. Führen Sie dazu eine GET-Anfrage an files/v3/files/import-from-url/async/tasks/{taskId}/status durch. Nachdem Sie diese Anfrage durchgeführt haben, erhalten Sie eine der folgenden Antworten:
  • PENDING: die Datei befindet sich in der Warteschlange, die hochgeladen werden soll. Der Importvorgang hat noch nicht begonnen.
  • PROCESSING: die Datei wird gerade hochgeladen.
  • CANCELED: der Upload wurde abgebrochen und die Datei wird nicht hochgeladen. Um die Datei in Ihren HubSpot-Account zu importieren, müssen Sie die Datei erneut hochladen.
  • COMPLETE: die Datei wurde erfolgreich in das Dateien-Tool hochgeladen. Die hochgeladene Datei wird in Ihrem Dateien-Tool angezeigt.

​
Details einer Datei anzeigen

Um sich die Details einer Datei anzusehen, die in das Dateien-Tool hochgeladen wurde, führen Sie eine GET-Anfrage an files/v3/files/{fileId} durch. Dadurch wird die Datei mit Details wie Name, Höhe und Breite, Codierung, URL und mehr zurückgegeben. So rufen Sie beispielsweise die Details einer Datei ab: Wenn eine Datei auf „privat“ festgelegt ist, führt die zurückgegebene URL zu einem 404-Fehler. Um eine aufrufbare URL der Datei zu erhalten, können Sie eine GET-Anfrage an /files/v3/files/{fileId}/signed-url vornehmen. Wenn Sie diese Anfrage durchführen, können Sie property-Parameter einschließen, damit spezifische Eigenschaften wie Höhe und Breite zurückgegeben werden.

​
Eine Datei löschen

Um eine Datei zu löschen, führen Sie eine DELETE-Anfrage an files/v3/files/{fileId} durch. Dadurch wird die Datei als gelöscht markiert und der Inhalt der Datei kann nicht mehr aufgerufen werden. Um eine Datei vollständig zu löschen, führen Sie eine DELETE-Anfrage an files/v3/files/{fileId}/gdpr-delete vor. Dadurch werden der Inhalt und die Metadaten der Datei innerhalb von 7 Tagen vollständig gelöscht. Wenn eine Datei nicht DSGVO-konform gelöscht wird, bleiben ihre Inhalte auf den HubSpot-Servern in einem privaten Zustand gespeichert, bei dem kein Benutzer darauf zugreifen kann. Um sicherzustellen, dass Dateiinhalte vollständig gelöscht werden, verwenden Sie die Funktionalität für eine DSGVO-konforme Löschung.

​
Einen Ordner erstellen

Um einen Ordner zu erstellen, führen Sie eine POST-Anfrage an files/v3/folders durch. Bei der Anfrage können Sie die folgenden Felder einbeziehen.
FeldErforderlichBeschreibung
nameJaName des Ordners, den Sie erstellen möchten.
parentFolderIdNeinUm den Ordner innerhalb eines vorhandenen Ordners zu erstellen, berücksichtigen Sie dieses Feld in der ID des vorhandenen Ordners. parentFolderId und parentFolderPath können nicht gleichzeitig festgelegt werden.
parentFolderPathNeinUm den Ordner innerhalb eines vorhandenen Ordners zu erstellen, berücksichtigen Sie dieses Feld im Pfad des vorhandenen Ordners ein. parentFolderId und parentFolderPath können nicht gleichzeitig festgelegt werden.
//Example request body of POST request to /files/v3/folders
{
  "name": "myNewFolder",
  "parentFolderId": 12345
}

​
Änderungen in v3

Wenn Sie bislang die vorherige Version dieser API verwendet haben, müssen Sie bei v3 folgende Änderungen berücksichtigen:
  • Alle über die API hochgeladenen Dateien sind im Dateien-Dashboard und in der Dateiauswahl sichtbar. Ausgeblendete Dateien können nicht erstellt werden. Private Dateien und nicht-indexierbare Dateien können jedoch weiterhin erstellt werden.
  • Listing-Dateien geben ausgeblendete oder gelöschte Dateien nicht zurück. Es kann jedoch eine wesentlich breitere Spanne von Filtern angewendet werden. Ausgeblendete Dateien können weiterhin nach ID abgerufen werden, erfordern jedoch einen neuen Bereich: files_ui_hidden.read..
  • Es können nicht mehrere Dateien mit einer einzigen Anfrage hochgeladen werden.
  • Ordneraktualisierungsaktionen wie das Verschieben und Umbenennen sind jetzt asynchron. Jede Anfrage gibt ein Token zurück, das verwendet werden kann, um den Status des Ordners zu überprüfen.
  • Für Endpunkte, die Dateien erstellen oder ersetzen, müssen Sie Zugriffsebenen für die Dateien angeben. Diese Zugriffsebenen sind:
    • PUBLIC_INDEXABLE: Die Datei ist für alle, die die URL kennen, öffentlich zugänglich. Suchmaschinen können die Datei indexieren.
    • PUBLIC_NOT_INDEXABLE: Die Datei ist für alle, die die URL kennen, öffentlich zugänglich. Das X-Robots-Tag: Der noindex-Header wird bei jedem Abrufen der Datei gesendet. Dabei werden Suchmaschinen angewiesen, die Datei nicht zu indexieren.
    • PRIVATE: Die Datei ist nicht öffentlich zugänglich. Eine signierte URL ist erforderlich, um Inhalte anzuzeigen. Suchmaschinen können die Datei nicht indexieren.
  • Endpunkte, die Dateien erstellen, ermöglichen ein gewisses Maß an Erkennung von Duplikaten als Teil der Upload-Optionen der Datei.
    • ENTIRE_PORTAL: Es wird nach einer doppelten Datei im Account gesucht.
    • EXACT_FOLDER: Es wird im angegebenen Ordner nach einer doppelten Datei gesucht.
    • NONE: Es wird keine Überprüfung auf Duplikate ausgeführt.
    • REJECT: Der Upload wird abgelehnt, wenn ein Duplikat gefunden wird.
    • RETURN_EXISTING: Wenn eine doppelte Datei gefunden wird, darf keine neue Datei hochgeladen werden. Stattdessen wird das gefundene Duplikat zurückgegeben.
    • Die Erkennung von Duplikaten erfolgt in einem duplicateValidationScope, was sich auf die Art und Weise auswirkt, wie wir nach einem Duplikat suchen.
    • Dies erfordert auch eine duplicateValidationStrategy, die vorgibt, was passiert, wenn ein Duplikat gefunden wird.