Letzte Änderung: 22. August 2025

Run in Postman

 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.

​
Hinweis:

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 Text-Werte 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": "+18884827768",
"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. 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: 
///Example request body
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"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
}
]
}
]
}
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.

​
Kontakte nach Datensatz-ID, E-Mail oder benutzerdefinierter „Eindeutiger Wert“-Eigenschaft 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:

​
Kontakte aktualisieren

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: 
{
  "properties": {
    "favorite_food": "burger",
    "jobtitle": "Manager",
    "lifecyclestage": "Customer"
  }
}

​
Hinweis:

Wenn Sie die lifecyclestage-Eigenschaft aktualisieren, können Sie den Wert in der Phasenreihenfolge nur vorwärts setzen. Um die Lifecycle-Phase nach vorn zu setzen, müssen Sie zunächst den bestehenden Lifecycle-Phasenwert des Datensatzes löschen. Der Wert kann manuell gelöscht werden oder automatisch über einen Workflow oder eine Integration, die Kontaktdaten synchronisiert, gelöscht werden.
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: 
{
  "inputs": [
    {
      "id": "123456789",
      "properties": {
        "favorite_food": "burger"
      }
    },
    {
      "id": "56789123",
      "properties": {
        "favorite_food": "Donut"
      }
    }
  ]
}

​
„Upsert“ von Kontakten

Mit dem upsert-Endpunkt können Sie auch gleichzeitig Kontakte erstellen und aktualisieren. Für diesen Endpunkt können Sie eine email- oder eine benutzerdefinierte Eigenschaft mit eindeutiger ID verwenden. Wenn die Kontakte bereits vorhanden sind, werden sie nach der Anfrage aktualisiert. Falls die Kontakte noch nicht vorhanden sind, werden sie erstellt. Für das „Upsert“ von Kontakten stellen Sie eine POST-Anfrage an /crm/v3/objects/contacts/batch/upsert. Fügen Sie in Ihrem Anforderungstext den idProperty-Parameter ein, um zu identifizieren, ob Sie eine email- oder eine benutzerdefinierte eindeutige ID-Eigenschaft verwenden. Fügen Sie den Wert dieser Eigenschaft als id sowie die anderen Eigenschaften hinzu, die Sie festlegen oder aktualisieren möchten.

​
Hinweis:

Teilweise „Upserts“ werden nicht unterstützt, wenn email als idProperty für Kontakte verwendet wird. Um ein teilweises „Upsert“ abzuschließen, verwenden Sie stattdessen eine benutzerdefinierte „Eindeutige ID“-Eigenschaft als idProperty.
Ihre Anfrage könnte beispielsweise wie folgt aussehen: 
{
  "inputs": [
    {
      "properties": {
        "phone": "+18884827768"
      },
      "id": "test@test.com",
      "idProperty": "email"
    },
    {
      "properties": {
        "phone": "+18888888888"
      },
      "id": "example@hubspot.com",
      "idProperty": "email"
    }
  ]
}

​
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 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}.

​
Eine Aktivität an einen Kontaktdatensatz anpinnen

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: 
{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}
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: 
{
  "properties": {
    "email": "example@hubspot.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+18884827768",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": {
        "id": 123456789
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 201
        }
      ]
    }
  ]
}

​
Kontakte löschen

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 in der Referenzdokumentation mehr über das massenweise Löschen von Kontakten.

​
Zusätzliche E-Mail-Adressen

Zusätzliche E-Mail-Adressen werden verwendet, wenn ein Kontakt mehr als eine E-Mail-Adresse hat. Diese können manuell zu einem Kontaktdatensatz in HubSpot oder automatisch nach einer Zusammenführung von Kontakten hinzugefügt werden. Zusätzliche E-Mail-Adressen sind ebenfalls eindeutige IDs für Kontakte. Mehrere Kontakte können also nicht dieselben zusätzlichen E-Mail-Adressen haben. Um zusätzliche E-Mail-Adressen für Kontakte anzuzeigen, schließen Sie beim Abrufen aller oder einzelner Kontakte den properties-Parameter mit den Eigenschaften email und hs_additional_emails ein. Die primäre E-Mail-Adresse eines Kontakts wird im Feld email angezeigt. Weitere E-Mail-Adressen werden im Feld hs_additional_emails angezeigt.

​
Beschränkungen

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.