Marketing-API | Marketingevents

​

In diesem Artikel

• Anforderungen an den Bereich
• Unterschiede zwischen internen ID- und externen ID-Endpunkten
• Endpunkte für das Event-Management
• Event-Teilnahme-Endpunkte
• Teilnehmerstatus-Endpunkte
• Endpunkte für die Listenzuordnung
• App-Einstellungen konfigurieren
  • Schritt 1: Eine API in Ihrer App erstellen
  • Schritt 2: HubSpot den URL-Pfad zu Ihrer API bereitstellen

​

Anforderungen an den Bereich

• crm.objects.marketing_events.read: erteilt die Berechtigung zum Abrufen von Marketingevent- und -Teilnahmedaten.
• crm.objects.marketing_events.write: erteilt die Berechtigung, Marketingevent-Informationen zu erstellen, löschen oder ändern.

​

Unterschiede zwischen internen ID- und externen ID-Endpunkten

• Endpunkte mit externen IDs: Endpunkte, die externalEventId- und externalAccountId-Parameter erfordern, funktionieren nur in derselben App, die das Event ursprünglich erstellt hat. Wenn Sie z. B. zwei öffentliche Apps mit den Namen App A und App B erstellt haben und ein Marketingevent über die Authentifizierung und IDs erstellt haben, die App A zugeordnet sind, kann nur App A das Event lesen, aktualisieren oder neue Teilnehmer hinzufügen. Wenn Sie versuchen, mit App B auf dasselbe Event zuzugreifen, das dieselbe externalEventId und externalAccountId verwendet, tritt ein 404-Fehler auf.
• Endpunkte, die eine objectId verwenden: Endpunkte, die eine objectId erfordern, können für den Zugriff auf ein Event von jeder App mit den im Abschnitt oben aufgeführten zugeordneten Bereichen verwendet werden, unabhängig von der App, die das Event ursprünglich erstellt hat. Wenn App A ein Marketingevent erstellt hat, kann App B weiterhin Teilnehmer über objectId-basierte Endpunkte lesen, aktualisieren oder hinzufügen.

​

Endpunkte für das Event-Management

​

Event-Eigenschaften

​

Ein Event erstellen

{
  "externalAccountId": "12345",
  "externalEventId": "67890",
  "eventName": "Winter webinar",
  "eventOrganizer": "Snowman Fellowship",
  "eventCancelled": false,
  "eventUrl": "https://example.com/holiday-jam",
  "eventDescription": "Let's get together to plan for the holidays",
  "eventCompleted": false,
  "startDateTime": "2024-08-07T12:36:59.286Z",
  "endDateTime": "2024-08-07T12:36:59.286Z",
  "customProperties": [
    {
      "name": "eventSeason",
      "value": "winter"
    }
  ]
}

​

Event-Eigenschaften mithilfe externer IDs aktualisieren

{
  "inputs": [
    {
      "customProperties": [
        {
          "name": "property1",
          "value": "1234"
        }
      ],
      "eventName": "Virtual cooking class",
      "startDateTime": "2023-11-30T17:46:20.461Z",
      "eventOrganizer": "Chef Joe",
      "eventDescription": "Join us for a virtual cooking class! Yum."
      "eventCancelled": false,
      "externalAccountId": "CookingCo",
      "externalEventId": "4"
    }
  ]
}

​

Event-Eigenschaften mithilfe seiner objectId aktualisieren

• Um die objectId für ein bestimmtes Marketingevent abzurufen, folgen Sie den Anweisungen in diesem Wissensdatenbank-Artikel, um die Details für ein Event in Ihrem HubSpot-Account anzuzeigen, und suchen Sie dann die ID unter dem Feld Datensatz-ID. Die objectId wird auch in der Antwort zurückgegeben, wenn Sie ein Event erfolgreich erstellt haben.
• Sie können auch eine GET-Anfrage an den im nächsten Abschnitt beschriebenen /marketing/v3/marketing-events-Endpunkt vornehmen.
• Wenn Sie die externalEventId für ein Event kennen, können Sie sie als Pfad in eine GET-Anfrage an /marketing/v3/marketing-events/{externalEventId}/identifiers einschließen. Die Antwort enthält alle Marketingevents zusammen mit den relevanten IDs für jedes Event (d. h. objectId, appInfo und marketingEventName sowie die externalAccountId des Events).

​

Event-Informationen abrufen

{
  "eventName": "Test Marketing Event",
  "eventType": "test-type",
  "startDateTime": "2024-05-22T12:29:50.734Z",
  "endDateTime": "2024-05-25T12:29:50.734Z",
  "eventOrganizer": "testEventOrganizer",
  "eventDescription": "testDescription",
  "eventUrl": "testURL",
  "eventCancelled": true,
  "eventCompleted": false,
  "customProperties": [
    {
      "name": "test_custom_prop",
      "value": "1"
    },
    {
      "name": "test_prop",
      "value": "2"
    }
  ],
  "objectId": "58237132332",
  "externalEventId": null,
  "eventStatus": "CANCELLED",
  "appInfo": {
    "id": "111",
    "name": "Zoom"
  },
  "registrants": 1,
  "attendees": 1,
  "cancellations": 2,
  "noShows": 0,
  "createdAt": "2024-08-07T12:58:40.635Z",
  "updatedAt": "2024-10-15T13:35:03.353Z"
}

​

Ein Event löschen

​

Mehrere Events gleichzeitig aktualisieren

{
  "inputs": [
    {
      "objectId": "58237132332",
      "eventCancelled": true,
      "eventOrganizer": "testEventOrganizer",
      "eventUrl": "testURL",
      "eventDescription": "testDescription",
      "eventName": "Test Marketing Event Update",
      "eventType": "test-type"
    },
    {
      "objectId": "54073507364",
      "eventCancelled": true,
      "eventOrganizer": "testEventOrganizer",
      "eventUrl": "testURL",
      "eventDescription": "testDescription",
      "eventName": "Test Marketing Event Update 2",
      "eventType": "test-type"
    }
  ]
}

​

Event-Teilnahme-Endpunkte

​

Teilnahme mithilfe der Event-objectId aktualisieren

• Um die ID eines Kontakts zu verwenden, führen Sie eine POST-Anfrage an /marketing/v3/marketing-events/{objectId}/attendance/{subscribeState}/create durch und geben die Kontakt-ID über das vid-Feld im inputs-Array Ihres Anforderungstextes an. Der folgende Anforderungstext enthält ein Beispiel für die Aktualisierung der Teilnahmedaten für einen Kontakt mit der ID 47733471576 mit der Angabe, wann der Teilnehmer über die joinedAt- und leftAt-Eigenschaften dem Event beigetreten ist und es verlassen hat:

{
  "inputs": [
    {
      "vid": 47733471576,
      "properties": {
        "joinedAt": "2024-05-22T13:38:16.500Z",
        "leftAt": "2024-05-22T15:40:16.500Z"
      },
      "interactionDateTime": 1716382579000
    }
  ]
}

• Um die E-Mail-Adresse eines Kontakts zu verwenden, führen Sie eine POST-Anfrage an /marketing/v3/marketing-events/{objectId}/attendance/{subscribeState}/email-create durch und geben dann die E-Mail-Adresse des Kontakts über das email-Feld im inputs-Array Ihres Anforderungstextes an.
  • Wenn Sie einen neuen Kontakt erstellen, können Sie das contactProperties-Feld in das inputs-Array Ihres Anforderungstextes aufnehmen, um alle zugehörigen Eigenschaften für den neu erstellten Kontakt festzulegen. Falls der Kontakt bereits vorhanden ist, werden die in der Anfrage angegebenen contactProperties sonst nicht aktualisiert.
  • Der folgende Anforderungstext enthält ein Beispiel für die Aktualisierung der Teilnahmedaten für einen Kontakt mit der E-Mail-Adresse john@example.com mit der Angabe im properties-Object Ihres inputs-Arrays, wann der Teilnehmer über die joinedAt- und leftAt-Eigenschaften dem Event beigetreten ist und es verlassen hat:

{
  "inputs": [
    {
      "contactProperties": {
        "additionalProp1": "string",
        "additionalProp2": "string"
      },
      "properties": {
        "joinedAt": "2024-05-22T13:38:16.500Z",
        "leftAt": "2024-05-22T15:40:16.500Z"
      },
      "email": "john@example.com",
      "interactionDateTime": 1716382579000
    }
  ]
}

• objectId: die Datensatz-ID des Marketingevents in Ihrem HubSpot-Account Weitere Informationen zur Verwendung der objectId eines Events statt seiner externen IDs finden Sie im obigen Abschnitt.
• subscriberState: eine Aufzählung, die dem neuen Teilnehmerstatus des Kontakts entspricht:
• REGISTERED: gibt an, dass sich der HubSpot-Kontakt für das Event registriert hat.
• ATTENDED: gibt an, dass der HubSpot-Kontakt am Event teilgenommen hat. Wenn Sie den Status eines Kontakts auf ATTENDED aktualisieren, können Sie auch die Zeitstempel joinedAt und leftAt als Parameter in den Anfragetext einfügen, der im ISO8601 Instant-Format angegeben ist.
• CANCELLED: gibt an, dass der HubSpot-Kontakt, der sich zuvor für das Event registriert hatte, seine Registrierung storniert hat.

​

Teilnahme mithilfe der externen Event-IDs aktualisieren

• Wenn Sie die Kontakt-IDs von bestehenden Kontakten verwenden möchten:
  • Führen Sie eine POST-Anfrage an /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/create durch, indem Sie die ID des Events aus Ihrer externen Anwendung als externalEventId verwenden.
  • Geben Sie im Anforderungstext ein inputs-Objekt an, das die folgenden Felder enthält:
    • interactionDateTime: der Zeitpunkt (Datum und Uhrzeit), zu dem sich der Kontakt zum Event angemeldet hat.
    • vid: die Kontakt-ID eines vorhandenen Kontakts.
• Wenn Sie die E-Mail-Adresse eines der Teilnehmer der Veranstaltung verwenden möchten:
  • Führen Sie eine POST-Anfrage an /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/email-create durch.
  • Geben Sie im Anforderungstext ein inputs-Objekt an, das die folgenden Felder enthält:
    • interactionDateTime: der Zeitpunkt (Datum und Uhrzeit), zu dem sich der Kontakt zum Event angemeldet hat.
    • email: die E-Mail-Adresse des Teilnehmers als Wert des E-Mail-Felds in einer Eingabe.
  • Stimmt die von Ihnen angegebene E-Mail-Adresse nicht mit der Adresse eines vorhandenen Kontakts überein, wird ein neuer Kontakt erstellt.

• externalEventId: die ID des Marketingevents Weitere Informationen zur Verwendung der objectId eines Events statt seiner externen IDs finden Sie im obigen Abschnitt.
• subscriberState: eine Aufzählung, die dem neuen Teilnehmerstatus des Kontakts entspricht:
  • REGISTERED: gibt an, dass sich der HubSpot-Kontakt für das Event registriert hat.
  • ATTENDED: gibt an, dass der HubSpot-Kontakt am Event teilgenommen hat. Wenn Sie den Status eines Kontakts auf ATTENDED aktualisieren, können Sie auch die Zeitstempel joinedAt und leftAt als Parameter in den Anfragetext einfügen, der im ISO8601 Instant-Format angegeben ist.
  • CANCELLED: gibt an, dass der HubSpot-Kontakt, der sich zuvor für das Event registriert hatte, seine Registrierung storniert hat.

​

Teilnehmerstatus-Endpunkte

​

Teilnahmen für einen bestimmten Kontakt lesen

{
  "results": [
    {
      "associations": {
        "marketingEvent": {
          "externalAccountId": "4",
          "marketingEventId": "123",
          "externalEventId": "456",
          "name": "Virtual baking workshop"
        },
        "contact": {
          "firstname": "Jane",
          "contactId": "156792341",
          "email": "jdoe@example.com",
          "lastname": "Doe"
        }
      },
      "createdAt": "2024-05-21T18:35:04.838Z",
      "id": "string",
      "properties": {
        "occurredAt": "2024-05-22T10:35:04.838Z",
        "attendancePercentage": "string",
        "attendanceState": "REGISTERED",
        "attendanceDurationSeconds": 3600
      }
    }
  ]
}

​

Aufschlüsselung der Teilnahmedaten lesen

​

Teilnahmezählungen lesen

{
  "attended": 152,
  "registered": 200,
  "cancelled": 3,
  "noShows": 8
}

​

Filtern der Aufschlüsselung von Teilnahmedaten

​

Endpunkte für die Listenzuordnung

• Navigieren Sie in Ihrem HubSpot Account zu CRM > Listen.
• Klicken Sie auf den Namen einer Liste.
• Klicken Sie oben rechts auf Details.
• Im rechten Bereich wird die Listen-ID unter Listen-IDs für API-Integrationen angezeigt. Sie können auf Listen-ID kopieren klicken, um die ID in die Zwischenablage zu kopieren.

• Gehen Sie in Ihrem HubSpot-Account zu CRM > Kontakte.
• Klicken Sie oben links auf Kontakte und wählen Sie im Dropdown-Menü die Option Marketingevents aus.
• Klicken Sie auf den Namen eines Marketingevents.
• Klicken Sie auf der Registerkarte Performance auf Listen, um den Abschnitt zu erweitern, und klicken Sie dann auf die Registerkarte Über Zuordnungen hinzugefügte Listen.

​

Listenzuordnung mit einer Marketingevent-ID erstellen

​

Listenzuordnung mit externen Event- und Account-IDs erstellen

​

Abrufen von Listen, die einem Marketingevent mithilfe einer Marketingevent-ID zugeordnet sind

{
  "total": 1,
  "results": [
    {
      "listId": "string",
      "listVersion": 0,
      "createdAt": "2024-05-10T08:58:35.769Z",
      "updatedAt": "2024-05-10T08:58:35.769Z",
      "filtersUpdatedAt": "2024-05-10T08:58:35.769Z",
      "processingStatus": "string",
      "createdById": "string",
      "updatedById": "string",
      "processingType": "string",
      "objectTypeId": "string",
      "name": "string",
      "size": 0
    }
  ]
}

​

Abrufen von Listen, die einem Event mithilfe externer Event- und Account-IDs zugeordnet sind

​

Listenzuordnung mithilfe einer Marketingevent-ID löschen

​

Listenzuordnung mithilfe externer Event- und Account-IDs löschen

​

App-Einstellungen konfigurieren

​

Schritt 1: Eine API in Ihrer App erstellen

• Akzeptiert:
  • externalAccountId: ein Abfrageparameter, der die accountId des Kunden in der externen App angibt.
  • appId: ein Abfrageparameter, der die ID der HubSpot-Anwendung angibt, die die Event-Details anfordert. Dies ist dann die ID Ihrer App.
  • externalEventId: ein Pfadparameter in der URL der Anfrage, der die ID des Events in der externen App angibt, zu dem HubSpot Details benötigt.
• Gibt zurück:
  • Ein JSON-Objekt, das Details für das Marketingevent bereitstellt und die folgenden Felder enthält, die in der folgenden Tabelle aufgeführt sind:

​

Schritt 2: HubSpot den URL-Pfad zu Ihrer API bereitstellen

• Sie enthält eine %s-Zeichensequenz enthalten, die HubSpot zum Ersetzen in der ID des Events (externalEventId) als Pfadparameter verwendet.
• Es muss der vollständige Pfad zur API-Ressource sein, einschließlich des Präfixes https:// und des Domain-Namens (z. B. my.event.app).