CRM-API | Importe

• Dateianforderungen
• Erforderliche Eigenschaften für das Importieren von Einträgen und Aktivitäten
• Erforderliche Eigenschaften für das Importieren von Teilnehmern an Marketingevents

​

Einen Import starten

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

​

Die importRequest-Daten formatieren

• name: Dies ist 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: Dies ist 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. Schließen Sie die objectTypeId für das Objekt / die Aktivität ein und ob Sie für Datensätze eine UPSERT-Aktion (erstellen und aktualisieren), eine CREATE-Aktion oder eine UPDATE-Aktion durchführen möchten. 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: Dies ist 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: Dies ist ein optionales Feld, um den Marketingstatus von Kontakten in Ihrer Importdatei anzugeben. Es 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: Dies ist 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: Dies ist ein Array, das Ihre Importdateiinformationen enthält.
  • fileName: Dies ist der Name der Importdatei.
  • fileFormat: Dies ist 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

• columnObjectTypeId: Dies ist 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: Dies ist der Name der Spaltenüberschrift. Dies sollte genau mit dem Namen der Spaltenüberschrift in der Datei übereinstimmen.
• propertyName: Dies ist der interne Name der HubSpot-Eigenschaft, welcher die Daten zugeordnet werden. Für die gemeinsame Spalte bei Importen von mehreren Dateien sollte propertyName den Wert null haben, wenn das toColumnObjectTypeId-Feld 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: Dies ist 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: Dies ist 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.
  • FLEXIBLE_ASSOCIATION_LABEL: Berücksichtigen Sie diesen Spaltentyp, um anzugeben, dass die Spalte Zuordnungslabel enthält.
  • 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 Zugeordneter Kontakt [E-Mail/Datensatz-ID] einen columnType vom Typ ASSOCIATION_KEYS aufweisen. Erfahren Sie mehr über das Einrichten Ihrer Importdatei bei einem Import mit Zuordnungen des gleichen Objekttyps.
• toColumnObjectTypeId: bei Importen mit mehreren Dateien oder mehreren Objekten der Name oder die objectTypeId des Objekts, zu dem die Eigenschaft Gemeinsame Spalte oder das Zuordnungslabel gehört. 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 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, wird durch die associationTypeId und associationCategory angegeben. 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 die foreignKeyType für die Spalte E-Mail in die Unternehmensdatei ein.
• associationIdentifierColumn: Gilt 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 Datei mit einem Objekt importieren

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

// Example POST to https://api.hubspot.com/crm/v3/imports
// Content-Type header set to multipart/form-data

{ "name": "Marketing Events Import Example", "marketingEventObjectId": 377224141223, "importOperations": { "0-1": "UPSERT", "0-54": "CREATE" }, "dateFormat": "YEAR_MONTH_DAY", "timeZone": "America/New_York", "files": [ { "fileName": "Marketing Events Import Example.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnName": "First Name", "columnObjectTypeId": "0-1", "propertyName": "firstname", "columnType": "STANDARD" }, { "columnName": "Last Name", "columnObjectTypeId": "0-1", "propertyName": "lastname", "columnType": "STANDARD" }, { "columnName": "Email", "columnObjectTypeId": "0-1", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" }, { "columnName": "Registered", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "REGISTERED" }, { "columnName": "Attended", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "JOINED" }, { "columnName": "Left", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "LEFT" }, { "columnName": "Cancelled", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "CANCELLED" } ] } } ] }

​

Eine Datei mit mehreren Objekten importieren

// Example POST to https://api.hubspot.com/crm/v3/imports
// Content-Type header set to multipart/form-data

{
"name": "Association Label Import",
"dateFormat": "DAY_MONTH_YEAR",
"files": [
{
"fileName": "association label example.xlsx",
"fileFormat": "SPREADSHEET",
"fileImportPage": {
"hasHeader": true,
"columnMappings": [
{
"columnObjectTypeId": "0-1",
"columnName": "Email",
"propertyName": "email"
},
{
"columnObjectTypeId": "0-2",
"columnName": "Domain",
"propertyName": "domain"
},
{
"columnName": "Association Label",
"columnType": "FLEXIBLE_ASSOCIATION_LABEL",
"columnObjectTypeId": "0-1",
"toColumnObjectTypeId": "0-2"
}
]
}
}
]
}

​

Mehrere Dateien importieren

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

​

Vorherige Importe abrufen

• 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.

​

Einen Import abbrechen

​

Importfehler überprüfen und beheben

• Stellen Sie sicher, dass für jede Spalte in Ihrer Datei eine Spaltenüberschrift vorhanden ist und dass die Anfragetext einen columnMapping-Eintrag für jede Spalte enthält. Folgende Kriterien müssen erfüllt sein:
  • Die Spaltenreihenfolge im Anfragetext und in der Importdatei muss übereinstimmen. Wenn die Spaltenreihenfolge nicht übereinstimmt, versucht das System eine automatische Neuanordnung, was jedoch möglicherweise nicht gelingt und dadurch zu einem Fehler beim Start des Imports führt.
  • Jede Spalte muss zugeordnet werden. Wenn eine Spalte nicht zugeordnet ist, ist die Importanfrage zwar trotzdem erfolgreich, führt jedoch zu einem Fehler vom Typ Falsche Spaltenanzahl, wenn der Import gestartet wird.
• Stellen Sie sicher, dass der Dateiname und das fileName-Feld in Ihrem Anfrage-JSON übereinstimmen und dass Sie die Dateierweiterung im fileName-Feld berücksichtigt haben. Zum Beispiel import_name.csv.
• Stellen Sie sicher, dass Ihr Header Content-Type mit dem Wert multipart/form-data enthält.

Example POST URL:
https://api.hubapi.com/crm/v3/imports?

Example importRequest JSON data:
This example contains 3 columns:
- First name, mapped to the firstname contact property
- Email, mapped to the email contact property
- Company ID, which contains a list of company record IDs
that the contact will be assocated with.
{
"name": "test_import",
"files": [
{
"fileName": "final_emails.csv",
"fileImportPage": {
"hasHeader": true,
"columnMappings": [
{
"ignored": false,
"columnName": "First Name",
"idColumnType": null,
"propertyName": "firstname",
"foreignKeyType": null,
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Email",
"idColumnType": "HUBSPOT_ALTERNATE_ID",
"propertyName": "email",
"foreignKeyType": null,
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Company ID",
"idColumnType": "HUBSPOT_OBJECT_ID",
"propertyName": null,
"foreignKeyType": {
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 1
},
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
}
]
}
}
]
}

​

Beschränkungen