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
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.
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
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.
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.
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.