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.
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
What made this section unhelpful for you?
Create datetime custom fields
Add one or more custom fields of type datetime to capture date and/or time values on 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 meta data describing the requirements for collecting DateTime data in a custom field.
Show child attributes
Response
Response Attributes
A collection of Meta data describing the requirements for collecting DateTime data in a custom field.
Show child attributes
What made this section unhelpful for you?
Response
{
"DateTimeFields": [
{
"MinDate": "sample string 1",
"MaxDate": "sample string 2",
"DefaultValue": "sample string 3",
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"Name": "sample string 4",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 5",
"UpdateRuleId": 4,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
]
}What made this section unhelpful for you?
Retrieve datetime custom fields
This method allows you to retrieve a specific custom field or all custom fields of type datetime. Use the optional query parameter locale to only retrieve the collection of localized fields for a specific locale across all custom fields. If none of the custom fields 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 custom DateTime field Id. If specified, only the custom DateTime field with this Id will be returned. Default value is 0.
Optional locale. If specified, only custom DateTime fields associated with the locale are returned.
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 Meta data describing the requirements for collecting DateTime data in a custom field.
Show child attributes
What made this section unhelpful for you?
Response
{
"DateTimeFields": [
{
"MinDate": "sample string 1",
"MaxDate": "sample string 2",
"DefaultValue": "sample string 3",
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"Name": "sample string 4",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 5",
"UpdateRuleId": 4,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
]
}What made this section unhelpful for you?
Create numeric custom fields
Add one or more custom fields of type numeric to capture numeric values on 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 Meta data describing the requirements for collecting numeric data in a custom field.
Show child attributes
Response
Response Attributes
A collection of Meta data describing the requirements for collecting numeric data in a custom field.
Show child attributes
What made this section unhelpful for you?
Response
{
"NumericFields": [
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"MinValue": 2.1,
"MaxValue": 3.1,
"DecimalPlaces": 1,
"DefaultValue": 1.1,
"FieldMask": "sample string 1",
"Name": "sample string 2",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 3",
"UpdateRuleId": 2,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
]
}What made this section unhelpful for you?
Retrieve numeric custom fields
This method allows you to retrieve a specific custom field or all custom fields of type numeric. Use the optional query parameter locale to only retrieve the collection of localized fields for a specific locale across all custom fields. If none of the custom fields 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 custom Numeric field Id. If specified, only the custom Numeric field with this Id will be returned. Default value is 0.
Optional locale. If specified, only custom numeric fields associated with the locale are returned.
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 Meta data describing the requirements for collecting numeric data in a custom field.
Show child attributes
What made this section unhelpful for you?
Response
{
"NumericFields": [
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"MinValue": 2.1,
"MaxValue": 3.1,
"DecimalPlaces": 1,
"DefaultValue": 1.1,
"FieldMask": "sample string 1",
"Name": "sample string 2",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 3",
"UpdateRuleId": 2,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
]
}What made this section unhelpful for you?
Create selectlist custom fields
Add one or more custom fields of type SelectList to create interactive experiences where users can select one or more items from a predefined list. You must have at least one picklist created that you can associate with the SelectList custom field.
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 Meta data describing the requirements for collecting single select/radio button, multi-select/checkbox data in a custom field.
Show child attributes
Response
Response Attributes
A collection of Meta data describing the requirements for collecting alphanumeric data in a custom field.
Show child attributes
What made this section unhelpful for you?
Response
{
"TextFields": [
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"MinLength": 1,
"MaxLength": 1,
"DefaultValue": "sample string 1",
"RegEx": "sample string 2",
"FieldMask": "sample string 3",
"Name": "sample string 4",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 5",
"UpdateRuleId": 5,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
]
}What made this section unhelpful for you?
Retrieve selectlist custom fields
This method allows you to retrieve a specific custom field or all custom fields of type SelectList. Use the optional query parameter locale to only retrieve the collection of localized fields for a specific locale across all custom fields. If none of the custom fields 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 custom SelectList field Id. If specified, only the custom SelectList field with this Id will be returned. Default value is 0.
Optional locale. If specified, only custom select list fields associated with the locale are returned.
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 Meta data describing the requirements for collecting single select/radio button, multi-select/checkbox data in a custom field.
Show child attributes
What made this section unhelpful for you?
Response
{
"SelectListFields": [
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"PicklistId": 214,
"DisplayType": 6,
"DefaultState": 0,
"Name": "sample string 1",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 2",
"UpdateRuleId": 5,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
]
}What made this section unhelpful for you?
Create text custom fields
Add one or more custom fields of type text to capture text data on 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 Meta data describing the requirements for collecting alphanumeric data in a custom field.
Show child attributes
Response
Response Attributes
A collection of Meta data describing the requirements for collecting alphanumeric data in a custom field.
Show child attributes
What made this section unhelpful for you?
Response
{
"TextFields": [
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"MinLength": 1,
"MaxLength": 1,
"DefaultValue": "sample string 1",
"RegEx": "sample string 2",
"FieldMask": "sample string 3",
"Name": "sample string 4",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 5",
"UpdateRuleId": 5,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
]
}What made this section unhelpful for you?
Retrieve text custom fields
This method allows you to retrieve a specific custom field or all custom fields of type Text. Use the optional query parameter locale to only retrieve the collection of localized fields for a specific locale across all custom fields. If none of the custom fields 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 custom Text field Id. If specified, only the custom text field with this Id will be returned. Default value is 0.
Optional locale. If specified, only custom text fields associated with the locale are returned.
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 Meta data describing the requirements for collecting alphanumeric data in a custom field.
Show child attributes
What made this section unhelpful for you?
Response
{
"TextFields": [
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"MinLength": 1,
"MaxLength": 1,
"DefaultValue": "sample string 1",
"RegEx": "sample string 2",
"FieldMask": "sample string 3",
"Name": "sample string 4",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 5",
"UpdateRuleId": 5,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
]
}What made this section unhelpful for you?
Retrieve update rules
This method will retrieve all update rules that can be applied on a custom field.
Update rules specify how MyPreferences should update custom field values when adding or updating profiles. If you don't specify an update rule when creating a custom field, it defaults to always.
The following update rules are available:
• 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 edited
Header Parameters
Authorization token
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 Update Rules that can be associated with a Profile.
Show child attributes
What made this section unhelpful for you?
Response
{
"UpdateRules": [
{
"Id": 1,
"Name": "1"
}
]
}What made this section unhelpful for you?
Retrieve custom fields
This method allows you to retrieve a specific custom field or all custom fields irrespective of their type. Use the optional query parameter locale to only retrieve the collection of localized fields for a specific locale across all custom fields. If none of the custom fields 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 custom field Id. If specified, only the custom field with this Id will be returned. Default value is 0.
Optional locale. If specified, only custom fields associated with the locale are returned.
Path Parameters
This is your organization’s MyPreferences Account Id. A 404 is returned if this value is invalid.
Response
Response Attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
What made this section unhelpful for you?
Response
{
"DateTimeFields": [
{
"MinDate": "sample string 1",
"MaxDate": "sample string 2",
"DefaultValue": "sample string 3",
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"Name": "sample string 4",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 5",
"UpdateRuleId": 4,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
],
"NumericFields": [
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"MinValue": 2.1,
"MaxValue": 3.1,
"DecimalPlaces": 1,
"DefaultValue": 1.1,
"FieldMask": "sample string 1",
"Name": "sample string 2",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 3",
"UpdateRuleId": 2,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
],
"SelectListFields": [
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"PicklistId": 214,
"DisplayType": 6,
"DefaultState": 0,
"Name": "sample string 1",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 2",
"UpdateRuleId": 5,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
],
"TextFields": [
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"MinLength": 1,
"MaxLength": 1,
"DefaultValue": "sample string 1",
"RegEx": "sample string 2",
"FieldMask": "sample string 3",
"Name": "sample string 4",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 5",
"UpdateRuleId": 5,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}
]
}What made this section unhelpful for you?
Update datetime custom field
This method allows you to update a single custom field of type DateTime by providing the corresponding Id 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.
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 Custom field 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
Minimum date supported by the field.
Maximum value supported by the field.
The default value of the field.
Id of the field (Read-Only).
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
The name of the field.
Localized display names of the field.
Show child attributes
The description of the field.
Id associated with the update rule.
[object Object][object Object][object Object][object Object]Determines the display order of the field on customer-facing user interfaces.
Determines whether the custom field is required when creating or replacing a profile. When set to TRUE, the field cannot be removed from the profile.
Allows custom fields to exist with a blank value on a profile. When set to FALSE, the custom field must be accompanied by a non-blank value when adding or updating a profile. This property works together with UpdateRules.
Indicates the status of the field.
What made this section unhelpful for you?
Response
{
"MinDate": "sample string 1",
"MaxDate": "sample string 2",
"DefaultValue": "sample string 3",
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"Name": "sample string 4",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 5",
"UpdateRuleId": 4,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}What made this section unhelpful for you?
Update numeric custom field
This method allows you to update a single custom field of type Numeric by providing the corresponding Id 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 Custom field 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
Id of the field (Read-Only).
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
Read-only system fields returned as part of an API response. These are updated automatically when a profile is created or modified.
Maximum value supported by the field.
Minimum value supported by the field.
The default value of the field.
Stores the field's input mask definition. It will be used to drive data collection on a UI.
The name of the field.
Localized display names of the field.
Show child attributes
The description of the field.
Id associated with the update rule. 1: The value can be added, changed, or cleared without restriction. 2: Once a value is added, the field becomes uneditable. It cannot be changed or cleared. 4: Once a value is added, it can be edited, but cannot be cleared. 5: Once added to a profile, the field immediately becomes uneditable. It cannot be changed or cleared.
[object Object][object Object][object Object][object Object]Determines the display order of the field on customer-facing user interfaces.
Determines whether the custom field is required when creating or replacing a profile. When set to TRUE, the field cannot be removed from the profile.
Allows custom fields to exist with a blank value on a profile. When set to FALSE, the custom field must be accompanied by a non-blank value when adding or updating a profile.
Indicates the status of the field.
What made this section unhelpful for you?
Response
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"MinValue": 2.1,
"MaxValue": 3.1,
"DecimalPlaces": 1,
"DefaultValue": 1.1,
"FieldMask": "sample string 1",
"Name": "sample string 2",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 3",
"UpdateRuleId": 2,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}What made this section unhelpful for you?
Update text custom field
This method allows you to update a single custom field of type Text by providing the corresponding Id 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 Custom field 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
Id of the field (Read-Only).
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
Minimum length supported by the field.
Maximum length supported by the field.
The default value of the field.
An optional regular expression that can be used to validate a field on update.
Stores the field's input mask definition. It will be used to drive data collection on a UI.
The name of the field.
Localized display names of the field.
Show child attributes
The description of the field.
Id associated with the update rule. 1: The value can be added, changed, or cleared without restriction. 2: Once a value is added, the field becomes uneditable. It cannot be changed or cleared. 4: Once a value is added, it can be edited, but cannot be cleared. 5: Once added to a profile, the field immediately becomes uneditable. It cannot be changed or cleared.
[object Object][object Object][object Object][object Object]Determines the display order of the field on customer-facing user interfaces.Determines the display order of the field when driving preference collection touchpoints.
Determines whether the custom field is required when creating or replacing a profile. When set to TRUE, the field cannot be removed from the profile.
Allows custom fields to exist with a blank value on a profile. When set to FALSE, the custom field must be accompanied by a non-blank value when adding or updating a profile. This property works together with UpdateRules.
Indicates the status of the field.
What made this section unhelpful for you?
Response
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"MinLength": 1,
"MaxLength": 1,
"DefaultValue": "sample string 1",
"RegEx": "sample string 2",
"FieldMask": "sample string 3",
"Name": "sample string 4",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 5",
"UpdateRuleId": 5,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}What made this section unhelpful for you?
Update selectlist custom field
This method allows you to update a single custom field of type SelectList by providing the corresponding Id 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 Custom field 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
Id of the field (Read-Only).
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
The Id of the associated picklist.
Custom field's display type.
[object Object][object Object][object Object][object Object][object Object][object Object][object Object]The default state of the checkbox.
[object Object][object Object]The name of the field.
Localized display names of the field.
Show child attributes
The description of the field.
Id associated with the update rule. 1: The value can be added, changed, or cleared without restriction. 2: Once a value is added, the field becomes uneditable. It cannot be changed or cleared. 4: Once a value is added, it can be edited, but cannot be cleared. 5: Once added to a profile, the field immediately becomes uneditable. It cannot be changed or cleared.
[object Object][object Object][object Object][object Object]Determines the display order of the field on customer-facing user interfaces.
Determines whether the custom field is required when creating or replacing a profile. When set to TRUE, the field cannot be removed from the profile.
Allows custom fields to exist with a blank value on a profile. When set to FALSE, the custom field must be accompanied by a non-blank value when adding or updating a profile. This property works together with UpdateRules.
Indicates the status of the field.
What made this section unhelpful for you?
Response
{
"Id": 1,
"Edited": {
"CreateDate": "sample string 1",
"CreatedBy": "sample string 2",
"ModifiedDate": "sample string 3",
"ModifiedBy": "sample string 4"
},
"PicklistId": 214,
"DisplayType": 6,
"DefaultState": 0,
"Name": "sample string 1",
"LocalizedDisplayNames": [
{
"Locale": "en_US",
"DisplayName": "sample string 1",
"ToolTipText": "sample string 2"
}
],
"Description": "sample string 2",
"UpdateRuleId": 5,
"DisplayOrder": 1,
"IsRequired": true,
"AllowBlanks": true,
"IsActive": true
}What made this section unhelpful for you?
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