Bis zum Hauptinhalt springen

In HubSpot speichern Kontakte Informationen zu den einzelnen Personen, die mit Ihrem Unternehmen interagieren. Die Kontakte-Endpunkte ermöglichen es Ihnen, Kontaktdatensätze in Ihrem HubSpot-Account zu erstellen und zu verwalten sowie Kontaktdaten zwischen HubSpot und anderen Systemen zu synchronisieren.

Erfahren Sie mehr über Objekte, Datensätze, Eigenschaften und Zuordnungen-APIs im Leitfaden Grundlegendes zum CRM. Weitere allgemeine Informationen zu Objekten und Datensätzen in HubSpot finden Sie in diesem Artikel über das Verwalten Ihrer CRM-Datenbank.

Um neue Kontakte zu erstellen, führen Sie eine POST-Anfrage an /crm/v3/objects/contacts durch.

Schließen Sie in Ihrer Anfrage Ihre Kontaktdaten in ein properties-Objekt ein. Sie können auch ein associations-Objekt hinzufügen, um Ihrem neuen Kontakt vorhandene Datensätze (z. B. Unternehmen, Deals) oder Aktivitäten (z. B. Meetings, Notizen) zuzuordnen.

Kontaktdetails werden in Kontakteigenschaften gespeichert. Es gibt Standard-HubSpot-Kontakteigenschaften, Sie können jedoch auch benutzerdefinierte Eigenschaften erstellen.

Wenn Sie einen neuen Kontakt erstellen, sollten Sie mindestens eine der folgenden Eigenschaften in Ihre Anfrage aufnehmen: email, firstname oder lastname. Es wird empfohlen, immer email einzuschließen, da E-Mail-Adressen die primäre eindeutige ID sind, um doppelte Kontakte in HubSpot zu vermeiden.

Um alle verfügbaren Eigenschaften anzuzeigen, können Sie eine Liste der Kontakteigenschaften Ihres Accounts abrufen, indem Sie eine GET-Anfrage an /crm/v3/properties/contacts durchführen. Erfahren Sie mehr über die Eigenschaften-API.

Um beispielsweise einen neuen Kontakt zu erstellen, kann Ihre Anfrage wie folgt aussehen:

Beim Erstellen eines neuen Kontakts können Sie den Kontakt auch mit bestehenden Datensätzen oder Aktivitäten verknüpfen. können Sie den Kontakt auch bestehenden Datensätzen oder Aktivitäten zuordnen, indem Sie ein associations-Objekt einschließen. Um beispielsweise einen neuen Kontakt mit einem bestehenden Unternehmen und einer vorhandenen E-Mail zu verknüpfen, würde Ihre Anfrage wie folgt aussehen:

Im associations-Objekt sollten Sie Folgendes einschließen:

ParameterBeschreibung
toDer Datensatz oder die Aktivität, den bzw. die Sie dem Kontakt zuordnen möchten, angegeben durch seinen bzw. ihren eindeutigen id-Wert.
typesDer Typ der Zuordnung zwischen dem Kontakt und dem Datensatz/der Aktivität. Beziehen Sie die associationCategory und associationTypeId ein. Standardzuordnungstyp-IDs sind hier aufgeführt. Sie können den Wert für benutzerdefinierte Zuordnungstypen (d. h. Label) über die Zuordnungen-API abrufen.

Sie können Kontakte einzeln oder in Batches abrufen.

  • Um einen einzelnen Kontakt abzurufen, führen Sie eine GET-Anfrage an /crm/v3/objects/contacts/{contactId} or /crm/v3/objects/contacts/{email}?idProperty=email durch.
  • Um eine Liste aller Kontakte anzufordern, führen Sie eine GET-Anfrage an /crm/v3/objects/contacts durch.

Sie können für diese Endpunkte die folgenden Abfrageparameter in die Anfrage-URL einschließen:

ParameterBeschreibung
propertiesEine durch Kommas getrennte Liste der Eigenschaften, die in der Antwort zurückgegeben werden sollen. Wenn der angefragte Kontakt keinen Wert für eine Eigenschaft hat, wird er nicht in der Antwort angezeigt.
propertiesWithHistoryEine durch Kommas getrennte Liste der aktuellen und historischen Eigenschaften, die in der Antwort zurückgegeben werden sollen. Wenn der angefragte Kontakt keinen Wert für eine Eigenschaft hat, wird er nicht in der Antwort angezeigt.
associationsEine durch Kommas getrennte Liste von Objekten, für die zugehörige IDs abgerufen werden sollen. Alle angegebenen Zuordnungen, die nicht vorhanden sind, werden nicht in der Antwort zurückgegeben. Erfahren Sie mehr über die Zuordnungen-API

Für den Batch-Leseendpunkt können Sie den optionalen idProperty-Parameter verwenden, um Kontakte nach email oder einer benutzerdefinierten „Eindeutige ID“-Eigenschaft abzurufen. Standardmäßig beziehen sich die id-Werte in der Anfrage auf die Datensatz-ID (hs_object_id), sodass der idProperty-Parameter beim Abrufen nach Datensatz-ID nicht erforderlich ist. Wenn Sie email oder eine benutzerdefinierte „Eindeutiger Wert“-Eigenschaft zum Abrufen von Kontakten verwenden, müssen Sie den idProperty-Parameter angeben.

Um beispielsweise einen Batch von Kontakten basierend auf Datensatz-ID-Werten abzurufen, könnte Ihre Anfrage wie folgt aussehen (nur aktuelle Werte oder aktuelle und historische Werte):

Um Kontakte basierend auf der E-Mail-Adresse oder einer benutzerdefinierten „Eindeutige ID“-Eigenschaft (z. B. eine für Ihr Unternehmen eindeutige Kunden-ID-Nummer) abzurufen, sieht Ihre Anfrage wie folgt aus:

Sie können Kontakte einzeln oder mehrere gleichzeitig aktualisieren.

Um einzelne Kontakte zu aktualisieren, können Sie die Datensatz-ID (id) oder die E-Mail-Adresse des Kontakts (email) verwenden.

  • Um einen einzelnen Kontakt anhand seiner Datensatz-ID zu aktualisieren, führen Sie eine PATCH-Anfrage an /crm/v3/objects/contacts/{contactId} durch und schließen Sie die Daten ein, die Sie aktualisieren möchten.
  • Um einen einzelnen Kontakt anhand seiner E-Mail-Adresse zu aktualisieren, führen Sie eine PATCH-Anfrage an /crm/v3/objects/contacts/{email}?idProperty=email durch und schließen Sie die Daten ein, die Sie aktualisieren möchten.

Zum Beispiel:

Um Kontakte in Batches zu aktualisieren, können Sie die Datensatz-ID-Werte der Kontakte (id) verwenden. Um mehrere Kontakte zu aktualisieren, führen Sie eine POST-Anfrage an /crm/v3/objects/contacts/batch/update durch. Geben Sie in Ihrem Anforderungstext die Datensatz-ID jedes Kontakts als id und berücksichtigen Sie die Eigenschaften, die Sie aktualisieren möchten.

Zum Beispiel:

Um einen Kontakt anderen CRM-Datensätzen oder einer Aktivität zuzuordnen, führen Sie eine PUT-Anfrage an /crm/v3/objects/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId} durch.

Erfahren Sie mehr über die Zuordnungen-API.

Um eine Zuordnung zwischen einem Kontakt und einem Datensatz oder einer Aktivität zu entfernen, führen Sie eine DELETE-Anfrage an die folgende URL durch: /crm/v3/objects/contacts/{contactID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.

Sie können eine Aktivität an einen Kontaktdatensatz anpinnen , indem Sie das hs_pinned_engagement_id-Feld in Ihre Anfrage aufnehmen. Geben Sie im Feld die id der anzupinnenden Aktivität an, die über die Interaktionen-APIs abgerufen werden kann. Sie können eine Aktivität pro Datensatz anpinnen, und die Aktivität muss bereits vor dem Anpinnen mit dem Kontakt verknüpft sein.

Um die angepinnte Aktivität eines Kontakts festzulegen oder zu aktualisieren, könnte Ihre Anfrage wie folgt aussehen:

Sie können auch einen Kontakt erstellen, ihn mit einer vorhandenen Aktivität verknüpfen und die Aktivität in derselben-Anfrage anpinnen. Zum Beispiel:

Sie können Kontakte einzeln oder mehrere gleichzeitig löschen, wodurch der Kontakte in den Papierkorb in HubSpot verschoben wird. Sie können den Kontakt später in HubSpot wiederherstellen.

Um einen einzelnen Kontakt anhand seiner ID zu löschen, führen Sie eine DELETE-Anfrage an /crm/v3/objects/contacts/{contactId} durch.

Erfahren Sie mehr über das gleichzeitige Löschen von mehreren Kontakten, indem Sie oben in diesem Artikel auf die Registerkarte Endpunkte klicken.

Batch-Vorgänge sind auf jeweils 100 Datensätze beschränkt. Sie können beispielsweise nicht mehr als 100 Kontakte in einer Anfrage per Batch aktualisieren. Es gibt auch Limits für Kontakte und Formulareinsendungen.