Kontakte

Kontakte-Endpunktreferenz

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

JSON

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

 
///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. 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:

JSON

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

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

Im associations-Objekt sollten Sie Folgendes einschließen:

Parameter	Beschreibung
`to`	Der Datensatz oder die Aktivität, den bzw. die Sie dem Kontakt zuordnen möchten, angegeben durch seinen bzw. ihren eindeutigen `id`-Wert.
`types`	Der 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:

Parameter	Beschreibung
`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

Um einen Batch von bestimmten Kontakten nach Datensatz-ID, E-Mail-Adresse oder einer benutzerdefinierten „Eindeutige ID“-Eigenschaft abzurufen, führen Sie eine POST-Anfrage an crm/v3/objects/contacts/batch/read durch. Der Batch-Endpunkt kann Zuordnungen nicht abrufen. Erfahren Sie, wie Sie Zuordnungen mit der Zuordnungen-API batchweise lesen.

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

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

xxxxxxxxxx
 
// 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 address
{
  "properties": ["email", "lifecyclestage", "jobtitle"],
  "idProperty": "email",
  "inputs": [
    {
      "id": "lgilmore@thedragonfly.com"
    },
    {
      "id": "sstjames@thedragonfly.com"
    }
  ]
}

xxxxxxxxxx
 
// Example request body with email address
{
  "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"
    }
  ]
}

xxxxxxxxxx
 
// 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.

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:

// Example request body with record ID
// PATCH /crm/v3/objects/contacts/123456789
{
  "properties": {
    "favorite_food": "burger",
    "jobtitle": "Manager",
    "lifecyclestage": "Customer"
  }
}

xxxxxxxxxx
 
// Example request body with record ID
// PATCH /crm/v3/objects/contacts/123456789
{
  "properties": {
    "favorite_food": "burger",
    "jobtitle": "Manager",
    "lifecyclestage": "Customer"
  }
}

// Example request body with email address
// PATCH /crm/v3/objects/contacts/lgilmore@thedragonfly.com?idProperty=email
{
  "properties": {
    "favorite_food": "Donut",
    "jobtitle": "Owner",
    "phone": "5555555555"
  }
}

xxxxxxxxxx
 
// Example request body with email address
// PATCH /crm/v3/objects/contacts/lgilmore@thedragonfly.com?idProperty=email
{
  "properties": {
    "favorite_food": "Donut",
    "jobtitle": "Owner",
    "phone": "5555555555"
  }
}

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:

// Example request body
// POST /crm/v3/objects/contacts/batch/update
{
  "inputs": [
    {
      "id": "123456789",
      "properties": {
        "favorite_food": "burger"
      }
    },
    {
      "id": "56789123",
      "properties": {
        "favorite_food": "Donut"
      }
    }
  ]
}

xxxxxxxxxx
 
// Example request body
// POST /crm/v3/objects/contacts/batch/update
{
  "inputs": [
    {
      "id": "123456789",
      "properties": {
        "favorite_food": "burger"
      }
    },
    {
      "id": "56789123",
      "properties": {
        "favorite_food": "Donut"
      }
    }
  ]
}

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:

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

xxxxxxxxxx
 
// Example request body PATCH /crm/v3/objects/contacts/{contactId}
{
  "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:

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

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

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 mehr über das gleichzeitige Löschen von mehreren Kontakten, indem Sie oben in diesem Artikel auf die Registerkarte Endpunkte klicken.

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.