Getting started with MyPreferences 3.0 Version 4 API is easy.  Before we dive in, let's spend some time to learn about the supported authorization options and understand how the API library is categorized based on MyPreferences' core framework.

Using API's

Refer to the Authorization section to discover the different authorization methods supported for accessing the MyPreferences API.

The MyPreferences API is a RESTful API that conforms to the constraints of a software architectural style called REST (Representational State Transfer). The API makes the configuration objects and data available as resources represented by unique URLs, also referred as endpoints.

In general, the API supports the following request methods:

GET: To retrieve a resource

POST: To create a new resource

PUT: To update (overwrite) an existing resource

PATCH: To perform partial updates to an existing resource

DELETE: To delete a resource

To access the Swagger specification of the MyPreferences API, click here.

API Categorization

The API's are categorized into three separate sets with distinct functionalities based on the application's core framework: Experiences, Data, and Connectivity.

Data Categorization

In MyPreferences, the data is organized in three main areas: Profiles, Preferences and Consents. The data elements collected in these areas coalesce to form a unified profile, capturing a comprehensive depiction of an individual's identity, preferences, and consents across all channels and interactions across their customer journey.

Profiles

In the Profiles area, you can store various data points including names, contact information, group affiliations, and a wide range of demographic and psychographic details.

Additionally, you have the flexibility to store multiple Alternate IDs, such as system and device identifiers, to uniquely identify individuals and devices within your enterprise ecosystem. This area also encompasses the storage of consents not linked to specific contact elements or preferences, along with Tags, Custom Fields, and Groups for comprehensive organization and categorization of customer data.

Preferences

The Preferences area stores all customer choices, subscriptions, communication frequencies, engagement channels, and any preference attributes. Designed with built-in rules to honor the right preference, propagate preferences, apply expiration, associate consents, and maintain complete preference history to satisfy compliance audits.

Consents

The Consents area serves as a universal consent repository that stores and manages all customer consents. With limitless granularity, you can attach consents to an individual, device or an application. You can also associate consents to a contact element or a preference communication. Designed with built-in rules to honor the right consent, apply expiration settings, auto-notify when a new consent version becomes available, and maintain complete consent history to satisfy compliance audits.

The Experience API's, also known as Configuration API's, are a suite of API's purpose-built for retrieving zero-party data configurations to drive highly personalized and relevant customer experiences.

These APIs have built-in localization support and offer specific query parameters to retrieve customized consent, preference, and other zero-party data configurations. This grants you total control over your customers' experiences, covering everything from micro experiences to comprehensive preference centers and everything in between.

These API's are classified as follows:

• Profile Configuration
• Preference Configuration

The Data API's facilitate the display and collection of zero-party data for individual profiles across customer touchpoints. When driving customer experiences, they work seamlessly in conjunction with the Experience API to ensure that the relevant elements are accurately displayed on user interfaces, delivering highly personalized customer experiences.

Using the Data API's, you can use any data point on a profile to retrieve the profile. Please note that using contact elements, custom fields, groups, and tags to retrieve a profile may result in multiple matching profiles being returned.

A suite of historical API's are also available as part of this API library. You can retrieve the entire history for any data point associated with a user's profile, including standard fields, contact elements, custom fields, preferences, consents, and more.

The Integration API suite includes asynchronous RESTful APIs for bulk import/export operations and Event APIs for retrieving event data, along with webhook subscriptions for real-time updates.

Bulk API

The MyPreferences 3.0 Bulk API is a powerful and efficient asynchronous RESTful API that serves as a robust conduit for seamless data transfer between MyPreferences and various external systems within your enterprise. It ensures that you can effortlessly manage and exchange large datasets, streamlining the process of integrating zero-party data across your technology ecosystem.

One of the primary advantages of the Bulk API lies in its ability to enable near-real time synchronization of customer data. This means that any updates or changes made within MyPreferences or other connected cloud-based or on-premise systems in your enterprise are swiftly propagated and reflected in the interconnected systems. As a result, your organization can maintain a consistent, up-to-date, and comprehensive view of customer data, which is essential for delivering personalized experiences to your customers.

Events API

Event APIs allow you to retrieve event data by account, subscription, profile, or specific event ID based on your webhook subscriptions. They facilitate experiences which enable customers to view their activity history, recent actions, and profile updates in real-time. By retrieving data based on webhook subscriptions, these APIs allow customers to track and review any changes or interactions they have made to their profiles, ensuring they have access to the most up-to-date information about their account activities.

Initiate request by specifying a segment name. Specify lastdatetime to retrieve updates for a specific period.

You can also specify MatchCriteria to retrieve data for specific profiles. ProfileID, AlternateID, EmailAddress, and PhoneNumber are the supported match criteria. Based on your match criteria, specify one or more corresponding values under the Values array.

You can optionally specify a Customer Type when using ProfileID as the match criteria. The output data will be generated based on the defined segment criteria and will only include profiles from your request that contain the specified customer type. When using EmailAddress or PhoneNumber as the match criteria, specify a Type only if the segment does not already have any Types configured. If the segment includes search criteria that filter based on Types, providing a Type will cause the API to return a 409 Conflict response.

Retrieve the data. You may iterate through multiple calls until all records are retrieved. The access token will expire automatically upon complete data retrieval.

Set the keepAlive parameter to true to retrieve data beyond the initial retrieval. The default value is set to false, if not specified.

Segments for deleted profiles will only output the profile ID, the date of deletion, and the reason code for the selected timeframe. No additional customer data from the profile will be included in the output.

Returns the status of your request. If a callback URL is provided with your Initiate request, MyPreferences will POST the status to the callback URL.

This endpoint should only be accessed if the keepAlive parameter was set to true when retrieving the data. Invoking this endpoint marks the data retrieval as “complete” and expires the access token.

What are Events?

Events are distinct actions performed within MyPreferences. They serve as triggers to notify external systems about specific activities or changes. Events provide real-time information to keep systems informed and enable integration with other tools and services through webhooks.

An action may be system initiated or user initiated. For instance, it could involve updating the status of a consent or simply switching the IsMobile status on a phone number. These actions also encompass automated tasks executed by the system, such as propagating preferences and consents, as well as recording opt-outs triggered via the Status Manager integration.

An event is synonymous with an Event Type, serving as a clear indicator of the type of action that occurred. Each event type is associated with an Entity.

An Entity represents an object which supports one or more event types. For example, the Preference entity supports the following event types.

• preference.added
• preference.updated
• preference.archived

Types of Events

Actions performed on profiles are referred to as Data Events, whereas actions performed exclusively on configuration objects to update, remove or modify configuration settings are referred to as Configuration Events. Currently, MyPreferences only supports data events and offers a wide range of events that cover various interactions and activities within the platform.

The following list highlights all the Data events supported by MyPreferences.

Subscribing to Events

To receive notifications about specific events, MyPreferences clients can subscribe to one or more event types of interest. This involves setting up a webbook subscription, which allows MyPreferences to send event data as an HTTP POST request to an external endpoint that you specify in your subscription request. Click here to access the Create Subscriptions API.

Authentication

Authentication is crucial to ensure the security and integrity of webbook interactions. MyPreferences webhooks support signature validation that allows receiving endpoints to validate webhook's authenticity, i.e., verify that the data is being posted by MyPreferences. Applications receiving event notifications shall provide a secret key which is configurable on all MyPreferences accounts.

All webhook notifications except the initial validation handshake message include a MyPreferences-Webhook header which contains two parameters, Timestamp and Signature.

The Timestamp parameter is part of the header and is also used when generating the signature. Therefore, during signature validation by the receiving system, any modification to the Timestamp field should result in the rejection of the POST request. The Issued Timestamp field is a valid ISO8601 formatted timestamp.

The Signature parameter is generated using a hash-based message authentication code (HMAC) using SHA2 -512. The hash signature is included in the request (authorization) header on each POST request delivered by the webhook.

These parameters are generated and included each time an event is dispatched to a receiving endpoint. In situations where the event is retried due to a failure, a new signature and timestamp is generated for each new attempt.

MyPreferences-Webhook Timestamp:2023-08-16T03:04:54Z Signature:0FIgmwOCx1iZNGqVzCkTZLipCDrVlBhZVKulO80QM0tGocr3axmmZ1x7jwB3doaI6lbagVm0+piN8OMcpxjl8w== MyPreferences-Webhook Timestamp:2023-08-16T03:04:54Z Signature:0FIgmwOCx1iZNGqVzCkTZLipCDrVlBhZVKulO80QM0tGocr3axmmZ1x7jwB3doaI6lbagVm0+piN8OMcpxjl8w== 

The ClientId, EventsClientSignatureUserId, Timestamp, and a Hashkey are used to construct a SHA512 HTMAC hash. This is similar to generating a hash using the custom authorization scheme to access the MyPreferences REST API. Your receiving application consuming the webhooks is expected to extract the timestamp from the header and use the ClientId, EventsClientSignatureUserId, and Hashkey to reconstruct the signature using SHA512. Your re-computed signature (converted to UTF-8 bytes and then to BASE64) must match the Signature included in the header. If it doesn't, the message must be considered as altered and should be rejected.

Initial Handshake

For all webhook subscriptions, the receiving application needs to participate in a validation handshake. Once the subscription is created, MyPreferences will issue a unique token to the receiving URL before any actual data is delivered. The schema of this event is similar to an actual data event and is shown below.

The data portion of this event includes a validationCode property. Your application verifies that the validation request is for an expected event subscription, and returns the validation code in the response synchronously. Once the handshake is established, your endpoint is authenticated, and it can continue receiving webhook notifications without needing to repeat the token exchange. This ensures secure and seamless communication between MyPreferences and your receiving application.

{
  "data": {
    "validationCode": "056C6FF4-3929-42AC-8E94-C6E021FD1C7B",
    "validationUrl": "https://rp-eastus.eventgrid.azure.net:553/eventsubscriptions/53286-1-7f396aa65cda44338b7763091cc02608-221/validate?id=056C6FF4-3929-42AC-8E94-C6E021FD1C7B&t=2024-07-24T14:09:00.9068770Z&apiVersion=2022-06-15&token=mUTqCc6C6t30ij3vEictNyEP%2baZlJ0cqe8RgeqB%2fo74%3d"
  },
  "dataVersion": "2",
  "eventTime": "2024-07-24T14:09:00.9069218Z",
  "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
  "id": "dfd3c295-0a8b-43c8-be7f-bee71f9842e9",
  "metadataVersion": "1",
  "subject": "",
  "topic": "/subscriptions/1ba4431b-6125-4da0-b908-a890a2e39206/resourceGroups/rgroupdnc29/providers/microsoft.eventgrid/domains/eventgriddomainstaging01/topics/53286-1-7f396aa65cda44338b7763091cc02608"
} {
  "data": {
    "validationCode": "056C6FF4-3929-42AC-8E94-C6E021FD1C7B",
    "validationUrl": "https://rp-eastus.eventgrid.azure.net:553/eventsubscriptions/53286-1-7f396aa65cda44338b7763091cc02608-221/validate?id=056C6FF4-3929-42AC-8E94-C6E021FD1C7B&t=2024-07-24T14:09:00.9068770Z&apiVersion=2022-06-15&token=mUTqCc6C6t30ij3vEictNyEP%2baZlJ0cqe8RgeqB%2fo74%3d"
  },
  "dataVersion": "2",
  "eventTime": "2024-07-24T14:09:00.9069218Z",
  "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
  "id": "dfd3c295-0a8b-43c8-be7f-bee71f9842e9",
  "metadataVersion": "1",
  "subject": "",
  "topic": "/subscriptions/1ba4431b-6125-4da0-b908-a890a2e39206/resourceGroups/rgroupdnc29/providers/microsoft.eventgrid/domains/eventgriddomainstaging01/topics/53286-1-7f396aa65cda44338b7763091cc02608"
} 

To prove endpoint ownership, send back the validation code in the validationResponse property as shown below:

{
  "validationResponse": "056C6FF4-3929-42AC-8E94-C6E021FD1C7B056C6FF4-3929-42AC-8E94-C6E021FD1C7B"
} {
  "validationResponse": "056C6FF4-3929-42AC-8E94-C6E021FD1C7B056C6FF4-3929-42AC-8E94-C6E021FD1C7B"
} 

You must return an HTTP 200-OK response status code. 202-Accepted isn't recognized as a valid response. The HTTP request must complete within 30 seconds. If the operation doesn't finish within 30 seconds, it will be canceled and can be reattempted after 5 seconds. If all the attempts fail, it will be treated as validation handshake error.

Asynchronous handshake

If you cannot return the validationCode in your response synchronously, a validationUrl property is also included in the data portion of the subscription validation event. To complete the handshake, find that URL in the event data and do a GET request to it. You can use either a REST client or your web browser.

The provided URL is valid for 5 minutes. During that time, the provisioning state of the event subscription is AwaitingManualAction. If you don't complete the manual validation within 5 minutes, the provisioning state is set to Failed. You'll have to create the event subscription again before starting the manual validation.

This method of authentication also requires the webhook endpoint to provide an HTTP status code of 200. This confirms the acceptance of the POST request for the validation event, which is a prerequisite before transitioning into manual validation mode. If the endpoint returns a 200 status code but fails to provide a validation response in a synchronous manner, the system will switch to manual validation mode. Furthermore, if a GET request is made to the validation URL within a 5-minute timeframe, the validation handshake is deemed successful.

Your application's readiness to manage and return the validation code suggests that you've set up the event subscription and are ready to receive events.

Securing Events with mTLS

Events support Mutual Transport Layer Security (mTLS) which brings an extra layer of security between our system and the clients receiving the webhook notifications. With mTLS, both the webhook consumer (receiving systems subscribed to our webhooks) and the webhook producer (our server) engage in mutual authentication, establishing a secure and efficient communication channel. mTLS also ensures data integrity protecting sensitive data from unauthorized access and tampering.

Your receiving endpoint must be setup to handle mTLS, including initiating the validation handshake. mTLS authentication relies on digital certificates, therefore, clients must obtain digital certificates from a trusted Certificate Authority (CA) or an internal PKI (Public Key Infrastructure) before the handshake process.

To enable mTLS support, you must collaborate closely with our support team and follow the steps listed below.

Generate Client Certificate: Obtain a digital certificate for your receiving endpoint from a trusted Certificate Authority (CA). Ensure that the certificate includes the necessary identifying information and is signed by a trusted CA.

Webhook endpoint configuration: Configure your receiving endpoint to present its certificate to the server during the handshake process.

MyPreferences Configuration: The MyPreferences Support team will configure your client certificate on our server for authentication.

Trust Server Certificate: Ensure that your receiving endpoint trusts the certificate provided by MyPreferences.

Test Connection: Test the connection between your receiving endpoint and MyPreferences to ensure that mTLS authentication is setup and functioning correctly.

You will closely collaborate with our support team throughout the setup procedures. Should you encounter any issues during the setup process, reach out to our support team for assistance.

Receiving Events

The system expects a HTTP 200-OK response from the webhook URL. Any other response codes (3xx, 4xx, or 5xx) are treated as a failure. Once the handshake is established, no content is required in the response body from the target webhook URL.

The MaxConcurrentRequests and Durationsettings manage the events throughput. The MaxConcurrentRequests determines how many events the event delivery service will try to send in one cycle. The Duration determines how long it will wait between each cycle. Though we do not track the exact amount of events that are generated via the event handler service, it is a precautionary measure to maintain optimal delivery rate and frequency.

Creating and managing event subscriptions

MyPreferences provides a set of Subscription APIs to manage webhook subscriptions:

• POST /subscriptions: Create a new subscription by specifying the desired event types and the target webhook URL.
• GET /subscriptions: Retrieve a list of active subscriptions along with their details.
• PUT /subscriptions/{subscription_id}: Update the configuration of an existing subscription, such as updating the list of event types.
• DELETE /subscriptions/{subscription_id}: Deactivate and remove a subscription, stopping notifications for selected event types.

Event Payload

When an event occurs, MyPreferences sends an HTTP POST request to the subscribed endpoint. The payload contains information about the event, including its type, timestamp, and relevant data associated with the event.

Subscription Payload

The subscription payload includes details about the subscription itself, such as the ID, webhook URL, and subscribed event types. This information helps identify the source of incoming requests and the event types being monitored.

Failures and retries

MyPreferences expects a 200-OK response to mark the request as success. All configured webhook URLs shall return a 200-OK response immediately upon receiving the event.

The system waits 30 seconds for a response after delivering a message. After 30 seconds, if the endpoint hasn’t responded, the message is queued for retry. It uses an exponential backoff retry policy for event delivery. The retries are performed based on the following schedule on a best effort basis:

If the endpoint responds within three minutes, the message distribution service attempts to remove the event from the retry queue on a best effort basis, but duplicates may still be received. It adds a small randomization to all retry steps and may opportunistically skip certain retries if an endpoint is consistently unhealthy, down for a long period, or appears to be overwhelmed.

The service supports the following retry configurations. An event is dropped if either of the limits of the retry policy is reached.

10 seconds
30 seconds
1 minute
5 minutes
10 minutes
30 minutes
1 hour
3 hours 10 seconds
30 seconds
1 minute
5 minutes
10 minutes
30 minutes
1 hour
3 hours 

Event time-to-live (TTL): The value must be an integer between 1 and 240. The default value is 240 minutes.

An event is sent to the dead letter queue if it is not delivered within the time-to-live period or the number of retries limit is reached. If we receive a 400 (Bad Request) or 413 (Request Entity Too Large) response code, the event is immediately scheduled for dead-lettering. These response codes indicate delivery of the event will never succeed.

The time-to-live expiration is checked only at the next scheduled delivery attempt. So, even if time-to-live expires before the next scheduled delivery attempt, event expiry is checked only at the time of the next delivery and then subsequently dead-lettered.

Once the event is sent to the dead-letter queue, the event delivery is abandoned. Our event failure notification service picks up the record from the queue, extracts the details, including the appropriate http status returned, failure reason. and sends out email alerts to the list of recipients configured to receive event failure alerts. The alerts are sent based on the alert criteria configuration described below.

Alerts

Alerts are not sent during the retry process. Once the event is sent to the dead-letter queue, the alert notifications are triggered based on the settings detailed below.

Alert Frequency: This represents the rate at which alerts are generated within a specific duration. It indicates how often an alert is triggered based on the occurrence of an event that failed to deliver. It contains the following settings:

• Alert Frequency (Min): This setting defines the minimum time between alerts. It ensures that once an alert is triggered, there is a designated gap before another alert can be generated. This prevents MyPreferences from generating excessive alerts and creating unnecessary noise. Default setting is 5 minutes. It supports values more than 0.
• Alert Frequency (Max): This setting defines the maximum rate at which alerts are triggered when the webhook fails. For example, if the max frequency is set to 5 minutes, the system will not generate more than one alert every 5 minutes. Default setting is 30 minutes.

Alert Threshold: This represents the count/number of errors or failures that must occur within a designated time period to trigger an alert. It ensures that only significant issues are flagged for immediate attention. It works in conjunction with “Alert Frequency” settings. It contains the following settings:

• Alert Threshold (Min): This is the minimum number of errors/failures that must occur within a designated time-frame to trigger an alert. It works in conjunction with “Alert Frequency”. Only values greater than "0" are supported for this setting. The default value is set to "1". Min value cannot exceed "100". For example, if it is is set to 5 consecutive failures, an alert will be generated only if the webhook fails to send notifications for 5 consecutive attempts.
• Alert Threshold (Max): This is the maximum allowable number of errors/failures within a defined duration before generating an alert. It helps prevent excessive alerting for less severe issues. It sets the maximum number of failures that are allowed before the system stops generating alerts. Works in conjunction with “Alert Frequency”. Only values greater than "5" are supported. The default value is set to "15". Max value cannot exceed "1000".

Usage and Recommendations

Utilizing webhooks effectively requires careful consideration of event selection and implementing best practices. One approach is to selectively subscribe to specific event types that align with your needs. For instance, subscribing to profile.created or profile.replaced event types can be advantageous as they provide comprehensive profile information by returning the entire profile. By choosing these events, you can streamline data retrieval while reducing unnecessary traffic.

The profile.replaced event is specifically generated when a PUT operation is performed to overwrite the profile. MyPreferences will not send any other events when profile.created or profile.replaced events are triggered.

When subscribing to Preference events, you can specify the Filters for which you want to receive events. You can specify AllFilters to receive events for all filters.

When subscribing to Consent events, you can specify the Consent Types for which you want to receive events. You can specify AllConsents to receive events for all consent types configured in your MyPreferences account. The same applies to Groups , Contacts, and Custom Fields.

Events for Standard Fields and Tags are applied globally across all profiles. For example, if you subscribe to standardfield.firstname.updated event type, a webhook notification is triggered anytime the first name field gets updated on any active profile.

Multiple actions = Multiple events

Often times, a simple operation on a profile may trigger multiple events. For example, a user adds an email address to their profile, updates a communication preference, and grants a consent. This action will result in the following event types being generated, each indicating the exact operation performed on customer's data.

• profile.updated
• contacts.email.added
• preference.added
• consent.filterassociation.created

Each event represents an independent action. You must pay close attention to elements such as OriginalEventTime, EventTime, ProfileId, and associated data to correctly sequence the updates made to a user's profile.

The OriginalEventTime property denotes the date and time when the event occurred. The EventTime property represents the date and time when the event was queued for distribution. These dates are designed to help you determine the processing order as well as identify the lag between the time it took to receive the event from its initial capture.

The Data property includes the updated customer data associated with the event and makes it available for immediate use. The Event property specifies the actual event.

By leveraging MyPreferences Events and Subscriptions framework, clients can stay informed about crucial activities within the platform and seamlessly integrate MyPreferences with external systems to enhance their workflow and decision-making processes.