MyPreferences API

Introduction

MyPreferences Application API is a powerful and efficient RESTful Webservices library for interacting with MyPreferences. It provides you with complete access to your configuration and preference data enabling you to build bespoke preference management solutions for your customers and prospects.

See MyPreferences Bulk API Help page if you are interested in high-volume data exports and more.

Authorization

All of the API listed below require the proper authorization header in order to work.
Please see the Authorization documentation on how to generate the correct header.

MyPreferences Configuration API

The MyPreferences Configuration APIs allow you to retrieve configuration data with ease enabling you to deliver personalized customer experiences at every touchpoint. Using the Configuration API, you design preference management user interfaces that reflect your configuration changes dynamically, without any developer assistance.

APIDescription
GET {clientId}/Programs

Retrieve all Programs.
GET {clientId}/Programs/Locale/{locale}

Retrieve all Programs which only return text tags for the specified locale.
GET {clientId}/Programs/{programId}

Retrieve a Program.
GET {clientId}/Programs/{programId}/{programGroupId}

Retrieve a specific Program from a Program Group. This call will return the default preference values for the Filters as defined in the Program Group.
GET {clientId}/Programs/{programId}/{programGroupId}/Locale/{locale}

Retrieve a specific Program from a Program Group and only return text tags for the specified locale. This call will return the default preference values for the Filters as defined in the Program Group.
GET {clientId}/Programs/{programId}/Locale/{locale}

Retrieve a specific Program and only return text tags for the specified locale.
GET {clientId}/Programs/ProgramTypes/{programTypeId}

Retrieve all Programs that match the specified Program Type.
GET {clientId}/Programs/ProgramTypes/{programTypeId}/Locale/{locale}

Retrieve all Programs that match a specified Program Type and only return text tags for the specified locale.
GET {clientId}/Programs/IncludeMatching

Retrieve Programs and associated Filters that match on the specified custom property search criteria.
GET {clientId}/Programs/IncludeMatching/Locale/{locale}

Retrieve Programs and associated Filters that match on the specified custom property search criteria and only return text tags for the specified locale.
GET {clientId}/Programs/IncludeAll

Retrieve Programs that match on the specified custom property search criteria. All Filters within the Programs will be returned.
GET {clientId}/Programs/IncludeAll/Locale/{locale}

Retrieve Programs that match on the specified custom property search criteria and only return text tags for the specified locale. All Filters within the Programs will be returned.
APIDescription
GET {clientId}/ProgramGroup

Retrieve Program Groups.
GET {clientId}/ProgramGroup/Locale/{locale}

Retrieve all Program Groups and only return text tags for the specified locale.
GET {clientId}/ProgramGroup/{programGroupId}

Retrieve a Program Group, including any Child or Rollup program groups.
GET {clientId}/ProgramGroup/{programGroupId}/Locale/{locale}

Retrieve a Program Group and only return text tags for the specified locale.
GET {clientId}/ProgramGroup/IncludeMatching

Retrieve Program Groups and associated Nested Program Groups, Programs, and Filters that match on specified custom property search criteria.
GET {clientId}/ProgramGroup/IncludeMatching/Locale/{locale}

Retrieve Program Groups and associated Nested Program Groups, Programs, and Filters that match on specified custom property search criteria. This call will only return text tags for the specified locale.
GET {clientId}/ProgramGroup/IncludeAll

Retrieve Program Groups that match on specified custom property search criteria. All Programs, Filters and Nested Program Groups within the Program Groups will be returned.
GET {clientId}/ProgramGroup/IncludeAll/Locale/{locale}

Retrieve Program Groups that match on specified custom property search criteria and only return text tags for the specified locale. All Programs, Filters and Nested Program Groups within the Program Groups will be returned.
APIDescription
GET {clientId}/Filters/{filterId}

Retrieve a Filter.
GET {clientId}/Filters/{filterId}/Locale/{locale}

Retrieve a Filter and only return text tags for the specified locale.

MyPreferences Preference API

The Preference API is used in conjunction with the Configuration API allowing you to add and retrieve preferences of your customers and prospects across any touchpoint. Using the Preference API, you can retrieve expressed and implied preferences associated with an ID or a Contact Element across Channels.

Use the Merge API to merge preferences from one or more Preference Keys.

Use the Deactivate API to deactivate preferences for a preference key in a specific Filter or across all Filters within a channel.

APIDescription
GET {clientId}/Preferences/Attributes?attributes[0].Key={attributes[0].Key}&attributes[0].Value={attributes[0].Value}&attributes[1].Key={attributes[1].Key}&attributes[1].Value={attributes[1].Value}&channels[0]={channels[0]}&channels[1]={channels[1]}

Retrieve preferences that match the preference attributes specified in the request. Note: Preference Attributes associated with preferences added via Bulk Import can be searched after 1 hour of being processed.
GET {clientId}/Preferences/CID/{CID}?channels[0]={channels[0]}&channels[1]={channels[1]}

Retrieve preferences for a CID across one or more Channels.
GET {clientId}/Preferences/CID/{CID}/Program?ProgramIds[0]={ProgramIds[0]}&ProgramIds[1]={ProgramIds[1]}

Retrieve preferences for a CID across one or more Programs.
GET {clientId}/Preferences/CID/{CID}/Program/Implied?ProgramIds[0]={ProgramIds[0]}&ProgramIds[1]={ProgramIds[1]}

Retrieve implied and expressed preferences for a single CID and one or more Programs.
GET {clientId}/Preferences/Email/{email}

Retrieve preferences for an email address.
GET {clientId}/Preferences/Email?email={email}

Retrieve preferences for an email address.
GET {clientId}/Preferences/Mail?Address1={Address1}&City={City}&StateProvince={StateProvince}&PostalCode={PostalCode}&Address2={Address2}

Retrieve preferences for a mailing address.
GET {clientId}/Preferences/Phone/{phone}

Retrieve preferences for a phone number.
GET {clientId}/Preferences/Fax/{fax}

Retrieve preferences for fax number.
GET {clientId}/Preferences/SMS/{sms}

Retrieve preferences for a mobile number.
GET {clientId}/Preferences/CID/{CID}/Implied?channels[0]={channels[0]}&channels[1]={channels[1]}

Retrieve implied and expressed preferences for a CID across one or more Channels.
GET {clientId}/Preferences/Email/{email}/Implied

Retrieve implied and expressed preferences for an email address.
GET {clientId}/Preferences/Email/Implied?email={email}

Retrieve implied and expressed preferences for an email address.
GET {clientId}/Preferences/Mail/Implied?Address1={Address1}&City={City}&StateProvince={StateProvince}&PostalCode={PostalCode}&Address2={Address2}

Retrieves implied and expressed preferences for a mailing address.
GET {clientId}/Preferences/Phone/{phone}/Implied

Retrieves implied and expressed preferences for a phone number.
GET {clientId}/Preferences/Fax/{fax}/Implied

Retrieves implied and expressed preferences for a fax number.
GET {clientId}/Preferences/SMS/{sms}/Implied

Retrieves implied and expressed preferences for a mobile number.
POST {clientId}/Preferences

Add Preferences. This method allows you to submit multi-channel preference requests for a variety of preference options (Filters) across various programs.
POST {clientId}/Preferences/Program/{programId}

Add preferences across all Filters within a Program. Note: You can specify a Channel ID to restrict the preference updates to a specific channel.
POST {clientId}/Preferences/ProgramGroup/{programGroupId}

Add preferences across all Filters within Programs for a Program Group. Note: You can specify a Channel ID to restrict the preference updates to a specific channel.
PUT {clientId}/Preferences/Merge

Merge preferences from one or more preference keys to a new or an existing preference key. Note: This call is designed to support fuzzy matching. Therefore, the merge operation will combine preferences across all matching elements within a preference key. For example, if a preference key includes CID 111 and Email johndoe@example.com, the merge process will merge preferences across all preference keys that contains the CID, Email or both, and associates it with the survivor preference key. Please request the Merge API Help Documentation for more details.
PUT {clientId}/Preferences/Deactivate

Deactivate a preference in a specific Filter or across all Filters within a specific channel.

MyPreferences Data Export API

The MyPreferences Data Export APIs allow you to retrieve data export data with ease enabling you to export and import data export configurations.

APIDescription
GET {clientId}/DataExport/Segments

Retrieve segments for all client segments
GET {clientId}/DataExport/Segments/{segmentName}

Retrieve segments for a segment ID.
GET {clientId}/DataExport/SegmentPermissions

Retrieve segmentPermisisons for all client segments
GET {clientId}/DataExport/SegmentPermissions/{segmentName}

Retrieve segmentPermissions for a segment ID.
GET {clientId}/DataExport/SegmentGroups

Retrieve segmentGroups for all client segment groups.
GET {clientId}/DataExport/SegmentGroups/{segmentGroupName}

Retrieve segmentGroups for a segmentGroup ID.
GET {clientId}/DataExport/SegmentGroupPermissions

Retrieve segmentGroupPermisisons for all client segment groups
GET {clientId}/DataExport/SegmentGroupPermissions/{segmentGroupName}

Retrieve segmentGroupPermissions for a segmentGroup ID.
GET {clientId}/DataExport/Folders

Retrieve segmentGroupPermisisons for all client segment groups
GET {clientId}/DataExport/Folders/{folderName}

Retrieve segmentGroupFolders for a segmentGroup ID.
GET {clientId}/DataExport/ExportSchedules

Retrieve exportSchedules for a exportSchedule ID.
GET {clientId}/DataExport/ExportSchedules/{exportScheduleName}

Retrieve exportSchedules for a exportSchedule ID.
POST {clientId}/DataExport/Segments

Add Segments.
POST {clientId}/DataExport/SegmentGroups

Add SegmentGroups.
POST {clientId}/DataExport/ExportSchedules

Add ExportSchedules.
POST {clientId}/DataExport/SegmentPermissions

Add Segment Permissions.
POST {clientId}/DataExport/SegmentGroupPermissions

Add SegmentGroup Permissions.
POST {clientId}/DataExport/Folders

Add SegmentGroup Folders.

MyPreferences Synchronization API

The Synchronization API is a purpose-built API that helps you easily promote your entire MyPreferences configuration from one account to another.

The order of execution is important when using the Synchronization APIs. You must ensure the dependent objects are in place before you add a parent object. Click here to see the recommended order of execution when promoting configuration between two MyPreferences accounts.

APIDescription
GET {clientId}/Config/Attributes

Retrieve all Preference Attributes.
GET {clientId}/Config/CustomProperties

Retrieve all Custom Properties.
GET {clientId}/Config/DistributionLists

Retrieve all Distribution Lists.
GET {clientId}/Config/DistributionLists/{distributionListName}

Retrieve distribution list with specified name.
GET {clientId}/Config/Filters/{filterId}

Retrieve a Filter.
GET {clientId}/Config/Frequencies

Retrieve all Frequencies.
GET {clientId}/Config/Locales

Retrieve all Locales.
GET {clientId}/Config/NestedProgramGroups

Retrieve all Nested Program Groups.
GET {clientId}/Config/ProgramGroup

Retrieve all Program Groups.
GET {clientId}/Config/ProgramGroupPermissions

Retrieve Permissions for all Program Groups.
GET {clientId}/Config/Programs/{programId}

Retrieve a Program.
GET {clientId}/Config/Programs

Retrieve all Programs.
GET {clientId}/Config/ProgramPermissions

Retrieve Permissions for all Programs.
GET {clientId}/Config/RequiredPreferenceConsents/{filterId}

Retrieve Required Preference Consents
GET {clientId}/Config/SourceGroups

Retrieve all Source Groups.
GET {clientId}/Config/TextTags

Retrieve all Text Tags.
GET {clientId}/Config/UserGroups

Retrieve all User Groups.
GET {clientId}/Config/Users

Retrieve all Users.
POST {clientId}/Config/Attributes

Add Attributes.
POST {clientId}/Config/CustomProperties

Add Custom Properties.
POST {clientId}/Config/DistributionLists

Add Distribution Lists.
POST {clientId}/Config/Filters

Add Filters.
POST {clientId}/Config/Frequencies

Add Frequencies.
POST {clientId}/Config/Locales

Add Locales.
POST {clientId}/Config/NestedProgramGroups

Add Nested Program Groups.
POST {clientId}/Config/ProgramGroups/Update

Add Program Groups. This API will add Text Tags and Custom Properties that don’t exist on your account before associating them to the Program Group.
POST {clientId}/Config/ProgramGroupPermissions

Add Permissions for Program Groups.
POST {clientId}/Config/ProgramPermissions

Add Permissions for Programs.
POST {clientId}/Config/Programs

Add Programs.
POST {clientId}/Config/SourceGroups

Add Source Groups.
POST {clientId}/Config/TextTags

Add Text Tags. Note: This call should only be used for promoting new Text Tags.If a text tag already exists, this API will remove any existing locales and associate the locales that you specify in your request. This will remove any values associated with the text tag for those locales across Program Groups, Programs, Filters and Frequencies.
POST {clientId}/Config/UserGroups

Add User Groups.
POST {clientId}/Config/Users

Add Users.
POST {clientId}/Config/CustomProperties/Filter

Add Custom Properties on Filters. This API will add Custom Properties that don’t exist on your account before associating them to the Filter.
POST {clientId}/Config/TextTags/Filter

Add Text Tags on Filters. This API will add Text Tags for the specified locales that don’t exist on your account before associating them to the Filter.
POST {clientId}/Config/CustomProperties/Program

Add Custom Properties on Programs. This API will add Custom Properties that don’t exist on your account before associating them to the Program.
POST {clientId}/Config/TextTags/Program

Add Text Tags on Programs. This API will add Text Tags for the specified locales that don’t exist on your account before associating them to the Program.
PUT {clientId}/Config/RequiredPreferenceConsents/{filterId}

Add Required Preference Consents to a Filter