Skip to content
HubSpot Developer Changelog

Introducing New Participant State API

We are excited to announce today, June 4th, 2024, that we are releasing a new Participant State API and the new Marketing Event Attendance State CRM object. This API is designed to enhance the management and analysis of participant data at marketing events.
This new API allows app developers to read access to the Marketing Event Attendance State CRM object that returns detailed metrics on participant engagement, providing valuable insights to optimize event outcomes.

Key API Features and Capabilities

  • Fetch Event Statistics and Contact Details: Easily access comprehensive event statistics and detailed participation information for individual contacts.
  • Participation Counters by Internal Identifier (marketingEventId): Retrieve participation counters using the internal event identifier to get aggregate data on participant numbers.
  • Participation Counters by External Account and Event IDs: Access participation data using external account and event IDs, seamlessly integrating external system data.
  • Read Contact's Participation Information: Obtain detailed engagement information for contacts through their email or internal ID, helping to track individual interactions across multiple events.
  • Read List of Marketing Events by Contact Identifier: Get a list of marketing events associated with a specific contact using their email or internal ID.
  • Read Marketing Event's Participation Breakdown: Analyze participation details for marketing events using either external account and event IDs or the internal marketingEventId. This feature provides a detailed participant engagement breakdown, helping to better understand event performance.
  • Marketing Events Attendance State CRM Object: Calculates the overall participation activity from the events. This is a read-only object that cannot be manipulated through the API or the HubSpot UI.

Example API response of returned participation data for a contact leveraging the following endpoint: GET /marketing/v3/marketing-events/participations/contacts/{contactIdentifier}/breakdown

Note: The contact ID or email address for the contact can be leveraged as the contactIdentifier path param.

// Example response for GET request for contact participation data { "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 } } ] }

Understanding Participant State vs. Timestamp Activities

Unlike traditional methods that track participant interactions through timestamped activities, the Participant State API offers a dynamic state for each participant. This state reflects their overall status regarding the event, providing a more comprehensive understanding of their engagement.

Important note: The participant state will not change existing event functionality.

Introducing 'No Show' State

One of the most innovative features of the Participant State API is the introduction of the 'No Show' state. This state is automatically generated for participants without registering for any attended activity after an event concludes. It's a game-changer in accurately tracking participant engagement and identifying drop-offs.

Questions or comments? Please join the peer-to-peer developer community forum.