Letzte Änderung: 11. September 2025
Nachdem Sie ein Event-Typschema definiert und dessen fullyQualifiedNameabgerufen haben, können Sie Daten zum Auftreten von Events über die App-Events-API senden. Beim Senden von Event-Daten müssen Sie sich an das zuvor erstellte Schema halten. Anfragen, die nicht mit dem Schema übereinstimmen, schlagen bei der Validierung fehl und werden nicht von der App erfasst.

​
Senden von Event-Occurrences

Um ein einzelnes Event-Vorkommnis zu senden, stellen Sie eine POST-Anfrage an /integrators/timeline/v4/events.Fügen Sie im Anfragetext Ereignisdaten hinzu, die dem definierten Schema des Event-Typs folgen, zusammen mit dem fullyQualifiedName-Wert in einem eventTypeName-Feld.
{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

Mit * markierte Felder sind Pflichtfelder.

FeldTypBeschreibung
eventTypeName*ZeichenfolgeDer vollständig qualifizierte Name des Event-Typs, den Sie verwenden, um das Event über die API zu identifizieren. Dieser Wert wird von HubSpot automatisch festgelegt und lässt sich nach der Erstellung des Event-Typs über die API abrufen. Dieser Wert kann nach der Erstellung nicht mehr geändert werden.
objectId*ZeichenfolgeDie ID des CRM-Datensatzes, der dem Auftreten des Events zugeordnet werden soll. Dieses Feld kann für alle Arten von CRM-Datensätzen verwendet werden und ist die empfohlene ID. Erfahren Sie mehr über CRM Datensatzzuordnung.
emailZeichenfolgeFür die Kontakt-Zuordnung können Sie die E-Mail-Adresse des zuzuordnenden Kontakts angeben. Erfahren Sie mehr über CRM-Datensatzzuordnung.
utkZeichenfolgeFür die Kontaktzuordnung können Sie das Benutzer-Token eines vorhandenen Kontakts angeben, der zugeordnet werden soll. Erfahren Sie mehr über CRM-Datensatzzuordnung.
domainZeichenfolgeFügen Sie dieses Feld zusätzlich zu objectId hinzu, um den domain-Eigenschaftswert des Unternehmens festzulegen. Erfahren Sie mehr über CRM-Datensatzzuordnung.
timestampZeichenfolgeLegt den Zeitpunkt des Auftretens des Events fest (ISO 8601-Format). Wenn nichts angegeben wird, verwendet HubSpot standardmäßig den Zeitstempel, an dem die Daten des Event-Vorkommnisses gesendet werden.
propertiesObjektSchlüsselwert-Paare von Eigenschaftsnamen und Eigenschaftswerte, die Sie für den Event-Typ konfiguriert haben. Erfahren Sie mehr über Event-Eigenschaften.
extraDataObjektZusätzliche Informationen, die für Chronik-Rendering-Vorlagen verfügbar sind. Muss im gültigen JSON-Format vorliegen.
timelineIFrameObjektWenn dies verwendet wird, enthält die Chronik-Karte einen Hyperlink, der es Benutzern ermöglicht, die verlinkten Inhalte in einem iframe zu öffnen. Erfahren Sie mehr über die Verwendung von iframes.
idZeichenfolgeEine eindeutige ID für das jeweilige Event-Vorkommnis. Muss innerhalb des Event-Typs eindeutig sein. Falls nicht anders angegeben, generiert HubSpot eine zufällige UUID. Wenn mehrere Events die gleiche ID haben, wird die erste akzeptiert und alle anderen abgelehnt.

​
Zuordnung von Datensätzen

Jedes Auftreten eines Events muss einem CRM-Datensatz zugeordnet werden, wobei der CRM-Objekttyp durch das Event-Typschema definiert ist. Die App-Events-API enthält mehrere Felder, mit denen sich Daten von Event-Vorkommnissen CRM-Datensätzen zuordnen lassen. Für alle unterstützten CRM-Objekte wird empfohlen, das objectId-Feld zu verwenden. Es gibt jedoch einige Situationen, in denen Sie vielleicht andere Felder bevorzugen.
  • utk/email: Wenn Sie die ID des Kontakts nicht kennen, verwenden Sie das utk-Feld und/oder email-Feld zur Identifizierung. Die Angabe dieser beiden IDs ermöglicht es Ihnen auch, Kontakte zu erstellen und zu aktualisieren. Zum Beispiel:
    • Wenn utk mit einem vorhandenen Kontakt übereinstimmt, jedoch email nicht, aktualisiert HubSpot den Kontakt (gemäß utk) mit der neuen E-Mail-Adresse.
    • Ist kein objectId angegeben, wird das Auftreten des Events einem vorhandenen Kontakt zugeordnet, der mit utk/email übereinstimmt, oder HubSpot erstellt einen neuen Kontakt, wenn keine Übereinstimmung vorliegt.
    • Beachten Sie bitte, dass anhand von utk allein kein neuer Kontakt erstellt werden kann. Sie sollten immer email zusammen mit utk erwähnen, um eine ordnungsgemäße Zuordnung zu gewährleisten.
  • domain: Für Unternehmenszuordnungen müssen Sie das objectId angeben, können aber auch domain einschließen, um die domain-Eigenschaft dieses Unternehmens zu aktualisieren.
Nachfolgend finden Sie die Prioritätenfolge für die Eigenschaftszuordnung von CRM-Datensätzen, wobei die kleinste Zahl die höchste Priorität darstellt:
Beschreibung der Feldpriorität
objectId1Die CRM-Datensatz-ID (empfohlen)
utk2Das Kontaktbenutzertoken (nur Kontakte)
email3Die E-Mail-Adresse des Kontakts (nur Kontakte)
domain4Die Unternehmen Domain (nur Unternehmen)

​
Zusätzliche Daten senden

Neben dem Senden von Daten an Event-Eigenschaften und dem Aktualisieren von CRM-Eigenschaften über das Auftreten von Events können Sie zusätzliche Daten für das Chronik-Rendering per extraData-Objekt einbeziehen.
Das extraData-Objekt darf nur gültige JSON-Dateien enthalten. Wenn diese falsch formatiert sind, wird das Event-Vorkommnis abgelehnt und Sie erhalten eine Fehlerantwort.
Auf extraData-Feldwerte kann über die detailTemplate des Eventtyps unter Verwendung der {{extraData.fieldName}}-Syntax zugegriffen werden. Alle Attributebenen von extraData sind durch Punktnotation verfügbar, z. B {{extraData.person1.preferredName}}. Die folgenden Vorlagen verwenden beispielsweise die customerName- und loginLocation-Eigenschaftsdaten zusammen mit dem surveyData-Feld von extraData, was über das Event-Vorkommnis gesendet wurde. Screenshot, der zeigt, wie das folgende Beispiel einer Rendering-Vorlage auf der Kontaktchronik erscheint. 
{
  "eventTemplateId": "5488733",
  "objectId": "769851",
  "tokens": {
    "customerName": "Tim",
    "loginLocation": "mobileApp",
  },
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer": "Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer": "Extremely likely"
      }
    ]
  }
}