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"}.
  • 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.
  • columnType: wird verwendet, um anzugeben, dass eine Spalte eine eindeutige ID-Eigenschaft enthält. Verwenden Sie je nach Eigenschaft 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.

Nachfolgend finden Sie ein Beispiel für einen Anfragetext für das Importieren, 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

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 more general errors, such as 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 column order in the request body and import file should match, and every column needs to be mapped.
  • 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.