Marketing Events API Update

Written by Hannah Seligson | Nov 13, 2024 5:20:34 PM

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 for a peer-to-peer discussion.

View full post