Importe

ÜberblickEndpunkte

Verwenden Sie die Importe-API, um CRM-Datensätze und -Aktivitäten in Ihren HubSpot-Account zu importieren, z. B. Kontakte, Unternehmen und Notizen. Nach dem Import können Sie über die verschiedenen CRM-API-Endpunkte auf Datensätze und Aktivitäten zugreifen und diese aktualisieren, einschließlich der Kontakte-API, Zuordnungen-API und Interaktionen-APIs. Sie können auch Datensätze und Aktivitäten mit dem anleitenden Import-Tool nach HubSpot importieren.

Bevor Sie mit dem Import beginnen, informieren Sie sich über die Objekte und Aktivitäten, die importiert werden können, sowie über die Datei- und Eigenschaftsanforderungen.

Einen Import starten

Sie können einen Import starten, indem Sie eine POST-Anfrage an /crm/v3/Imports durchführen, die einen Anfragetext enthält, der angibt, wie die Spalten Ihrer Importdatei den zugehörigen CRM-Eigenschaften in HubSpot zugeordnet werden sollen.

API-Importe werden als form-data-Typ-Anfragen gesendet, wobei der Anfragetext die folgenden Felder enthält:

  • importRequest: ein Textfeld, das den Anfrage-JSON enthält.
  • files: Ein Dateifeld, das die Importdatei enthält.

Fügen Sie für den Anfrage-Header einen Content-Type-Header mit dem Wert multipart/form-data hinzu.

Der folgende Screenshot zeigt, wie Ihre Anfrage bei der Verwendung einer Anwendung wie Postman aussehen könnte:

postman-import-request-no-response0

Die importRequest-Daten formatieren

Definieren Sie in der JSON-Anfrage die Details der Importdatei, einschließlich der Zuordnung der Spalten der Tabelle zu HubSpot-Daten. Ihr Anfrage-JSON sollte die folgenden Felder enthalten:

  • name: der Name der Imports. In HubSpot ist dies der Name, der im Import-Tool angezeigt wird, sowie der Name, auf den Sie in anderen Tools wie Listen verweisen können.
  • importOperations: ein optionales Feld, das angibt, ob der Import für ein bestimmtes Objekt oder eine bestimmte Aktivität Datensätze erstellen und aktualisieren, sie nur erstellen oder nur aktualisieren soll. Fügen Sie die objectTypeId für das Objekt/die Aktivität ein und ob Datensätze erstellt und aktualisiert (UPSERT), nur erstellt (CREATE) oder nur aktualisiert (UPDATE) werden sollen. Zum Beispiel würde das Feld in Ihrer Anfrage wie folgt aussehen: "importOperations": {"0-1": "CREATE"}. Wenn Sie dieses Feld nicht einschließen, ist der Standardwert für den Import UPSERT.
  • dateFormat: das Format für Daten, die in der Datei berücksichtigt werden. Standardmäßig wird dieser auf MONTH_DAY_YEAR festgelegt, aber Sie können auch DAY_MONTH_YEAR oder YEAR_MONTH_DAY verwenden.
  • marketableContactImport: ein optionales Feld, um den Marketingstatus von Kontakten in Ihrer Importdatei anzugeben. Dies wird nur verwendet, wenn Kontakte in Accounts importiert werden, die Zugriff auf Marketingkontakte haben. Um die Kontakte in der Datei als Marketingkontakte einzustufen, verwenden Sie den Wert true. Um die Kontakte in der Datei als Nicht-Marketingkontakte einzustufen, verwenden Sie den Wert false. 
  • createContactListFromImport: ein optionales Feld zum Erstellen einer statischen Liste der Kontakte aus Ihrem Import. Um eine Liste aus Ihrer Datei zu erstellen, verwenden Sie den Wert true.
  • files: ein Array, das Ihre Importdateiinformationen enthält.
    • fileName: der Name der Importdatei.
    • fileFormat: das Format der Importdatei. Verwenden Sie bei CSV-Dateien den Wert CSV. Verwenden Sie bei Excel-Dateien den Wert SPREADSHEET.
    • fileImportPage: enthält das columnMappings-Array, das zum Zuordnen von Daten aus Ihrer Importdatei zu HubSpot-Daten erforderlich ist. Im Folgenden erfahren Sie mehr über das Zuordnen von Spalten.

Dateispalten zu HubSpot-Eigenschaften zuordnen

Fügen Sie innerhalb des columnMappings-Arrays einen Eintrag für jede Spalte in Ihrer Importdatei ein, der der Reihenfolge Ihrer Tabelle entspricht. Fügen Sie für jede Spalte die folgenden Felder hinzu:

  • columnObjectTypeId: der Name oder objectTypeId-Wert des Objekts oder der Aktivität, zu dem/der die Daten gehören. Eine vollständige Liste der objectTypeId-Werte finden Sie in diesem Artikel.
  • columnName: der Name der Spaltenüberschrift.
  • propertyName: der interne Name der HubSpot-Eigenschaft, welcher die Daten zugeordnet werden. Für die gemeinsame Spalte in Importe von mehreren Dateien muss propertyName null sein, wenn das Feld toColumnObjectTypeId verwendet wird.
  • columnType: Wird verwendet, um anzugeben, dass eine Spalte eine „Eindeutige ID“-Eigenschaft enthält. Verwenden Sie abhängig von der Eigenschaft und dem Ziel des Imports einen der folgenden Werte:
    • HUBSPOT_OBJECT_ID: die ID eines Datensatzes. Beispielsweise kann Ihre Kontaktimportdatei eine Spalte mit der Datensatz-ID enthalten, in der die ID des Unternehmens gespeichert ist, dem die Kontakte zugeordnet werden sollen.
    • HUBSPOT_ALTERNATE_ID: eine eindeutige ID, die sich von der Datensatz-ID unterscheidet. Beispielsweise kann Ihre Kontaktimportdatei eine E-Mail-Spalte enthalten, in der die E-Mail-Adressen der Kontakte gespeichert sind.
    • ASSOCIATION_KEYS: Fügen Sie nur für Importe mit Zuordnungen gleicher Objekte diesen Spaltentyp für die eindeutige ID der Datensätze des gleichen Objekttyps hinzu, die Sie zuordnen. Beispielsweise muss in Ihrer Anfrage für einen Kontaktzuordnungsimport die Spalte [E-Mail/Datensatz-ID] des zugeordneten Kontakt einen columnType vom Typ ASSOCIATION_KEYS aufweisen. Erfahren Sie mehr über das Einrichten Ihrer Importdatei bei einem Import mit Zuordnungen des gleichen Objekttyps.
  • toColumnObjectTypeId: gilt nur für Importe von mehreren Dateien, der Name oder die objectTypeId des Objekts, zu dem die Eigenschaft gemeinsame Spalte gehört. Fügen Sie dieses Feld für die Eigenschaft „Gemeinsame Spalte“ (und ggf. die Spalte „Zuordnungslabel“) in die Datei des Objekts ein, zu dem die Eigenschaft nicht gehört. Wenn Sie beispielsweise Kontakte und Unternehmen in zwei Dateien mit der Kontakteigenschaft E-Mail als gemeinsame Spalte verknüpfen, fügen Sie die toColumnObjectTypeId für die Spalte E-Mail in die Unternehmensdatei ein.
  • foreignKeyType: gilt nur für Importe von mehreren Dateien, die Art der Zuordnung, die die gemeinsame Spalte verwenden soll, angegeben durch die associationTypeId und associationCategory. Fügen Sie dieses Feld für die Eigenschaft „Gemeinsame Spalte“ in die Datei des Objekts ein, zu dem die Eigenschaft nicht gehört. Wenn Sie beispielsweise Kontakte und Unternehmen in zwei Dateien mit der Kontakteigenschaft E-Mail als gemeinsame Spalte verknüpfen, fügen Sie den foreignKeyType für die Spalte E-Mail in die Unternehmensdatei ein.
  • associationIdentifierColumn: nur für Importe von mehreren Dateien, gibt die Eigenschaft an, die in der gemeinsamen Spalte zum Zuordnen der Datensätze verwendet wird. Fügen Sie dieses Feld für die Eigenschaft „Gemeinsame Spalte“ in die Datei des Objekts ein, zu dem die Eigenschaft gehört. Wenn Sie beispielsweise Kontakte und Unternehmen in zwei Dateien mit der Kontakteigenschaft E-Mail als gemeinsame Spalte verknüpfen, legen Sie die associationIdentifierColumn als true für die Spalte E-Mail in der Kontaktdatei fest.

Eine einzige Datei importieren

Nachfolgend finden Sie ein Beispiel für einen Anfragetext für das Importieren einer Datei, um Kontakte zu erstellen:

// 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

Mehrere Dateien importieren

Nachfolgend finden Sie ein Beispiel für einen Anfragetext für das Importieren und Zuordnen von Kontakten und Unternehmen in zwei Dateien, wobei die Kontakteigenschaft E-Mail die gemeinsame Spalte in den Dateien ist:

// 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" } } ] } } ] }

Bei einer erfolgreichen Anfrage enthält die Antwort eine importId, mit der Sie den Import abrufen oder abbrechen können. 

Vorherige Importe abrufen

Um alle Importe von Ihrem HubSpot-Account abzurufen, führen Sie eine GET-Anfrage an /crm/v3/imports/ durch. Um Informationen für einen bestimmten Import abzurufen, führen Sie eine GET-Anfrage an /crm/v3/imports/{importId} durch.

Wenn Sie Importe abrufen, werden Informationen zurückgegeben, einschließlich des Namens, der Quelle, des Dateiformats, der Sprache, des Datumsformats und der Spaltenzuordnungen des Imports. Der state des Imports wird ebenfalls zurückgegeben, was eine der folgenden Optionen sein kann:

  • STARTED: HubSpot erkennt, dass der Import vorhanden ist, der Import hat jedoch noch nicht mit der Verarbeitung begonnen.
  • PROCESSING: Der Import wird aktiv verarbeitet.
  • DONE: Der Import ist abgeschlossen. Alle Objekte, Aktivitäten oder Zuordnungen wurden aktualisiert oder erstellt.
  • FAILED: Es liegt ein Fehler vor, der beim Starten des Imports nicht erkannt wurde. Der Import wurde nicht abgeschlossen.
  • CANCELED: Der Benutzer hat den Export abgebrochen, während er sich in einem der Zustände "STARTED, PROCESSING oder DEFERRED befand.
  • DEFERRED: Die maximale Anzahl von Importen (drei) wird gleichzeitig verarbeitet. Der Import wird gestartet, sobald einer der anderen Importe die Verarbeitung abgeschlossen hat.

Weitere Informationen zum Durchblättern und Beschränken der Ergebnisse finden Sie auf der Registerkarte Endpunkte oben in diesem Artikel.

Bitte beachten: Wenn Sie Importe mit einem Zugriffstoken für private Apps abrufen, enthält die Antwort nur Importe, die von dieser privaten App durchgeführt werden. Importe, die in HubSpot oder über eine andere private App abgeschlossen wurden, werden nicht zurückgegeben.

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.

Bitte beachten: Wenn Sie einen Fehler erhalten, überprüfen Sie, ob es doppelte Header gibt, z. B. Content-Type. Dies kann vorkommen, wenn Sie Postman verwenden oder wenn es im Header Ihres Python-Skripts enthalten ist. Entfernen Sie das Duplikat, bevor Sie die Anfrage abschließen. 

Beschränkungen

Wenn Sie die Importe-API verwenden, können Sie bis zu 80.000.000 Zeilen pro Tag importieren. Einzelne Importdateien sind jedoch auf 1.048.576 Zeilen oder 512 MB beschränkt, je nachdem, was zuerst erreicht wird.

Wenn Ihre Anfrage die Zeilen- oder Größenbeschränkung überschreitet, gibt HubSpot einen 429-HTTP-Fehler zurück. Wenn Sie sich diesen Beschränkungen nähern, wird empfohlen, Ihren Import in mehrere Anfragen aufzuteilen.  

War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.