PossibleNOW Documentation

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.

Production:

https://pm.mypreferences.com/Profiles/v4

Sandbox:

https://pmstg.mypreferences.com/Profiles/v4

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

Endpoints

POST

GET

PATCH

POST

GET

PATCH

POST

GET

PATCH

POST

GET

PATCH

POST

PATCH

GET

POST

GET

PATCH

POST

GET

POST

GET

POST

GET

POST

GET

PATCH

POST

GET

PATCH

POST

GET

PATCH

GET

DELETE

GET

The Profile Configuration API allows you to define all aspects of customer profile configuration including names, contact information, group affiliations, and a wide range of demographic and psychographic details using standard and custom fields.

Additionally, you have the flexibility to create Alternate IDs, such as system and device identifiers, to uniquely identify individuals and devices within your enterprise ecosystem. This API also allows you to create and manage Consents, Tags, Custom Fields, and Groups for comprehensive organization and categorization of customer data.

These API's work in conjunction with the Preference Configuration API to display a complete and highly personalized customer experience.

MyPreferences serves as a universal consent repository managing consents around an individual or device (IoT) across any data category.

The Consents API suite provides complete control over the entire lifecycle of consents. This includes functionalities for creating, updating, and deactivating consent types. A Consent Type represents a specific category or classification of consent. With capabilities to add new consent types, retrieve existing ones, obtain supported consent statuses, and update specific consent types, it ensures a comprehensive management of consent-related information.

By utilizing HTTP PATCH requests, it facilitates partial modifications to consent configurations. This functionality enhances flexibility and provides greater control over consent configurations. The flexible nature of these methods offers greater control over consent configurations and ensures that user consent is accurately managed and remains compliant with diverse data privacy regulations.

Contact Types allow you to classify your contacts based on the context or purpose of their communication. By assigning specific contact types, such as "Home email," "Work email," "Home phone," or "Work phone," you can easily differentiate and organize your customer contacts according to their respective roles and usage as determined by the individual.

The Name and Description fields on all Contact Types support localization which helps you configure them in any language to support multilingual customer experiences.

Preferences on a profile are always associated with a Type. Types are broadly classified into two categories:

Contact Element Types

As the name suggests, contact element types are used for associating contacts for a specific communications channel, specifically Email, Phone, SMS, and Mail.

Let's consider the example of email. Clients can define distinct email types, such as "Work," "Home," and "Emergency." By doing so, users can assign specific email addresses to each type and also store preferences or associate consents accordingly.

Clients can define consent settings for each email type, indicating whether they allow or disallow certain types of communication or data sharing. For instance, a user may grant consent for work-related emails to be shared with colleagues within the company but restrict the sharing of personal emails with third parties.

Identity Types

Identity Types or Id Types include CustomerTypes, AlternateId Types, and Group Types.

Customer Types are used to classify profiles based on the type of customer. For example, a contact can be classified as a Customer or a Prospect. It is a required data element on every profile. Preferences which are stored on a profile that are not connected to a contact element type are stored using the customer type.

Alternate ID Types are used for associating additional identifiers that help you uniquely identify a profile across other systems. For example, customer identifiers from other applications such as Salesforce, Marketo, or Facebook can be stored as Alternate Ids. Alternate ID values are unique by Alternate ID Type across all profiles.

Group Types are used for classifying Groups. For example, you can set up groups named “Family”, “Football Fans”, “Employee”, etc. which can be used to connect a set of user profiles based on collective interests and characteristics. When assigning a user profile to a group, you pass in a Group Name and associate it with any of the available group types. You can also designate a profile as “Primary” within a group. When driving preference collection touchpoints, you can retrieve all profiles that are a part of a group using the Profile ID or a contact element of the primary profile associated with that group.

Custom Fields help you expand and enrich the collection of user profile data throughout the customer journey. A custom field can be one of the following types: Text, Numeric, DateTime, and SelectList. A picklist is required for SelectList custom fields

When creating custom fields, you can mark them as required and designate update rules for each field. These update rules are enforced by the API when custom fields are added or updated on a profile. The following updates are currently available for implementation.

• Always (default): Always updates the value • If Current Value Is Blank: Only updates if existing value on the custom field is blank • If New Value Is Not Blank: Only updates if the incoming value is not blank • Never: Once added to a profile, the field cannot be updated or removed

Group Types are used for classifying Groups. For example, you can set up groups named “Family”, “Football Fans”, “Employee”, etc. which can be used to connect a set of user profiles based on collective interests and characteristics. When assigning a user profile to a Group, you pass in a Group Name and associate it with any of the available Group Types.

You can also designate a profile as “Primary” within a group. When driving customer experiences, you can retrieve all profiles that are a part of a group using the Profile Id or any contact element of the primary profile associated with that group.

Picklists are sets of name-value pairs that are associated with a SelectList custom field. The Name field within a picklist supports localization, enabling the creation of multilingual customer experiences. The corresponding value is stored along with the custom field.

SelectList custom fields configured with a display type of “multi-select” can accommodate multiple values. Multiple values sent through the MyPreferences API are delimited using “::” double colon.

Tags help you organize and categorize profiles based on specific pieces of information associated with your customer and non-customer profiles. For example, you can tag users as Influencers or Reward members and retrieve profiles that match on those specific values.

Tags are unique and always exist within a context of a profile. You can add and delete tags without affecting other profile information.

Endpoints

GET

DELETE

The Preference Configuration API's allow you to retrieve preference configuration data with ease for driving personalized preference collection experiences across customer touchpoints. Using these API's, you can define and manage all aspects of preference configuration which includes the creation of Programs, Filters, Program Groups, Frequency Options, Preference Attributes, Custom Properties, and Locales.

Typically, these API's are used in conjunction with Profile Configuration API's to create holistic zero-party data experiences that encompass customer demographics, psychographics, preferences, consents, feedback, and other data points.

Program Groups allow you to categorize your programs based on common characteristics such as product lines, region, business units, customer types, etc.

The “Program Group” API allows you to retrieve program group information based on specific parameters. You can use the “Retrieve all Program Groups" method to retrieve the entire configuration for all program groups. You can use other methods to retrieve configuration for individual program groups or use the “Retrieve Program Groups (Include Matching)” and “Retrieve Program Groups (Include All)” methods to retrieve a dynamically generated set of program groups, programs, and filters based on your custom property criteria.

These API's enable you to build multi-level preference communication hierarchies for driving granular preference management experiences at various levels. They are natively designed to return your preference communications and choices based on your hierarchy setup. Alternatively, they also support use cases where you can flatten a preference hierarchy into a single, consolidated view.

Click here to watch a brief tutorial on program groups.

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

Retrieve configuration for a specific program. You can optionally specify localeId to only retrieve text tags for the specified locale.

This method will return all Filters and their associated configurations. It is typically used when driving experiences like opt-in forms and newsletter subscriptions, particularly when users are enrolling for a specific preference-oriented offering.

Header Parameters

Authorizationstring Required

Authorization token.

Content-Typestring

Type of the data being sent in the request or the data that is expected in the response. Supports application/json.

Query Parameters

localestring

A valid locale Id associated with a text tag on the specified program. If specified, the API response will only include text tags for the specified locale.

Path Parameters

clientIdstring

This is your MyPreferences account Id.

Messagestring

Nullable:

True

1
2
3

curl --location 'https://pm.mypreferences.com/Profiles/v4/string/Programs/string?locale=string' \
--header 'Authorization: string' \
--header 'Content-Type: application/json'

{
  "Programs": [
    {
      "Link": 1,
      "ID": "sample string 2",
      "Name": "sample string 3",
      "Description": "sample string 4",
      "DefaultLocaleID": "sample string 5",
      "ProgramType": "sample string 6",
      "DisplayOrder": 7,
      "CustomProperties": [
        {
          "Link": 1,
          "Key": "sample string 2",
          "Value": "sample string 3"
        }
      ],
      "Locales": [
        {
          "ID": "sample string 1",
          "DisplayTags": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ]
        }
      ],
      "Filters": [
        {
          "Link": 1,
          "ChannelID": "sample string 2",
          "ProgramID": "sample string 3",
          "ID": "sample string 4",
          "Name": "sample string 5",
          "Description": "sample string 6",
          "DefaultPreferenceValue": 7,
          "DefaultLocaleID": "sample string 7",
          "CustomProperties": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ],
          "Locales": [
            {
              "ID": "sample string 1",
              "DisplayTags": [
                {
                  "Link": "0",
                  "Key": "sample string 2",
                  "Value": "sample string 3"
                }
              ]
            }
          ],
          "FrequencyLocales": [
            {
              "ID": "sample string 1",
              "Frequencies": [
                {
                  "ID": "sample string 1",
                  "DisplayName": "sample string 2",
                  "Description": "sample string 3",
                  "IsDefault": true,
                  "DisplayOrder": "0"
                }
              ]
            }
          ],
          "Attributes": [
            {
              "Link": null,
              "ID": "",
              "AttributeType": "",
              "DisplayOrder": null,
              "IsRequired": false,
              "AttributeConstraints": [
                {
                  "ConstraintType": "string",
                  "constraintType": "",
                  "detail": ""
                }
              ],
              "DisplayTextLocales": [
                {
                  "Locale": "",
                  "Name": "",
                  "Description": ""
                }
              ]
            }
          ],
          "RequiredPreferenceConsents": [
            {
              "TypeName": "",
              "DisplayOrder": null
            }
          ]
        }
      ]
    }
  ]
}

Retrieve configuration for all programs. You can optionally specify localeId to only retrieve text tags for the specified locale.

Header Parameters

Authorizationstring Required

Authorization token.

Content-Typestring

Type of the data being sent in the request or the data that is expected in the response. Supports application/json.

Query Parameters

Object

The server is unable to handle your request due to a temporary condition. You must delay your request for some time before trying again. Notify PossibleNOW Support if it’s a continuous occurrence.

Response Attributes

Messagestring

Nullable:

True

1
2
3

curl --location 'https://pm.mypreferences.com/Profiles/v4/string/Programs?locale=string' \
--header 'Authorization: string' \
--header 'Content-Type: application/json'

{
  "Programs": [
    {
      "Link": 1,
      "ID": "sample string 2",
      "Name": "sample string 3",
      "Description": "sample string 4",
      "DefaultLocaleID": "sample string 5",
      "ProgramType": "sample string 6",
      "DisplayOrder": 7,
      "CustomProperties": [
        {
          "Link": 1,
          "Key": "sample string 2",
          "Value": "sample string 3"
        }
      ],
      "Locales": [
        {
          "ID": "sample string 1",
          "DisplayTags": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ]
        }
      ],
      "Filters": [
        {
          "Link": 1,
          "ChannelID": "sample string 2",
          "ProgramID": "sample string 3",
          "ID": "sample string 4",
          "Name": "sample string 5",
          "Description": "sample string 6",
          "DefaultPreferenceValue": 7,
          "DefaultLocaleID": "sample string 7",
          "CustomProperties": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ],
          "Locales": [
            {
              "ID": "sample string 1",
              "DisplayTags": [
                {
                  "Link": "0",
                  "Key": "sample string 2",
                  "Value": "sample string 3"
                }
              ]
            }
          ],
          "FrequencyLocales": [
            {
              "ID": "sample string 1",
              "Frequencies": [
                {
                  "ID": "sample string 1",
                  "DisplayName": "sample string 2",
                  "Description": "sample string 3",
                  "IsDefault": true,
                  "DisplayOrder": "0"
                }
              ]
            }
          ],
          "Attributes": [
            {
              "Link": null,
              "ID": "",
              "AttributeType": "",
              "DisplayOrder": null,
              "IsRequired": false,
              "AttributeConstraints": [
                {
                  "ConstraintType": "",
                  "Detail": ""
                }
              ],
              "DisplayTextLocales": [
                {
                  "Locale": "",
                  "Name": "",
                  "Description": ""
                }
              ]
            }
          ],
          "RequiredPreferenceConsents": [
            {
              "TypeName": "",
              "DisplayOrder": null
            }
          ]
        }
      ]
    }
  ]
}

Retrieve configuration for a specific program associated with a program group. You can optionally specify localeId to only retrieve text tags for the specified locale.

This call will return the default preference values for the Filters as defined in the specified program group.

Header Parameters

Authorizationstring Required

Authorization token

Content-Typestring

Type of the data being sent in the request or the data that is expected in the response. Supports application/json.

Query Parameters

localestring

A valid locale ID associated with a text tag. If specified, the API response will only include text tags for the specified locale.

Path Parameters

clientIdstring

This is your MyPreferences Account Id.

programGroupIdstring

Id of the program group that contains the program.

Messagestring

Nullable:

True

1
2
3

curl --location --globoff 'https://pm.mypreferences.com/Profiles/v4/string/Programs/string/string?locale={localeId}' \
--header 'Authorization: string' \
--header 'Content-Type: application/json'

{
  "Programs": [
    {
      "Link": 1,
      "ID": "sample string 2",
      "Name": "sample string 3",
      "Description": "sample string 4",
      "DefaultLocaleID": "sample string 5",
      "ProgramType": "sample string 6",
      "DisplayOrder": 7,
      "CustomProperties": [
        {
          "Link": 1,
          "Key": "sample string 2",
          "Value": "sample string 3"
        }
      ],
      "Locales": [
        {
          "ID": "sample string 1",
          "DisplayTags": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ]
        }
      ],
      "Filters": [
        {
          "Link": 1,
          "ChannelID": "sample string 2",
          "ProgramID": "sample string 3",
          "ID": "sample string 4",
          "Name": "sample string 5",
          "Description": "sample string 6",
          "DefaultPreferenceValue": 7,
          "DefaultLocaleID": "sample string 7",
          "CustomProperties": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ],
          "Locales": [
            {
              "ID": "sample string 1",
              "DisplayTags": [
                {
                  "Link": "0",
                  "Key": "sample string 2",
                  "Value": "sample string 3"
                }
              ]
            }
          ],
          "FrequencyLocales": [
            {
              "ID": "sample string 1",
              "Frequencies": [
                {
                  "ID": "sample string 1",
                  "DisplayName": "sample string 2",
                  "Description": "sample string 3",
                  "IsDefault": true,
                  "DisplayOrder": "0"
                }
              ]
            }
          ],
          "Attributes": [
            {
              "Link": null,
              "ID": "",
              "AttributeType": "",
              "DisplayOrder": null,
              "IsRequired": false,
              "AttributeConstraints": [
                {
                  "ConstraintType": "",
                  "Detail": ""
                }
              ],
              "DisplayTextLocales": [
                {
                  "Locale": "",
                  "Name": "",
                  "Description": ""
                }
              ]
            }
          ],
          "RequiredPreferenceConsents": [
            {
              "TypeName": "",
              "DisplayOrder": null
            }
          ]
        }
      ]
    }
  ]
}

Retrieve all programs that belong to a specific program type. You can optionally specify localeId to only retrieve text tags for the specified locale.

This method will return all programs and their associated configurations for the specified program type. Supported program types are “Transactional”, “Marketing”, “Informational”, “Consent”, and “Do Not Contact (DNC)”.

Header Parameters

Authorizationstring Required

Authorization token.

Content-Typestring

Type of the data being sent in the request or the data that is expected in the response. Supports application/json.

Query Parameters

localestring

A valid locale ID associated with a text tag. If specified, the API response will only include text tags for the specified locale.

Path Parameters

clientIdstring

This is your MyPreferences Account Id.

Messagestring

Nullable:

True

1
2
3

curl --location --globoff 'https://pm.mypreferences.com/Profiles/v4/string/Programs/ProgramTypes/string?locale={localeId}' \
--header 'Authorization: string' \
--header 'Content-Type: application/json'

{
  "Programs": [
    {
      "Link": 1,
      "ID": "sample string 2",
      "Name": "sample string 3",
      "Description": "sample string 4",
      "DefaultLocaleID": "sample string 5",
      "ProgramType": "sample string 6",
      "DisplayOrder": 7,
      "CustomProperties": [
        {
          "Link": 1,
          "Key": "sample string 2",
          "Value": "sample string 3"
        }
      ],
      "Locales": [
        {
          "ID": "sample string 1",
          "DisplayTags": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ]
        }
      ],
      "Filters": [
        {
          "Link": 1,
          "ChannelID": "sample string 2",
          "ProgramID": "sample string 3",
          "ID": "sample string 4",
          "Name": "sample string 5",
          "Description": "sample string 6",
          "DefaultPreferenceValue": 7,
          "DefaultLocaleID": "sample string 7",
          "CustomProperties": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ],
          "Locales": [
            {
              "ID": "sample string 1",
              "DisplayTags": [
                {
                  "Link": "0",
                  "Key": "sample string 2",
                  "Value": "sample string 3"
                }
              ]
            }
          ],
          "FrequencyLocales": [
            {
              "ID": "sample string 1",
              "Frequencies": [
                {
                  "ID": "sample string 1",
                  "DisplayName": "sample string 2",
                  "Description": "sample string 3",
                  "IsDefault": true,
                  "DisplayOrder": "0"
                }
              ]
            }
          ],
          "Attributes": [
            {
              "Link": null,
              "ID": "",
              "AttributeType": "",
              "DisplayOrder": null,
              "IsRequired": false,
              "AttributeConstraints": [
                {
                  "constraintType": "",
                  "detail": ""
                }
              ],
              "DisplayTextLocales": [
                {
                  "Locale": "",
                  "Name": "",
                  "Description": ""
                }
              ]
            }
          ],
          "RequiredPreferenceConsents": [
            {
              "TypeName": "",
              "DisplayOrder": null
            }
          ]
        }
      ]
    }
  ]
}

This method allows you to retrieve a specific set of programs that match the custom property criteria specified as query parameters in your request.

It returns all programs that match on the custom property criteria specified in the request, and only includes the filters that also match on the same custom property criteria.

What are custom properties?

Custom Properties are a collection of key-value pairs that can be attached to Program Groups, Programs, and Filters. The key is the name of the property and the value is the content.

While the actual customer data, such as their choices, consents, preferences, etc. helps you deliver an individualized experience, custom properties allow you to personalize it for specific audience segments. For example, a first time visitor may want to see options related to onboarding, whereas an existing customer might get a highly personalized experience.

You can define as many of these key-value pairs to support any level of specializations ranging from micro experiences to comprehensive preference centers and everything in between.

Example:

https://{Base URL}/{client_id}/Programs/IncludeMatching?Jurisdication=EU&OnlineOnly=True&LifeCycleStage

In this example, the API will return all programs and only those associated filters where custom properties exist with the following values:

"Jurisdiction" = EU,
"OnlineOnly" = True,
"LifeCycleStage" exists with ANY value, because no value was supplied in the request.

Header Parameters

Authorizationstring Required

Authorization token.

Content-Typestring

Type of the data being sent in the request or the data that is expected in the response. Supports application/json.

Query Parameters

localestring

Path Parameters

Nullable:

True

1
2
3

curl --location --globoff 'https://pm.mypreferences.com/Profiles/v4/{clientId}/Programs/IncludeMatching' \
--header 'Authorization: string' \
--header 'Content-Type: application/json'

{
  "Programs": [
    {
      "Link": 1,
      "ID": "sample string 2",
      "Name": "sample string 3",
      "Description": "sample string 4",
      "DefaultLocaleID": "sample string 5",
      "ProgramType": "sample string 6",
      "DisplayOrder": 7,
      "CustomProperties": [
        {
          "Link": 1,
          "Key": "sample string 2",
          "Value": "sample string 3"
        }
      ],
      "Locales": [
        {
          "ID": "sample string 1",
          "DisplayTags": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ]
        }
      ],
      "Filters": [
        {
          "Link": 1,
          "ChannelID": "sample string 2",
          "ProgramID": "sample string 3",
          "ID": "sample string 4",
          "Name": "sample string 5",
          "Description": "sample string 6",
          "DefaultPreferenceValue": 7,
          "DefaultLocaleID": "sample string 7",
          "CustomProperties": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ],
          "Locales": [
            {
              "ID": "sample string 1",
              "DisplayTags": [
                {
                  "Link": "0",
                  "Key": "sample string 2",
                  "Value": "sample string 3"
                }
              ]
            }
          ],
          "FrequencyLocales": [
            {
              "ID": "sample string 1",
              "Frequencies": [
                {
                  "ID": "sample string 1",
                  "DisplayName": "sample string 2",
                  "Description": "sample string 3",
                  "IsDefault": true,
                  "DisplayOrder": "0"
                }
              ]
            }
          ],
          "Attributes": [
            {
              "Link": null,
              "ID": "",
              "AttributeType": "",
              "DisplayOrder": null,
              "IsRequired": false,
              "AttributeConstraints": [
                {
                  "ConstraintType": "",
                  "Detail": ""
                }
              ],
              "DisplayTextLocales": [
                {
                  "Locale": "",
                  "Name": "",
                  "Description": ""
                }
              ]
            }
          ],
          "RequiredPreferenceConsents": [
            {
              "TypeName": "",
              "DisplayOrder": null
            }
          ]
        }
      ]
    }
  ]
}

This method allows you to retrieve a specific set of programs that match the custom property criteria specified as query parameters in your request.

It returns all programs that match on the custom property criteria specified in the request, and includes all the filters irrespective of their match against the same custom property criteria.

What are custom properties?

Custom Properties are a collection of key-value pairs that can be attached to Program Groups, Programs, and Filters. The key is the name of the property and the value is the content.

While the actual customer data, such as their choices, consents, preferences, etc. helps you deliver an individualized experience, custom properties allow you to personalize it for specific audience segments. For example, a first time visitor may want to see options related to onboarding, whereas an existing customer might get a highly personalized experience.

You can define as many of these key-value pairs to support any level of specializations ranging from micro experiences to comprehensive preference centers and everything in between.

Example:

https://{Base URL}/{client_id}/Programs/IncludeMatching?Jurisdication=EU&OnlineOnly=True&LifeCycleStage

In this example, the API will return all programs that match the custom property criteria specified below. It returns all Filters even if they do not contain the specified custom property criteria.

"Jurisdiction" = EU,
"OnlineOnly" = True,
"LifeCycleStage" exists with ANY value, because no value was supplied in the request.

Header Parameters

Authorizationstring Required

Authorization token.

Content-Typestring

Type of the data being sent in the request or the data that is expected in the response. Supports application/json.

Path Parameters

Nullable:

True

1
2
3

curl --location --globoff 'https://pm.mypreferences.com/Profiles/v4/{clientId}/Programs/IncludeAll' \
--header 'Authorization: string' \
--header 'Content-Type: application/json'

{
  "Programs": [
    {
      "Link": 1,
      "ID": "sample string 2",
      "Name": "sample string 3",
      "Description": "sample string 4",
      "DefaultLocaleID": "sample string 5",
      "ProgramType": "sample string 6",
      "DisplayOrder": 7,
      "CustomProperties": [
        {
          "Link": 1,
          "Key": "sample string 2",
          "Value": "sample string 3"
        }
      ],
      "Locales": [
        {
          "ID": "sample string 1",
          "DisplayTags": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ]
        }
      ],
      "Filters": [
        {
          "Link": 1,
          "ChannelID": "sample string 2",
          "ProgramID": "sample string 3",
          "ID": "sample string 4",
          "Name": "sample string 5",
          "Description": "sample string 6",
          "DefaultPreferenceValue": 7,
          "DefaultLocaleID": "sample string 7",
          "CustomProperties": [
            {
              "Link": 1,
              "Key": "sample string 2",
              "Value": "sample string 3"
            }
          ],
          "Locales": [
            {
              "ID": "sample string 1",
              "DisplayTags": [
                {
                  "Link": "0",
                  "Key": "sample string 2",
                  "Value": "sample string 3"
                }
              ]
            }
          ],
          "FrequencyLocales": [
            {
              "ID": "sample string 1",
              "Frequencies": [
                {
                  "ID": "sample string 1",
                  "DisplayName": "sample string 2",
                  "Description": "sample string 3",
                  "IsDefault": true,
                  "DisplayOrder": "0"
                }
              ]
            }
          ],
          "Attributes": [
            {
              "Link": null,
              "ID": "",
              "AttributeType": "",
              "DisplayOrder": null,
              "IsRequired": false,
              "AttributeConstraints": [
                {
                  "constraintType": "",
                  "detail": ""
                }
              ],
              "DisplayTextLocales": [
                {
                  "Locale": "",
                  "Name": "",
                  "Description": ""
                }
              ]
            }
          ],
          "RequiredPreferenceConsents": [
            {
              "TypeName": "",
              "DisplayOrder": null
            }
          ]
        }
      ]
    }
  ]
}

Programs contain Filters, which are channel-specific containers of preferences and preference-related data. They represent the enabling of a communication channel for a program. Each filter is unique and holds preference data and configuration settings for a specific channel within a program.

Each Filter is required to be associated with a Channel Type. Supported channel types are Phone, Text/SMS, Email, Mail, and Solicit. Preferences set for contact channels require a contact element (e.g., phone number, email address, mailing address) available on a user’s profile.

The Solicit channel represents any ID-based channel such as a social media app or an IoT device. Preferences stored for an ID-based channel are stored against the Customer Type associated with the user’s profile.

To create and manage filters, log into MyPreferences and click Filters under the Orchestrate menu.

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.

Production:

https://pm.mypreferences.com/Profiles/v4

Sandbox:

https://pmstg.mypreferences.com/Profiles/v4

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.

Production:

https://pm.mypreferences.com/Profiles/v4

Sandbox:

https://pmstg.mypreferences.com/Profiles/v4

Sections

Overview

Using API's

API Categorization

Data Categorization

Profiles

Preferences

Consents

Language Box

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

Experience API

What made this section unhelpful for you?

Endpoints

POST

GET

GET

PATCH

POST

GET

PATCH

POST

GET

PATCH

POST

GET

PATCH

POST

PATCH

GET

POST

GET

PATCH

POST

GET

POST

GET

POST

GET

POST

GET

GET

GET

PATCH

PATCH

PATCH

PATCH

POST

GET

GET

PATCH

POST

POST

GET

PATCH

GET

DELETE

GET

GET

GET

GET

GET

GET

GET

GET

GET

GET

GET

What made this section unhelpful for you?

Profile Configuration

What made this section unhelpful for you?

Consents

Contact Types

Contact Element Types

Response

Response

Response

Response