Overview
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.
Base URL
Production:
https://pm.mypreferences.com/Profiles/v4
Sandbox:
https://pmstg.mypreferences.com/Profiles/v4
Experience API
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
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
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.
What made this section unhelpful for you?
Consents
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
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.
What made this section unhelpful for you?
Create address type
Add one or more address types to associate postal addresses with profiles. These address types allow you to to link specific preferences and consents to each postal address.
Header Parameters
Authorization token
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Body Parameters
A collection of metadata describing type information for an Address that can be associated with a Profile.
Show child attributes
Response
Response Attributes
A collection of meta data describing type information for an Address that can be associated with a Profile.
Show child attributes
What made this section unhelpful for you?
Response
{
"AddressTypes": [
{
"TypeName": "Primary",
"IsDefault": false,
"IsActive": false,
"TypeId": 1,
"RequiredContactConsents": [
{
"TypeName": "Data Processing Consent",
"DisplayOrder": "1",
"RequireGrantedOrNotSetOnAdd": true
}
],
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "Primary",
"Description": ""
}
],
"Edited": {
"CreateDate": "2024-06-13T11:46:12.000Z",
"CreatedBy": "John.Doe",
"ModifiedDate": "2024-06-13T11:46:12.000Z",
"ModifiedBy": "John.Doe"
}
}
]
}What made this section unhelpful for you?
Retrieve address types
This method allows you to retrieve a specific address type or all address types. Use the optional query parameter locale to only retrieve the collection of localized fields for a specific locale across all Types. If none of the Types have a localized field collection for the specified locale, the HTTP status code of 404-Not Found is returned.
Header Parameters
Authorization token
Query Parameters
Optional Type Id. If specified, only the Type with this Id will be returned. Default value is 0.
A valid locale associated with the AddressType. Ex: “en”, “en-us”, “en-uk”, “fr-ca”.
Path Parameters
This is your organization’s MyPreferences account Id. A 404 is returned if this value is invalid.
What made this section unhelpful for you?
Response
{
"AddressTypes": [
{
"TypeName": "Primary",
"IsDefault": false,
"IsActive": false,
"TypeId": 1,
"RequiredContactConsents": [
{
"TypeName": "Data Processing Consent",
"DisplayOrder": "1",
"RequireGrantedOrNotSetOnAdd": false
}
],
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "Primary",
"Description": ""
}
],
"Edited": {
"CreateDate": "2024-06-13T11:46:12.000Z",
"CreatedBy": "John.Doe",
"ModifiedDate": "2024-06-13T11:46:12.000Z",
"ModifiedBy": "John.Doe"
}
}
]
}What made this section unhelpful for you?
Update address type
This method allows you to update a single address type by providing the corresponding TypeId parameter.
The HTTP PATCH request method applies partial modifications to a resource. Click here to learn about using PATCH.
The MyPreferences API supports add, replace, remove, and test PATCH operations. The API does not support move and copy PATCH operations.
In the JSON body of your request, send the op, path, and value parameters:
- op denotes the type of operation to execute such as
add,replace,remove, ortest. path denotes the path of the target location on the resource to update.
- value denotes the value to apply.
- from JSON pointer to the location to copy or move.
Note: When removing multiple elements from an array object, send the remove operations in descending order to keep the indices intact.
Header Parameters
Authorization token
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Id of the AlternatIdType to update.
Body Parameters
Operation to be performed on the target object. Valid values are: add/remove/replace/test.
JSON pointer that references a location within the target document where the operation is performed.
JSON pointer to the location to copy or move.
Value to be added or replaced.
Response
Response Attributes
The name given to the type.
A collection of a locale specific name/value pair of Strings used to support localization.
Show child attributes
Determines if it is the Default Type.
Defines whether the item is Active or Inactive.
A read-only field that uniquely identifies the Type.
Read-only system fields returned as part of an API response. These are updated automatically when a profile is created or modified.
Show child attributes
Collection of required consents on the contact.
Show child attributes
What made this section unhelpful for you?
Response
{
"TypeName": "sample string 1",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "sample string 1",
"Description": "sample string 2"
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"RequiredContactConsents": [
{
"TypeName": "Data Processing Consent",
"DisplayOrder": "1",
"RequireGrantedOrNotSetOnAdd": false
}
]
}What made this section unhelpful for you?
Create alternate Id types
Add one or more alternate Id types which can be used for adding additional identifiers on a profile. ID values associated with these types must be unique for a type across all profiles.
Header Parameters
Authorization token
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Body Parameters
A collection of Additional unique identifiers that can be associated with a profile. For example, customer identifiers from other applications such as Salesforce, Marketo or Facebook can be stored as AlternateIds.
Show child attributes
Response
Response Attributes
A collection of Additional unique identifiers that can be associated with a profile. For example, customer identifiers from other applications such as Salesforce, Marketo or Facebook can be stored as AlternateIds.
Show child attributes
What made this section unhelpful for you?
Response
{
"AlternateIdTypes": [
{
"TypeName": "sample string 1",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "sample string 1",
"Description": "sample string 2"
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
}
}
]
}What made this section unhelpful for you?
Retrieve alternate Id types
This method allows you to retrieve a specific Alternate ID type or all Alternate Id types. Use the optional query parameter locale to only retrieve the collection of localized fields for a specific locale across all Types. If none of the Types have a localized field collection for the specified locale, the HTTP status code of 404-Not Found is returned.
Header Parameters
Authorization token
Query Parameters
Optional Type Id. If specified, only the Type with this Id will be returned. Default value is 0.
A valid locale associated with the AlternateIdType. Ex: “en”, “en-us”, “en-uk”, “fr-ca”.
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Response
Response Attributes
A collection of Additional unique identifiers that can be associated with a profile. For example, customer identifiers from other applications such as Salesforce, Marketo or Facebook can be stored as AlternateIds.
Show child attributes
What made this section unhelpful for you?
Response
{
"AlternateIdTypes": [
{
"TypeName": "sample string 1",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "sample string 1",
"Description": "sample string 2"
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
}
}
]
}What made this section unhelpful for you?
Update alternate Id type
This method allows you to update a single alternate Id by providing the corresponding TypeId parameter.
The HTTP PATCH request method applies partial modifications to a resource. Click here to learn about using PATCH.
The MyPreferences API supports add, replace, remove, and test PATCH operations. The API does not support move and copy PATCH operations.
In the JSON body of your request, send the op, path, and value parameters:
op denotes the type of operation to execute such as add, replace, remove, or test.
path denotes the path of the target location on the resource to update.
- value denotes the value to apply.
Note: When removing multiple elements from an array object, send the remove operations in descending order to keep the indices intact.
Header Parameters
Authorization token
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Id of the AlternateIdType to update.
Body Parameters
Operation to be performed on the target object. Valid values are: add/remove/replace/test.
JSON pointer that references a location within the target document where the operation is performed.
JSON pointer to the location to copy or move.
Value to be added or replaced.
Response
Response Attributes
The name given to the type.
A collection of a locale specific name/value pair of Strings used to support localization.
Show child attributes
Determines if it is the Default Type.
Defines whether the item is Active or Inactive.
A read-only field that uniquely identifies the Type.
Read-only system fields returned as part of an API response. These are updated automatically when a profile is created or modified.
Show child attributes
What made this section unhelpful for you?
Response
{
"TypeName": "sample string 1",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "sample string 1",
"Description": "sample string 2"
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
}
}What made this section unhelpful for you?
Create customer types
Add one or more customer types that can be assigned to profiles. The CustomerType is a required element on ever profile, and each profile will only have a single customer type. Any preferences stored in a profile that are not associated with a Contact Element Type are linked to the CustomerType.
Header Parameters
Authorization token
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Body Parameters
A collection of Customer Types that can be associated with a Profile.
Show child attributes
Response
Response Attributes
A collection of Customer Types that can be associated with a Profile.
Show child attributes
What made this section unhelpful for you?
Response
{
"CustomerTypes": [
{
"TypeName": "sample string 1",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "sample string 1",
"Description": "sample string 2"
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
}
}
]
}What made this section unhelpful for you?
Retrieve customer types
This method allows you to retrieve a specific customer type or all customer types. Use the optional query parameter locale to only retrieve the collection of localized fields for a specific locale across all Types. If none of the Types have a localized field collection for the specified locale, the HTTP status code of 404-Not Found is returned.
Header Parameters
Authorization token
Query Parameters
Optional Type Id. If specified, only the Type with this Id will be returned. Default value is 0.
A valid locale associated with the CustomerType. Ex: “en”, “en-us”, “en-uk”, “fr-ca”.
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Response
Response Attributes
A collection of Customer Types that can be associated with a Profile.
Show child attributes
What made this section unhelpful for you?
Response
{
"CustomerTypes": [
{
"TypeName": "sample string 1",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "sample string 1",
"Description": "sample string 2"
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
}
}
]
}What made this section unhelpful for you?
Update customer type
This method allows you to update a single customer type by providing the corresponding TypeId parameter.
The HTTP PATCH request method applies partial modifications to a resource. Click here to learn about using PATCH.
The MyPreferences API supports add, replace, remove, and test PATCH operations. The API does not support move and copy PATCH operations.In the JSON body of your request, send the op, path, and value parameters:
op denotes the type of operation to execute such as add, replace, remove, or test.
path denotes the path of the target location on the resource to update.
- value denotes the value to apply.
Note: When removing multiple elements from an array object, send the remove operations in descending order to keep the indices intact.
Header Parameters
Authorization token
Indicates the data format of the request body.
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Id of the CustomerType to update.
Body Parameters
Operation to be performed on the target object. Valid values are: add/remove/replace/test.
JSON pointer that references a location within the target document where the operation is performed.
JSON pointer to the location to copy or move.
Value to be added or replaced.
Response
Response Attributes
The name given to the type.
A collection of a locale specific name/value pair of Strings used to support localization.
Show child attributes
Determines if it is the Default Type.
Defines whether the item is Active or Inactive.
A read-only field that uniquely identifies the Type.
Read-only system fields returned as part of an API response. These are updated automatically when a profile is created or modified.
Show child attributes
What made this section unhelpful for you?
Response
{
"TypeName": "sample string 1",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "sample string 1",
"Description": "sample string 2"
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
}
}What made this section unhelpful for you?
Create email types
Add one or more email types to associate email addresses on profiles. These email types allow you to link specific preferences and consents to each email address.
Header Parameters
Authorization token
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Body Parameters
A collection of Email Types that can be associated with a Profile.
Show child attributes
Response
Response Attributes
A collection of Email Types that can be associated with a Profile.
Show child attributes
What made this section unhelpful for you?
Response
{
"EmailTypes": [
{
"TypeName": "Primary",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "Primary",
"Description": ""
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "2024-06-13T11:46:12.000Z",
"CreatedBy": "John.Doe",
"ModifiedDate": "2024-06-13T11:46:12.000Z",
"ModifiedBy": "John.Doe"
},
"RequiredContactConsents": [
{
"TypeName": "Data Processing Consent",
"DisplayOrder": "1",
"RequireGrantedOrNotSetOnAdd": false
}
]
}
]
}What made this section unhelpful for you?
Update email type
This method allows you to update a single email type by providing the corresponding TypeId parameter.
The HTTP PATCH request method applies partial modifications to a resource. Click here to learn about using PATCH.
The MyPreferences API supports add, replace, remove, and test PATCH operations. The API does not support move and copy PATCH operations. In the JSON body of your request, send the op, path, and value parameters:
op denotes the type of operation to execute such as add, replace, remove, or test.
path denotes the path of the target location on the resource to update.
- value denotes the value to apply.
Note: When removing multiple elements from an array object, send the remove operations in descending order to keep the indices intact.
Header Parameters
Authorization token
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Id of the EmailType to update.
Body Parameters
Operation to be performed on the target object. Valid values are: add/remove/replace/test.
JSON pointer that references a location within the target document where the operation is performed.
JSON pointer to the location to copy or move.
Value to be added or replaced.
Response
Response Attributes
The name given to the type.
A collection of a locale specific name/value pair of Strings used to support localization.
Show child attributes
Determines if it is the Default Type.
Defines whether the item is Active or Inactive.
A read-only field that uniquely identifies the Type.
Read-only system fields returned as part of an API response. These are updated automatically when a profile is created or modified.
Show child attributes
Collection of required consents on the contact.
Show child attributes
What made this section unhelpful for you?
Response
{
"TypeName": "Data Processing Consent",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "Primary",
"Description": "sample string 2"
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "2024-06-13T11:46:12.000Z",
"CreatedBy": "John.Doe",
"ModifiedDate": "2024-06-13T11:46:12.000Z",
"ModifiedBy": "John.Doe"
},
"RequiredContactConsents": [
{
"TypeName": "Data Processing Consent",
"DisplayOrder": "1",
"RequireGrantedOrNotSetOnAdd": false
}
]
}What made this section unhelpful for you?
Retrieve email types
This method allows you to retrieve a specific email type or all email types. Use the optional query parameter locale to only retrieve the collection of localized fields for a specific locale across all Types. If none of the Types have a localized field collection for the specified locale, the HTTP status code of 404-Not Found is returned.
Header Parameters
Authorization token
Query Parameters
Optional Type Id. If specified, only the Type with this Id will be returned. Default value is 0.
A valid locale associated with the EmailType. Ex: “en”, “en-us”, “en-uk”, “fr-ca”.
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Response
Response Attributes
A collection of Email Types that can be associated with a Profile.
Show child attributes
What made this section unhelpful for you?
Response
{
"EmailTypes": [
{
"TypeName": "Primary",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "Primary",
"Description": ""
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "2024-06-13T11:46:12.000Z",
"CreatedBy": "John.Doe",
"ModifiedDate": "2024-06-13T11:46:12.000Z",
"ModifiedBy": "John.Doe"
},
"RequiredContactConsents": [
{
"TypeName": "Data Processing Consent",
"DisplayOrder": "1",
"RequireGrantedOrNotSetOnAdd": false
}
]
}
]
}What made this section unhelpful for you?
Create phone types
Add one or more phone types to associate phone numbers on profiles. These phone types allows you to to link specific preferences and consents to each phone number.
Header Parameters
Authorization token
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Body Parameters
A collection of Phone Types that can be associated with a Profile.
Show child attributes
Response
Response Attributes
A collection of Phone Types that can be associated with a Profile.
Show child attributes
What made this section unhelpful for you?
Response
{
"PhoneTypes": [
{
"TypeName": "Primary",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "Primary",
"Description": ""
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "2024-06-13T11:46:12.000Z",
"CreatedBy": "John.Doe",
"ModifiedDate": "2024-06-13T11:46:12.000Z",
"ModifiedBy": "John.Doe"
},
"RequiredContactConsents": [
{
"TypeName": "Data Processing Consent",
"DisplayOrder": "1",
"RequireGrantedOrNotSetOnAdd": false
}
]
}
]
}What made this section unhelpful for you?
Retrieve phone types
This method allows you to retrieve a specific phone type or all phone types. Use the optional query parameter locale to only retrieve the collection of localized fields for a specific locale across all Types. If none of the Types have a localized field collection for the specified locale, the HTTP status code of 404-Not Found is returned.
Header Parameters
Authorization token
Query Parameters
Optional Type Id. If specified, only the Type with this Id will be returned. Default value is 0.
A valid locale associated with the PhoneType. Ex: “en”, “en-us”, “en-uk”, “fr-ca”.
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Response
Response Attributes
A collection of Phone Types that can be associated with a Profile.
Show child attributes
What made this section unhelpful for you?
Response
{
"PhoneTypes": [
{
"TypeName": "Primary",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "Primary",
"Description": ""
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "2024-06-13T11:46:12.000Z",
"CreatedBy": "John.Doe",
"ModifiedDate": "2024-06-13T11:46:12.000Z",
"ModifiedBy": "John.Doe"
},
"RequiredContactConsents": [
{
"TypeName": "Data Processing Consent",
"DisplayOrder": "1",
"RequireGrantedOrNotSetOnAdd": false
}
]
}
]
}What made this section unhelpful for you?
Update phone type
This method allows you to update a single PhoneType specified by the TypeId parameter.
The HTTP PATCH request method applies partial modifications to a resource. Click here to learn about using PATCH.
The MyPreferences API supports add, replace, remove, and test PATCH operations. The API does not support move and copy PATCH operations. In the JSON body of your request, send the op, path, and value parameters:
op denotes the type of operation to execute such as add, replace, remove, or test.
path denotes the path of the target location on the resource to update.
- value denotes the value to apply.
Note: When removing multiple elements from an array object, send the remove operations in descending order to keep the indices intact.
Header Parameters
authorization token
application/json
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Id of the PhoneType to update.
Body Parameters
Operation to be performed on the target object. Valid values are: add/remove/replace/test.
JSON pointer that references a location within the target document where the operation is performed.
JSON pointer to the location to copy or move.
Value to be added or replaced.
Response
Response Attributes
The name given to the type.
A collection of a locale specific name/value pair of Strings used to support localization.
Show child attributes
Determines if it is the Default Type.
Defines whether the item is Active or Inactive.
A read-only field that uniquely identifies the Type.
Read-only system fields returned as part of an API response. These are updated automatically when a profile is created or modified.
Show child attributes
Show child attributes
What made this section unhelpful for you?
Response
{
"TypeName": "sample string 1",
"LocalizedFields": [
{
"Locale": "en_US",
"Name": "sample string 1",
"Description": "sample string 2"
}
],
"IsDefault": true,
"IsActive": true,
"TypeId": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"RequiredContactConsents": [
{
"TypeName": "Data Processing Consent",
"DisplayOrder": "1",
"RequireGrantedOrNotSetOnAdd": false
}
]
}What made this section unhelpful for you?
Custom Fields
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
Groups
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
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
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
Preference Configuration
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.
What made this section unhelpful for you?
Program Groups
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.
Programs
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
Filters
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.
Data API
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.
Base URL
Production:
https://pm.mypreferences.com/Profiles/v4
Sandbox:
https://pmstg.mypreferences.com/Profiles/v4
Integration API
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.
Base URL
Production:
https://pm.mypreferences.com/Profiles/v4
Sandbox:
https://pmstg.mypreferences.com/Profiles/v4