Marketing Events

Marketing events is a CRM object, similar to contacts and companies, that enables you to track and associate marketing events, such as a webinar, to other HubSpot CRM objects. Below, learn more about working with the marketing event API to integrate marketing events into an app.

Create your app definition on HubSpot

To enable your integration to connect to a HubSpot user's account, you must create an app definition in HubSpot for it. App definitions include details such as the logo and text to be shown to the HubSpot user when your integration attempts to make an initial connection to their account, as well as the permissions (scopes) your integration needs in the user's HubSpot account.

To get started creating your app:

When authenticating calls made by your app, you can either use a private app access token or OAuth. Learn more about authentication methods. For the full list of endpoints available, click the Endpoints tab at the top of this article.

Subscriber state endpoints

The subscriber state endpoints allow you to record a subscription state between a HubSpot contact and a marketing event. For example, you can use this endpoint to record that a HubSpot contact has registered for a marketing event.

There are 2 subscription endpoints:

  • POST /marketing/v3/marketing-events/events/{externalEventId}/{subscriberState}/upsert:  records a subscription between a set of HubSpot contacts (identified by contact ID) and the Marketing Event with the specified ID.
  • POST /marketing/v3/marketing-events/events/{externalEventId}/{subscriberState}/email-upsert:  records a subscription between a set of HubSpot contacts (identified by email address) and the Marketing Event with the specified ID.

There are 3 accepted values for {subscriberState}:

  • register:  indicates that the HubSpot contact has registered for the event.
  • attend: indicates that the HubSpot contact has attended the event.
  • cancel: indicates that the HubSpot contact, who had previously registered for the event, has now cancelled their registration for the event.

Please note: these APIs are idempotent so long as the ID of the contact and the interactionDateTime value in the event has not changed. This enables you to safely set subscriber state multiple times without HubSpot creating duplicate events in the marketing events properties.

Configure settings

There's some setup required to enable Marketing Events correctly for your app.

If you send HubSpot a subscriber state change (e.g a register or cancelled event), HubSpot will first check to see if a Marketing Event exists for the specified event ID. If it doesn't, HubSpot will call the configured endpoint for your app to retrieve the details of the marketing event, then create the event in HubSpot and then publish the subscriber state change.

This is provided for convenience; however, it's still recommended that you create the Marketing Events yourself via our CRUD methods and don't rely on this functionality to create your Marketing Events in HubSpot.

Step 1: Create an API in your app

In order to support this, HubSpot requires each app that uses Marketing Events to define an API to fetch information about a specific marketing event.

Requirements:

  • Accepts:
    • externalAccountId (QueryParam): the accountId of the customer in the external app.
    • appId (QueryParam): the id of the HubSpot application that is requesting the event details. This will be the id of your app.
    • externalEventId (PathParam): the id of the event in the external app that we want details about.
  • Returns:
    • Marketing Event details

Step 2: Configure the API in MarketingEventExtension

Now that you've created the API in your app that will return a MarketingEventDetails object, you will need to configure the URL paths to this API in MarketingEventExtension, so HubSpot knows where to make requests to get the Event Details.

NOTE: Your configured path must:

  • At least contain a %s character sequence, which we use to substitute in the id of the event (externalEventId) as a path parameter
  • Be the full path to the API resource.

For example, if you configure an eventDetailsURL of https://my.event.app/events/%s, and you need to make a request to fetch details of an event with id 1234-event-XYZ, for the HubSpot app with id app-101 and account with id ABC-account-789, HubSpot will make a GET request to:

https://my.event.app/events/1234-event-XYZ?appId=app-101&externalAccountId=ABC-account-789

You should return a JSON response with the following fields:

Field Name Required Type Field Description
eventName true string The name of the marketing event
eventOrganizer true string The name of the organizer of the marketing event.
eventType false string Describes what type of event this is. For example: WEBINAR, CONFERENCE, WORKSHOP
startDateTime false string($date-time) The start date and time of the marketing event.
endDateTime false string($date-time) The end date and time of the marketing event.
eventDescription false string The description of the marketing event.
eventUrl false string A URL in the external event application where the marketing event.
eventCancelled false bool Indicates if the marketing event has been cancelled. Defaults to false"

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.