A marketing event is a CRM object, similar to contacts and companies, that enables you to track marketing events, such as a webinar, along with the contacts who registered and attended the event. Below, learn more about working with the marketing event API to integrate marketing events into an app.
- Scope requirements
- Differences between internal ID and external ID endpoints
- Event management endpoints
- Event attendance endpoints
- Participant state endpoints
- List association endpoints
- Configure app settings
To make an API request to one of the marketing event endpoints, the following scopes are required:
crm.objects.marketing_events.read
: grants permission to retrieve marketing event and attendance data.crm.objects.marketing_events.write
: grants permission to create, delete, or make changes to marketing event information.
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, check out the reference documentation.
Many endpoints below provide two different ways to identify an event you want to fetch or update. Though the end result for similar endpoints might be the same, they differ mainly in the associated IDs you provide:
- Endpoints using external IDs: endpoints that require
externalEventId
andexternalAccountId
parameters will only work in the same app that originally created the event. For example, if you created two public apps, called App A and App B, and you created a marketing event via the authentication and IDs associated with App A, only App A can read, update, or add new participants to the event. If you attempt to access the same event with App B using the same externalEventId and externalAccountId, a 404 error will result. - Endpoints using an objectId: endpoints that require an
objectId
can be used to access an event by any app with the associated scopes listed in the section above, regardless of the app that originally created the event. If App A created a marketing event, App B can still read, update, or add participants throughobjectId
-based endpoints.
The following sections provide context on common event properties, and detail how to use the various event management endpoints to create, read, update, and archive events.
The following properties are available to fetch and update when using the event management endpoints:
Parameter | Type | Description |
---|---|---|
eventName | String | The title of your event. |
eventType | String | The type of the event (e.g., webinar, tradeshow, etc.). |
eventOrganizer | String | The individual or organization that's hosting the event. |
eventDescription | String | A description for your event. |
eventUrl | String | A URL that users can navigate to where they can learn more details and/or register for your event. |
eventCancelled | Boolean | Whether or not the event is cancelled. |
eventStartTime | String | An ISO 8601 formatted timestamp of the event's start time. |
eventEndTime | String | An ISO 8601 formatted timestamp of the event's end time. |
To create a marketing event you can make a POST
request to /marketing/v3/marketing-events/events
and provide the eventName
, externalEventId
, externalAccountId
, and eventOrganizer
in the body of your request. You can optionally provide any additional properties listed in the table above in your request.
For example, if the externalAccountId
of your app is "12345"
, and the externalEventId
of your event in your app is "67890"
, you could create a new event called "Winter webinar"
with a request that would resemble the following:
{
"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"
}
]
}
You can update marketing events by making a POST
request to /marketing/v3/marketing-events/events/upsert
endpoint. You can include any customProperties
along with any other details of your event (including its name, start time, and description).
If a marketing event already exists with the specified ID in your request, it will be updated. Otherwise, a new event will be created.
For example, the following request would create an event with an ID of 4
named "Virtual cooking class":
xxxxxxxxxx
{
"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"
}
]
}
Once an event is created, you can update its properties by making a PATCH
request to /marketing/v3/marketing-events/{objectId}
.
- To get the
objectId
for a specific marketing event, follow the instructions in this knowledge base article to view the details for an event in your HubSpot account, then locate the ID under the Record ID field. TheobjectId
will also be returned in the response when you successfully create an event. - You can also make a
GET
request to the/marketing/v3/marketing-events
endpoint described in the next section. - If you have the
externalEventId
of an event, you can include it as a path when making aGET
request to/marketing/v3/marketing-events/{externalEventId}/identifiers
. The response will include all marketing events along with the relevant identifiers for each event (i.e., the event'sobjectId
, itsappInfo
, themarketingEventName
, and theexternalAccountId
).
To get a list of all marketing events along with their properties, make a GET
request to /marketing/v3/marketing-events
.
If you need to retrieve the details for a specific marketing event by its Record ID in HubSpot, you can provide the ID as the objectId in a GET
request to /marketing/v3/marketing-events/{objectId}
.
xxxxxxxxxx
{
"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"
}
To delete a marketing event, make a DELETE
request to /marketing/v3/marketing-events/{objectId}
with the event's associated objectId
.
If successful, you'll receive a 204 No Content
response.
To update multiple marketing events in bulk, you can make a POST
request to /marketing-events/v3/marketing-events/batch/update
and provide the properties you want to update for each event within the inputs array of the request body.
For example, if you wanted to update several properties of two marketing events with object IDs of 58237132332 and 54073507364 in a single request, the body of your request would resemble the following:
xxxxxxxxxx
{
"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"
}
]
}
The event attendance state endpoints allow you to record registration activities for a contact, such as whether they registered, attended, or cancelled their registration for your event. For example, you can use this endpoint to record that a HubSpot contact has registered for a marketing event.
If you want to use the objectId
of a marketing event, you can either use the contact ID of the contact you want to record participation state for, or you can use their email address.
- To use a contact's ID, make a POST request to
/marketing/v3/marketing-events/{objectId}/attendance/{subscribeState}/create
then provide the ID of the contact using thevid
field within theinputs
array of your request body. For example, the request body below provides an example of updating the attendance data for a contact with an ID of47733471576
and specifying when the attendee joined and left the event via thejoinedAt
andleftAt
properties:
xxxxxxxxxx
{
"inputs": [
{
"vid": 47733471576,
"properties": {
"joinedAt": "2024-05-22T13:38:16.500Z",
"leftAt": "2024-05-22T15:40:16.500Z"
},
"interactionDateTime": 1716382579000
}
]
}
- To use a contact's email, make a POST request to
/marketing/v3/marketing-events/{objectId}/attendance/{subscribeState}/email-create
then provide the email of the contact using theemail
field within theinputs
array of your request body.- If you're creating a new contact, you can include the
contactProperties
field within theinputs
array of your request body to set any associated properties on the newly created contact. Otherwise, if the contact already exists,contactProperties
provided in the request will not be updated. - For example, the request body below provides an example of updating the attendance data for a contact with an email address of
john@example.com
and specifying when the attendee joined and left the event via thejoinedAt
andleftAt
fields within theproperties
object of yourinputs
array:
- If you're creating a new contact, you can include the
xxxxxxxxxx
{
"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
}
]
}
For either of the approaches above, provide the following values for the corresponding path parameters:
objectId
: the Record ID of the marketing event in your HubSpot account. Check out the section above for more details on using the objectId of an event versus using its external IDs.subscriberState
: an enumeration that matches the new attendance status of the contact:REGISTERED
: indicates that the HubSpot contact has registered for the event.ATTENDED
: indicates that the HubSpot contact has attended the event. If you're updating a contact's status to ATTENDED, you can also include thejoinedAt
andleftAt
timestamps as parameters in the request body, specified in the ISO8601 Instant format.CANCELLED
: indicates that the HubSpot contact, who had previously registered for the event, has cancelled their registration.
Please note:
If you were previously using the /upsert
or /email-upsert
endpoints to update an attendee's status, you can instead use the alternate endpoints listed below. However, compared to the event attendance endpoints above, using these endpoints will not provide support for the following:
- Creating a new contact if it doesn't already exist.
- Showing timeline events on the contact record page.
- Specifying the
joinedAt
orleftAt
properties. - Providing a detailed response upon success.
If you do use the endpoints that require the externalEventId
from your app, you can either use the contact IDs or email address of existing contacts:
- If you want to use the contact IDs of existing contacts:
- Make a
POST
request to/marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/create
, using the ID of the event from your external application as theexternalEventId
. - In the request body, provide an
inputs
object that includes the following fields:interactionDateTime
: the date and time at which the contact subscribed to the event.vid
: the contact ID of an existing contact.
- Make a
- If you want to use the email address of one of the event's attendees:
- Make a
POST
request to/marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/email-create
. - In the request body, provide an
inputs
object that includes the following fields:interactionDateTime
: the date and time at which the contact subscribed to the event.email
: the email address of the attendee as the value of the email field within an inputs
- If the email address you include don't match the address of an existing contact, a new contact will be created.
- Make a
For both of the endpoints above, provide the following values for the corresponding path parameters:
externalEventId
: the ID of the marketing event. Check out the section above for more details on using the objectId of an event versus using its external IDs.subscriberState
: an enumeration that matches the new attendance status of the contact:REGISTERED
: indicates that the HubSpot contact has registered for the event.ATTENDED
: indicates that the HubSpot contact has attended the event. If you're updating a contact's status to ATTENDED, you can also include thejoinedAt
andleftAt
timestamps as parameters in the request body, specified in the ISO8601 Instant format.CANCELLED
: indicates that the HubSpot contact, who had previously registered for the event, has cancelled their registration.
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 attendance state multiple times without HubSpot creating duplicate events in the marketing events properties.
You can use the participation endpoints to retrieve event participant data for your marketing events. You can query data such as aggregate metrics for a specific event, as well as participant data for a specific contact or event.
Review the available participation endpoints below. For a full reference of all available parameters for each endpoint, check out the reference documentation.
Please note:
The activity counts in the marketing events page in your HubSpot account may differ from the corresponding aggregate metrics from the participation counters API endpoint.
For example, if a participant registered for an event, then cancelled, then re-registered for the same event, each of those activities will be included in the totals you see in the marketing events UI in your account. If you're using the participant state endpoints below, only the current state of a participant is included in the associated counter for that metric (e.g., attended
, registered
, cancelled
, or noShows
).
To get event participation data for a specific contact, make a GET
request to /marketing/v3/marketing-events/participations/contacts/{contactIdentifier}/breakdown
, using's the contact's ID or email address as the contactIdentifier
path parameter.
The response will include a summary of the contact's event participation in the properties
field:
xxxxxxxxxx
{
"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
}
}
]
}
To get a breakdown of participation data for a specific event, use your externalAccountId
and the externalEventId
of your event to make a GET
request to /marketing/v3/marketing-events/participations/{externalAccountId}/{externalEventId}/breakdown
.
To get an aggregate participation summary for an event, use your externalAccountId
and the externalEventId
of your event to make a GET
request to /marketing/v3/marketing-events/participations/{externalAccountId}/{externalEventId}
.
The response will include the total attendance counts:
xxxxxxxxxx
{
"attended": 152,
"registered": 200,
"cancelled": 3,
"noShows": 8
}
When fetching breakdown data or event participation data for a specific contact, you can filter the resulting data using the contactIdentifier, state, limit, or after fields as query parameters in your request.
Query parameter | Type | Description |
---|---|---|
contactIdentifier | string | The email address or ID of a specific contact |
state | Enumeration | The participation state for the event. The possible participation states are:
|
limit | Number | Limit the results returned. By default, the limit is set to 10. The valid range is 1-100. |
after | Number | Used for paging between results in the response. Consult the provided offset in the previous page of response data to determine the next index of results to return. |
You can use the endpoints described in the sections below to manage associations between lists and your marketing events.
Many of these endpoints require a listId
as a path parameter, which you can find on the list details page in your HubSpot account:
- In your HubSpot account, navigate to CRM > Lists.
- Click the name of a list.
- In the top right, click Details.
- In the right panel, the list ID will appear under List IDs for API integrations. You can click Copy list ID to copy the ID to the clipboard.
As you associate lists with your marketing events, they'll appear on the details page for a marketing event in your HubSpot account:
- In your HubSpot account, navigate to CRM > Contacts.
- In the upper left, click Contacts and in the dropdown menu, select Marketing events.
- Click the name of a marketing event.
- On the Performance tab, click Lists to expand the section, then click the Lists added through associations tab.
To create a new association between a marketing event and an existing list, make a PUT
request to /marketing/v3/marketing-events/associations/{marketingEventId}/lists/{listId}
.
If successful, you'll receive a 204 No content
response.
To create a new association between a marketing event and an existing list using the external account ID and the external event ID, make a PUT
request to /marketing/v3/marketing-events/associations/{externalAccountId}/{externalEventId}/lists/{listId}
.
If successful, you'll receive a 204 No content
response.
To get all lists associated with a marketing event, make a GET
request to /marketing/v3/marketing-events/associations/{marketingEventId}/lists
.
The response will resemble the following:
xxxxxxxxxx
{
"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
}
]
}
You can also get lists associated with a marketing event using an external account ID and the external event ID, make a GET
request to /marketing/v3/marketing-events/associations/{externalAccountId}/{externalEventId}/lists
.
To delete a list association for a marketing event using a marketing event ID, make a DELETE
request to /marketing/v3/marketing-events/associations/{marketingEventId}/lists/{listId}
.
If successful, you'll receive a 204 No content
response.
To delete a list association for a marketing event using the external account ID and an external event ID, make a DELETE
request to /marketing/v3/marketing-events/associations/{externalAccountId}/{externalEventId}/lists/{listId}
.
If successful, you'll receive a 204 No content
response.
There's some setup required to allow marketing events to sync properly with HubSpot.
If you send HubSpot an attendance state change (e.g., a registration or cancellation), 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 attendance state change.
This is provided for convenience; however, it's still recommended that you create the Marketing Events yourself via the CRUD methods provided in the reference documentation, and don't rely on this functionality to create your marketing events in HubSpot.
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
: a query parameter that specifies the accountId of the customer in the external app.appId
: a query parameter that specifies the ID of the HubSpot application that is requesting the event details. This will be the ID of your app.externalEventId
: a path parameter in the URL of the request that specifies the ID of the event in the external app that HubSpot requires details about.
- Returns:
- A JSON object that provides details for the marketing event, that includes the following fields detailed in the table below:
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 |
HubSpot will also send a X-HubSpot-Signature-v3
header that you can use to verify that the request came from HubSpot. Read more about request signatures for additional details on the signature and how to validate it.
Now that you've created the API in your app that will return an object that provides the details of a specific marketing event, you will need to provide HubSpot with the URL path to your API by making a POST
request to /marketing/v3/marketing-events/{appId}/settings
. This will allow HubSpot to determine how to make requests to your app to get the details of a marketing event.
In the body of your POST
request, specify your URL using the eventDetailsURL
field. The eventDetailsURL
must adhere to the following two requirements:
- Contain a
%s
character sequence, which HubSpot will use to substitute in the ID of the event (externalEventId
) as a path parameter. - It must be the full path to the API resource, including the
https://
prefix and the domain name (e.g.,my.event.app
).
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