Developer Announcements

hseligson
HubSpot Employee
HubSpot Employee

Marketing Events API Update

We are excited to announce, starting on November 13th, an update to the Marketing Events API that addresses existing limitations and significantly enhances event management and data analysis capabilities for app developers. This update enables access to all Marketing Events via the API, regardless of their creation source, allowing for comprehensive event management and analysis.

 

What's changing?

Current API limitations

  1. Identifier Constraints:
  • The Marketing Events API currently uses two primary identifiers: externalEventId and externalAccountId.
    • externalEventId: Represents the event ID within a specific app.
    • externalAccountId: Represents the account ID within a specific app.
  • Each application is limited to interacting only with the Marketing Events it has created, restricting cross-app event management capabilities.
  1. Offline & Manually Created Events:
  • Events created directly from the UI with manually imported participants lack the externalEventId and externalAccountId fields. As a result, they are inaccessible through the API, limiting apps' ability to manage or analyze them.

New functionality

  1. Unified Access
  • The API now provides access to all Marketing Events, irrespective of their creation source, by:
    • Allowing apps to retrieve and interact with Marketing Events created by other applications.
    • Mechanisms to interact with events created via the UI should be provided, even if these events do not possess externalEventId and externalAccountId.
  1. Enhanced API Endpoints:
  • We have developed new and enhanced existing endpoints to support the retrieval, analysis, and management of all marketing events and adding participants using the objectId.
    These endpoints have advanced querying and filtering capabilities, enabling more robust and flexible event management by introducing the ability to interact through externalEventId, externalAccountId, and internal objectId. Each API method will return the internal objectId, enabling interactions with all marketing events. Whether created through integrations or manually. 

Below are listed the new endpoints. Please refer to the API documentation for more information.

 

Basic

GET /marketing/v3/marketing-events/{objectId}

Returns the details of the Marketing Event with the specified Id

GET /marketing/v3/marketing-events

Returns details of all Marketing Events

PATCH /marketing/v3/marketing-events/{objectId}

Updates an existing Marketing Event with the specified Id, if one exists

DELETE /marketing/v3/marketing-events/{objectId}

Deletes an existing Marketing Event with the specified Id, if one exists

Search

GET /marketing/v3/marketing-events/{externalEventId}/identifiers

Searches the portal for all Marketing Events whose externalEventId matches the value provided in the request.

Batch

POST  /marketing/v3/marketing-events/batch/update

Update multiple marketing events

POST  /marketing/v3/marketing-events/batch/archive

Delete multiple marketing events

Attendance

POST
/marketing/v3/marketing-events/{objectId}/attendance/{subscriberState}/email-create

Record participation state between multiple contacts and a marketing event, using contact email addresses

POST
/marketing/v3/marketing-events/{objectId}/attendance/{subscriberState}/create

Record participation state between multiple contacts and a marketing event, using contact Ids

 

What does this mean for developers?

No changes are required for developers already using the Marketing Events API. However, this update brings significant advantages by enabling new cross-app event management and data analysis capabilities. To maximize these features, we recommend reviewing the updated API documentation.

 

Starting on November 13th, developers will have access to the following endpoints. Endpoints related to objectId, are the only ones in beta and are expected to go live by the end of Q4:

  • GET /marketing/v3/marketing-events/{objectId}
  • PATCH /marketing/v3/marketing-events/{objectId}
  • DELETE /marketing/v3/marketing-events/{objectId}

Questions or comments? Join us in the developer forums below for a peer-to-peer discussion.

0 Replies 0

0 Replies

No replies on this post just yet

No one has replied to this post quite yet. Check back soon to see if someone has a solution, or submit your own reply if you know how to help! Karma is real.

Reply to post

Need help replying? Check out our Community Guidelines