Kontakte

ÜberblickEndpunkte

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.

Kontakte erstellen

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.

Eigenschaften

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.

Bitte beachten: Wenn Sie lifecyclestage in Ihre Anfrage aufgenommen haben, müssen sich die Werte auf den internen Namen der Lifecycle-Phase beziehen. Die internen Namen der Standardphasen sind Textwerte und ändern sich auch nicht, wenn Sie das Label der Phase bearbeiten (z. B. subscriber oder marketingqualifiedlead). Die internen Namen von benutzerdefinierten Phasen sind numerische Werte. Sie können die interne ID einer Phase in Ihren Einstellungen für Lifecycle-Phasen finden, oder indem Sie die Lifecycle-Phase-Eigenschaft über die API abrufen.

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

///Example request body { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "company": "HubSpot", "website": "hubspot.com", "lifecyclestage": "marketingqualifiedlead" } }

Zuordnungen

Beim Erstellen eines neuen Kontakts können Sie den Kontakt auch mit bestehenden Datensätzen oder Aktivitäten verknüpfen. Schließen Sie im associations-Objekt die folgenden Felder ein:

Use this table to describe parameters / fields
ParameterDescription
toObjectId

Die ID des Datensatzes oder der Aktivität, dem oder der der Kontakt zugeordnet werden soll.

associationTypeId

Eine eindeutige ID, die den Zuordnungstyp zwischen dem Kontakt und dem anderen Objekt oder der anderen Aktivität angibt. Standardzuordnungstypen sind hier aufgeführt, oder Sie können den Wert abrufen, indem Sie eine GET-Anfrage an /crm/v4/associations/{fromObjectType}/{toObjectType}/labels durchführen. Erfahren Sie mehr über die Zuordnungen-API.

Sie können auch das label-Feld hinzufügen, um ein definiertes Zuordnungslabel zuzuweisen, das die Zuordnung beschreibt. Erfahren Sie mehr über das Zuordnen von Datensätzen über die Zuordnungen-API.

Um beispielsweise einen neuen Kontakt mit einem bestehenden Unternehmen und einer vorhandenen E-Mail zu verknüpfen, würde Ihre Anfrage wie folgt aussehen:

///Example request body { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "company": "HubSpot", "website": "hubspot.com", "lifecyclestage": "marketingqualifiedlead" }, "associations": [ { "to": { "id": 123456 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 279 } ] }, { "to": { "id": 556677 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 197 } ] }] }

Kontakte 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 durch.
  • Um eine Liste aller Kontakte anzufragen, 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: 

Use this table to describe parameters / fields
ParameterDescription
properties

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

propertiesWithHistory

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

associations

Eine 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):

///Example request body with record ID (current values) { "properties": [ "email", "lifecyclestage", "jobtitle" ], "inputs": [ { "id": "1234567" }, { "id": "987456" } ] }
///Example request body with record ID (current and historical values) { "propertiesWithHistory": [ "lifecyclestage", "hs_lead_status" ], "inputs": [ { "id": "1234567" }, { "id": "987456" } ] }

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:

///Example request body with email { "properties": [ "email", "lifecyclestage", "jobtitle" ], "idProperty": "email", "inputs": [ { "id": "lgilmore@thedragonfly.com" }, { "id": "sstjames@thedragonfly.com" } ] }
///Example request body with a unique value property { "properties": [ "email", "lifecyclestage", "jobtitle" ], "idProperty": "internalcustomerid", "inputs": [ { "id": "12345" }, { "id": "67891" } ] }

Kontakte aktualisieren

Sie können Kontakte einzeln oder mehrere gleichzeitig aktualisieren. Bei vorhandenen Kontakten sind E-Mail und Datensatz-ID eindeutige Werte, sodass Sie id oder email zum Aktualisieren von Kontakten über die API verwenden können.

Um einen einzelnen Kontakt anhand seiner Kontakt-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.

Bestehende Kontakte mit Datensätzen oder Aktivitäten verknüpfen

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.

Um den associationTypeId-Wert abzurufen, verweisen Sie auf diese Liste der Standardwerte oder führen Sie eine GET-Anfrage an/crm/v4/associations/{fromObjectType}/{toObjectType}/labels durch.

Erfahren Sie mehr über die Zuordnungen-API.

Eine Zuordnung entfernen

Um eine Verknüpfung 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}.

Eine Aktivität an einen Kontaktdatensatz anpinnen

You can pin an activity on a contact record by including the hs_pinned_engagement_id field in your request. In the field, include the id of the activity to pin, which can be retrieved via the engagements APIs. You can pin one activity per record, and the activity must already be associated with the contact prior to pinning.

To set or update a contact's pinned activity, your request could look like:

///Example request body PATCH /crm/v3/objects/contacts/{contactId} { "properties": { "hs_pinned_engagement_id": 123456789 } }

You can also create a contact, associate it with an existing activity, and pin the activity in the same request. For example:

///Example request body POST /crm/v3/objects/contacts { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "hs_pinned_engagement_id": 123456789 }, "associations": [ { "to": { "id": 123456789 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 201 }] }] }

Delete contacts

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.

Beschränkungen

Batch operations for creating, updating, and archiving are limited to batches of 100. There are also limits for contacts and form submissions.

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.