Letzte Änderung: 22. August 2025

Run in Postman
Informationen zur vorherigen Version finden Sie in der Dokumentation für die v3 Zuordnungen-API.
Zuordnungen stellen die Beziehungen zwischen Objekten und Aktivitäten im HubSpot-CRM dar. Datensatzzuordnungen können sowohl zwischen Datensätzen verschiedener Objekte (z. B. Kontakt zu Unternehmen) als auch innerhalb desselben Objekts (z. B. Unternehmen zu Unternehmen) bestehen. Sie können die Zuordnungen-Endpunkte verwenden, um Zuordnungen zwischen Datensätzen oder Datensätzen und Aktivitäten zu erstellen, abzurufen, zu aktualisieren oder zu löschen. Die Zuordnungsschema-Endpunkte ermöglichen es Ihnen, die unterstützten Zuordnungstypen in Ihrem Account anzuzeigen, Ihre eigenen Zuordnungstypen zu erstellen und Ihren Datensatzbeziehungen Label zuzuweisen. Zuordnungslabel werden zwischen Kontakten, Unternehmen, Deals, Tickets und benutzerdefinierten Objekten unterstützt und können in ganz HubSpot in Tools wie Listen und Workflows verwendet werden. Erfahren Sie mehr über Objekte, Datensätze, Eigenschaften und Zuordnungen-APIs im Leitfaden Grundlegendes zum CRM.
Bitte beachten: Die v4-Zuordnungen-API wird in Version 9.0.0 oder höher des NodeJS-HubSpot-Clients unterstützt.

​
Von HubSpot definierte Zuordnungstypen

HubSpot bietet eine Reihe vordefinierter Zuordnungstypen (z. B. Kontakt ohne Label zu Unternehmen), aber Account-Admins können ihre eigenen Zuordnungslabel definieren, um zusätzlichen Kontext für Datensatzbeziehungen bereitzustellen (z. B. Manager und Mitarbeiter). Es gibt zwei von HubSpot definierte Zuordnungstypen:
  • Primär: das Hauptunternehmen, dem der andere Datensatz zugeordnet ist. Primäre Zuordnungen können in HubSpot-Tools wie Listen und Workflows verwendet werden. Für Datensätze mit mehreren zugeordneten Unternehmen unterstützt diese API das Ändern, welches Unternehmen als primäres Unternehmen gilt.
  • Ohne Label: ein Zuordnungstyp, der hinzugefügt wird, wenn ein beliebiger Kontakt-, Unternehmens-, Deal-, Ticket- oder benutzerdefinierter Objektdatensatz zugeordnet wird. Dieser Typ gibt an, dass eine Zuordnung vorhanden ist, und wird immer in Antworten mit einem Label-Wert von null zurückgegeben. Wenn ein Datensatz über eine primäre Zuordnung oder ein benutzerdefiniertes Zuordnungslabel verfügt, werden diese Typen neben dem nicht benannten Zuordnungstyp aufgeführt.
In diesem Abschnitt können Sie alle von HubSpot definierten Zuordnungstypen anzeigen.

​
Einzelne vs. gepaarte Labels

Es gibt zwei Typen von Zuordnungslabeln, mit denen Sie die Beziehungen zwischen Datensätzen beschreiben können:
  • Einzeln: ein Label, das für beide Datensätze in der Beziehung gilt. Zum Beispiel: Freund oder Kollege.
  • Paar: ein Label-Paar, wenn unterschiedliche Wörter verwendet werden, um jede Seite der Beziehung zwischen den zugeordneten Datensätzen zu beschreiben. Zum Beispiel: Übergeordnet und Untergeordnet oder Arbeitgeber und Arbeitnehmer. Um gepaarte Label zu erstellen, müssen Sie das inverseLabel-Feld in Ihre Anfrage aufnehmen, um das zweite Label im Paar zu benennen.

​
Zuordnungstypen erstellen

Sie können benutzerdefinierte Zuordnungstypen entweder in HubSpot oder über den API-Endpunkt des Zuordnungsschemas erstellen. Sie können bis zu 10 Zuordnungstypen zwischen den einzelnen Objektpaaren erstellen (z. B. Kontakte und Unternehmen, Kontakte und Kontakte). Um einen Zuordnungstyp über die API zu erstellen, führen Sie eine POST-Anfrage an /crm/v4/associations/{fromObjectType}/{toObjectType}/labels durch und schließen Sie Folgendes in Ihre Anfrage ein:
  • name: der interne Name des Zuordnungstyps. Dieser Wert darf keine Bindestriche enthalten oder mit einem numerischen Zeichen beginnen.
  • Label : der Name des Zuordnungslabels, wie in HubSpot angezeigt.
  • inverseLabel (Nur gepaarte Labels): der Name des zweiten Labels im Label-Paar.
Ihre Anfrage könnte beispielsweise wie folgt aussehen:

​
Zuordnungstypen abrufen

Um die Zuordnungstypen zwischen bestimmten Objekten anzuzeigen, führen Sie eine GET-Anfrage an /crm/v4/associations/{fromObjectType}/{toObjectType}/labels durch. Sie erhalten ein Array, jedes Element enthält:
  • category: Gibt an, ob der Zuordnungstyp von HubSpot (HUBSPOT_DEFINED) oder von einem Benutzer (USER_DEFINED) erstellt wurde.
  • typeId: die numerische ID für diesen Zuordnungstyp. Dies wird verwendet, um beim Zuordnen von Datensätzen ein Label festzulegen. In dieser Liste finden Sie alle von HubSpot definierten typeId-Werte.
  • Label: das alphanumerische Label. Dies ist dann null für den Zuordnungstyp ohne Label.
Sie finden diese Werte auch in HubSpot in Ihren Zuordnungseinstellungen.

​
Datensätze verknüpfen

​
Datensätze ohne Label zuordnen

Sie können eine standardmäßige Zuordnung ohne Label zwischen zwei Datensätzen erstellen oder mehrere Zuordnungen ohne Label für mehrere Datensätze gleichzeitig einrichten. Um eine individuelle Standardzuordnung zwischen zwei Datensätzen einzurichten, führen Sie eine PUT-Anfrage durch an /crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId} Berücksichtigen Sie in der Anfrage-URL Folgendes:
  • fromObjectType: die ID des Objekts, das Sie zuordnen. Die ID-Werte finden Sie in dieser Liste der Objekttyp-IDs, oder für Kontakte, Unternehmen, Deals, Tickets und Notizen können Sie den Objektnamen verwenden (z. B contact, company).
  • fromObjectId: die ID des zuzuordnenden Datensatzes.
  • toObjectType: die ID des Objekts, dem Sie den Datensatz zuordnen. Die ID-Werte finden Sie in dieser Liste der Objekttyp-IDs, oder für Kontakte, Unternehmen, Deals, Tickets und Notizen können Sie den Objektnamen verwenden (z. B contact, company).
  • toObjectId: die ID des Datensatzes, der zugeordnet werden soll.
Um beispielsweise einen Kontaktdatensatz mit der ID 12345 einem Unternehmensdatensatz mit der ID 67891 zuzuordnen, würde Ihre Anfrage-URL so lauten: /crm/v4/objects/contact/12345/associations/default/company/67891. Um mehrere Standardzuordnungen gleichzeitig einzurichten, führen Sie eine POST-Anfrage an crm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/default durch. Fügen Sie im Anforderungstext Werte für die Datensätze eine objectId, die Sie zuordnen möchten.
Bitte beachten: Die Anzahl der Zuordnungen, die ein Datensatz haben kann, hängt vom Objekt und Ihrem HubSpot-Abonnement ab.

​
Datensätze einem Label zuordnen

Um zwei Datensätze zuzuordnen und ein Label zur Beschreibung der Zuordnung festzulegen, führen Sie eine PUT-Anfrage an /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId} durch. Fügen Sie im Anforderungstext die associationCategory und associationTypeId ein, um den Typ der Zuordnung anzugeben, die Sie erstellen möchten. Wenn Sie nicht benannte Zuordnungen erstellen, können Sie die im obigen Abschnitt beschriebenen Standardendpunkte verwenden, für die associationCategory oder associationTypeId nicht erforderlich ist. Wenn Sie Zuordnungen mit einem Label erstellen, können Sie auf diese Liste der Standardtyp-IDs verweisen oder Sie müssen die benutzerdefinierten Zuordnungstypen zwischen diesen Objekten abrufen.
Bitte beachten: Stellen Sie für objektübergreifende und gepaarte Label-Beziehungen sicher, dass Sie die typeId verwenden, die sich auf die richtige Richtung bezieht (z. B. Kontakt zu Unternehmen vs. Unternehmen zu Kontakt, Mitarbeiter zu Manager vs. Manager zu Mitarbeiter).
So ordnen Sie beispielsweise einen Kontakt mithilfe eines benutzerdefinierten Labels einem Deal zu: 1. Führen Sie eine GET-Anfrage an /crm/v4/associations/contact/deal/labels durch. 2. Sehen Sie sich in Ihrer Antwort die Werte typeId und category für das Label an. Die ID ist eine Zahl (z. B. 36), und die Kategorie ist immer USER_DEFINED für benutzerdefinierte Label. 3. Führen Sie eine PUT-Anfrage /crm/v4/objects/contact/{objectId}/associations/deal/{toObjectId}mit dem folgenden Anforderungstext durch: 
/// Example request body
[
  {
    "associationCategory": "USER_DEFINED",
    "associationTypeId": 36
  }
]

​
Zuordnungslimits festlegen und verwalten

Sie können Limits für die Anzahl der zwischen Objekten zugeordneten Datensätze festlegen oder wie oft ein Label zur Beschreibung von Zuordnungen verwendet werden kann. Darüber hinaus gibt es technische Beschränkungen und Limits, die von Ihrem HubSpot-Abonnement abhängen.

​
Zuordnungslimits erstellen oder aktualisieren

Sie können neue Zuordnungslimits zwischen Objekten erstellen oder bestehende aktualisieren.
  • Um Limits zu erstellen, führen Sie eine POST-Anfrage an crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create durch.
  • Um bestehende Limits zu aktualisieren, führen Sie eine POST-Anfrage an crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update durch.
Fügen Sie im Anforderungstext inputs mit Folgendem hinzu:
ParameterBeschreibung
categoryDie Kategorie der Zuordnung, für die Sie ein Limit festlegen, entweder HUBSPOT_DEFINED oder USER_DEFINED.
typeIdDie numerische ID für den Zuordnungstyp, für den Sie ein Limit festlegen möchten. Beziehen Sie sich auf diese Liste der Standard-typeId-Werte oder rufen Sie den Wert für benutzerdefinierte Label ab.
maxToObjectIdsDie maximal zulässige Anzahl von Zuordnungen für den Zuordnungstyp.
Um beispielsweise Limits festzulegen, dass ein Deal mit maximal fünf Kontakten verknüpft werden kann, wobei nur ein Kontakt als Ansprechpartner für einen Deal gekennzeichnet ist, würde Ihre Anfrage wie folgt aussehen: 
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/create
{
  "inputs": [
    {
      "category": "HUBSPOT_DEFINED",
      "typeId": 3,
      "maxToObjectIds": 5
    },
    {
      "category": "USER_DEFINED",
      "typeId": 35,
      "maxToObjectIds": 1
    }
  ]
}

​
Zuordnungslimits abrufen

  • Um alle definierten Zuordnungslimits zu lesen, führen Sie eine GET-Anfrage an/crm/v4/associations/definitions/configurations/all durch. Dadurch werden benutzerdefinierte Zuordnungslimits zurückgegeben, die für alle Objekte definiert sind.
  • Um Zuordnungslimits zwischen zwei bestimmten Objekten zu lesen, führen Sie eine GET-Anfrage an /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType} durch.
Bei beiden Anfragen gibt die Antwort die Werte der Zuordnungen für category, typeId maxToObjectIds und labelzurück. Wenn Sie beispielsweise Limits zwischen Deals und Kontakten abrufen, würde die Antwort wie folgt aussehen: 
//Example response GET crm/v4/associations/definitions/configurations/deal/contact
{
  "results": [
    {
      "category": "HUBSPOT_DEFINED",
      "typeId": 3,
      "userEnforcedMaxToObjectIds": 5,
      "label": null
    }
  ]
}

​
Zuordnungslimits löschen

Um bestimmte Zuordnungslimits zu löschen, führen Sie eine POST-Anfrage an /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge durch. Fügen Sie im Anforderungstext die Werte category und typeId der Zuordnungstypen ein, für die Sie Limits aufheben möchten. Um beispielsweise das Ansprechpartner-Limit für Deals und Kontakte aufzuheben, müsste die Anfrage wie folgt aussehen: 
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/purge
{
  "inputs": [
    {
      "category": "USER_DEFINED",
      "typeId": 35
    }
  ]
}
Wenn Sie erfolgreich sind, erhalten Sie eine 204-Antwort und das enthaltene Limit wird auf den Systemstandard zurückgesetzt (d. h., viele Kontakte können das Label Point ofcontact haben).

​
Zu hoher Zuordnungsnutzung berichterstatten

Es gibt technische Beschränkungen für die Anzahl der Zuordnungen, die ein Datensatz haben kann. Sie können die Zuordnungen-API verwenden, um einen Bericht mit Datensätzen abzurufen, die sich dem Höchstlimit für Zuordnungen nähern oder dieses erreicht haben. Um den Bericht abzurufen, führen Sie eine POST-Anfrage an crm/v4/associations/usage/high-usage-report/{userID} durch. Die Datei enthält Datensätze, die 80 % oder mehr ihres Zuordnungslimits nutzen. Wenn ein Unternehmen beispielsweise bis zu 50.000 Kontakten zugeordnet werden kann, wird das Unternehmen in der Datei aufgenommen, wenn es über 40.000 oder mehr zugeordnete Kontakte verfügt. Die Datei wird an die E-Mail-Adresse des Benutzers gesendet, dessen ID in der Anfrage-URL enthalten war. Erfahren Sie, wie Sie Benutzer-IDs mit der Benutzer-API abrufen.

​
ID-Werte des Zuordnungstyps

Die folgenden Tabellen enthalten die von HubSpot definierten associationTypeId-Werte, die den Typ der Zuordnung angeben. Die Zuordnungstypen variieren je nach den enthaltenen Objekten und der Richtung der Zuordnung (z. B. ist Kontakt zu Unternehmen anders als Unternehmen zu Kontakt). Wenn Sie benutzerdefinierte Objekte oder benutzerdefinierte Zuordnungslabel erstellen, haben die zugehörigen Zuordnungstypen „Eindeutige typeId“-Werte, die Sie in Ihren Zuordnungseinstellungen in HubSpot abrufen oder suchen müssen.
Bitte beachten: Zu den Standardzuordnungstypen für Unternehmen gehören ein Zuordnungstyp ohne Label und ein primärer Zuordnungstyp. Wenn ein Datensatz mehr als ein zugeordnetes Unternehmen hat, kann nur eines das primäre Unternehmen sein. Die anderen Zuordnungen können entweder kein Label enthalten oder über benutzerdefinierte Zuordnungslabel verfügen.

​
v1 Zuordnungen (alt)

Wenn Sie die v1-Zuordnungen-API verwenden, finden Sie in der folgenden Tabelle Informationen zu den IDs, die beim Zuordnen von Datensätzen zu verwenden sind.
ZuordnungstypID
Kontakt zu Unternehmen1
Unternehmen zu Kontakt (Standard)2
Unternehmen zu Kontakt (alle Label)280
Deal zu Kontakt3
Kontakt zu Deal4
Deal zu Unternehmen5
Unternehmen zu Deal6
Unternehmen zu Interaktion7
Interaktion zu Unternehmen8
Kontakt zu Interaktion9
Interaktion zu Kontakt10
Deal zu Interaktion11
Interaktion zu Deal12
Übergeordnetes Unternehmen zu untergeordnetem Unternehmen13
Untergeordnetes Unternehmen zu übergeordnetem Unternehmen14
Kontakt zu Ticket15
Ticket zu Kontakt16
Ticket zu Interaktion17
Interaktion zu Ticket18
Deal zu Artikel19
Artikel zu Deal20
Unternehmen zu Ticket25
Ticket zun Unternehmen26
Deal zu Ticket27
Ticket zu Deal28