Marketing Events

Access and test APIs in beta. 

Please note: This API is currently under development and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer Developer Beta Terms of Use. You also acknowledge and understand the risk associated with testing an unstable API. 
 

This API is currently in beta. 

Create your app definition on HubSpot

In order for your integration to connect to a HubSpot user's account, you must create an app definition on HubSpot for it. Here, you enter 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, and it also defines what permissions (scopes) your integration needs in the user's HubSpot account.

There is an overview on how to use the HubSpot developer tools, but the steps to get up and running are:

  1. Get a developer account
  2. Create an application definition on your developer account
  3. When creating your application definition, include the appropriate marketing event scopes:
    • crm.objects.marketing_events.read If you intend to read marketing event information
    • crm.objects.marketing_events.write If you intend to create, delete, or make changes to marketing event information

Authentication

There are 2 ways to authenticate API requests made to HubSpot:

  1. API Key. Your developer API key is used when managing settings related to your HubSpot apps through the API (the /settings endpoints for the marketing events extension)
  2. OAuth token. You need to use an oauth token for any request made on behalf of a HubSpot user (the /events endpoints for the marketing events extension). Note that you must ask for the crm.objects.marketing_events.read and/or crm.objects.marketing_events.write scopes when requesting an oauth token for use with the marketing events extension.

Read the Authentication documentation for more information.

CRUD Endpoints

There following API endpoints are available:

  • POST /marketing/v3/marketing-events-beta/events - Creates a new Marketing Event.
  • GET /marketing/v3/marketing-events-beta/events/{externalEventId} - Returns the details of the Marketing Event with the specified id, if one exists.
  • PATCH /marketing/v3/marketing-events-beta/events/{externalEventId} - Updates an existing Marketing Event with the specified id, if one exists.
  • PUT /marketing/v3/marketing-events-beta/events/{externalEventId} - Upsets a Marketing Event. If there is an existing Marketing event with the specified id, it will be updated; otherwise a new event will be created.
  • DELETE /marketing/v3/marketing-events-beta/events/{externalEventId} - Deletes an existing Marketing Event with the specified id, if one exists.

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-beta/events/{externalEventId}/{subscriberState}/upsert - You can record a subscription between a set of HubSpot contacts (identified by their HubSpot contact id) and the Marketing Event with the specified id.
  • POST /marketing/v3/marketing-events-beta/events/{externalEventId}/{subscriberState}/email-upsert - You can record a subscription between a set of HubSpot contacts (identified by their 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.

Important Note: These APIs are idempotent so long as the vid of the contact in the event has not changed. What this means is you can safely call registered, attended and cancelled more than once for the same contact vid and we wont record a duplicate event for them in the Marketing Event properties.

Configure Settings

Explanation of Settings

There is a small amount of setup required to enable Marketing Events correctly for your App.

If you send us a subscriber state change (e.g a register or cancelled event) we first check to see if a Marketing Event exists in HubSpot for the specified event id. If it doesn't, we 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, we still recommend 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 we require each app that uses Marketing Events to define an API where we can 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 we know where to make requests to when we need 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 we 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, will will make the following call:

GET 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"