Configuration

The Experience API's, also referred to 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 API's natively support localization and specific query parameters to return custom configurations, consents, preference choices, and other data elements, giving you complete control over your customers' experiences, spanning from micro experiences to full-featured preference centers and everything in between.

These API's are classified as follows:

• Profile Configuration
• Preference Configuration

NOTE

Both MyPreferences 2.0 and 3.0 customers utilize the Configuration APIs. However, users of MyPreferences 3.0 must be cognizant about the route discrepancy when using these APIs. The Configuration API along with the Synchronization API are the only API's relevant to MyPreferences 3.0 users, and they can be accessed here.

A Profile represents a unified view of a user across all channels and touchpoints. A user can be a known or an anonymous individual, an application, or an IoT device. The Profile record can contain demographic and psychographic information, consents, preferences, group associations, feedback and any other pieces of zero-party data collected along the customer journey.

This method allows you to submit a user’s profile, preference, and consent information in a single call to create a unique Profile record. The response will include a system generated ProfileId that can be used to retrieve or edit the profile later.

This method will retrieve one or more profiles that match the email address specified in the request. The EmailType is an optional parameter that can be passed in to further restrict the return set.

This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response.

This method will retrieve one or more profiles that have an exact match on the mailing address field values specified in the request. Passing minimal data in the parameters may result in multiple profiles being returned in the response, so the more parameters passed in will increase the likelihood of finding the desired profile being searched for.

All fields that are passed in need to match the values in the profile or the record will not be returned. All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response.

For example, if a user wants to search for a profile with the name Audrey Julia Michaels at an unknown address on a road named Jefferson in Roswell, GA, they could use the following request:

GET {clientId}/Profile/Address?address1=Jefferson&city=Roswell&stateProvince=GA&addressType=Home&firstName=Audrey&middleName=Julia&lastName=Michaels&partialAddress1Match=true&partialNameMatch=true

This method will retrieve one or more Profiles that fit an exact match the first, middle, and last name values specified in the request.

This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response.

This method will retrieve one or more Profiles that fit a partial match the first, middle, and last name values specified in the request. This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response. For example: 'Smi' included in the last name parameter could match 'Smith' or 'Smilla', but not 'Small' or 'Sampson'...

This method will retrieve one or more Profiles that contain the custom fields and values specified in the request. More than one custom field can be filtered on, and the parameters are read in as an array with the first field and value combination starting with 0.

This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response. For example: if a user wants to find a profile that has custom field "alpha" equal to "couch" and custom field "beta" equal to "book", they could use this request to achieve that result:

GET {clientId}/Profile/CustomFields?customFields[0].Name=alpha&customFields[0].Value=couch&customFields[1].Name=beta&customFields[1].Value=book

This method expands the ability to search for profiles by custom fields by the inclusion of an operator for each custom field.

The operator specifies whether the values in the CustomFields.Value parameter should be evaluated by "Equals, All of, or Any of" adding flexibility to filtering by a custom field.

This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response. For example: if a user wants to find profiles that has custom field "alpha" with any of the values "couch, chair or table" the following request to achieve that result:

GET {clientId}/Profile/CustomFields/SelectList? customFields[0].OperatorId=3&customFields[0].Name=alpha&customFields[0].Value=couch:chair:table

Retrieve profiles by an exact match on one or more tag values. Tag parameters are read in as an array with the first tag value starting with 0.

This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response. For Example: If a user wants to return profiles that can have either "tester" and "preferred" tags and return all implied preferences and a full consent history, the following API call can be used:

GET {clientId}/Profiles/Tags?tag[0]=tester&tag[1]=preferred&exactMatch=false&implied=true

This method will retrieve one or more Profiles that match the preference attributes specified in the request. More than one attribute can be filtered on, and the parameters are read in as an array with the first field and value combination starting with 0.

All attribute fields and values that are identified in the parameters need to match a profile for it to be returned in the response. This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response. For example: if a user wants to find a profile that has an attribute "alpha" equal to "phone" and attribute "beta" equal to "account", they could use this request to achieve that result:

GET {clientId}/Profiles/Attributes?attributes[0].Key=alpha&attributes[0].Value=phone&attributes[1].Key=beta&attributes[1].Value=account

This method will retrieve one or more profiles that are part of a group by using the profile Id of the group’s primary profile. Using this endpoint, if the profile id is found then all of the profiles within that group are returned in the response.

This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response.

This method will retrieve one or more profiles that are part of a group by using the AlternateID/AlternateIdType combination of the group’s primary profile. Using this endpoint, if the profile's Alternate id is found then all of the profiles within that group are returned in the response.

This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response.

This method will retrieve one or more profiles that are part of a group by using the phone number of a primary profile of the group. Using this endpoint, if the primary profile's phone number is found then all of the profiles within that group are returned in the response.

This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response.

This method will retrieve one or more profiles that are part of a group by using the email address of a primary profile of the group. Using this endpoint, if the primary profile's email address is found then all of the profiles within that group are returned in the response.

This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response.

This method will retrieve one or more profiles that are part of a group by using the name of the group. If the group's name is found then all of the profiles within that group are returned in the response.

This method can only return up to 50 profiles. If more than 50 matching profiles are found, the API returns a 403-Forbidden.

All active consents, custom fields, groups, tags, and preferences for which you have permissions will be returned in the response.

This method allows you to update a profile without doing a GET first if the Profile ID is already known. This method will perform an update operation on all preferences, consents, groups, tags, and custom fields submitted with the request.

This method allows you to do a full replace of a profile.

The original information contained in the profile will be overwritten by the information contained in the request.

Properties and collections that are not included in the PUT request will be considered blank, and will no longer be included in the profile.

The PATCH method applies partial modifications to a single profile specified by the ProfileId parameter. Only information specified in the path and values included in the body will be updated in the profile.

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.

This endpoint can be used for both inserts and updates to a profile using the Alternate ID/Alternate Type provided in the request. If the Alternate ID and Alternate Type combination are found on an existing profile, the profile will be updated with the information submitted in the request. If not, this method will perform an insert operation to create the profile.

This method allows you to do a full replace of a profile specified by the Alternate ID and AlternateIdType parameters. The original information contained in the profile will be overwritten by the information contained in the request.

Properties and collections that are not included in the PUT request will be considered blank, and will no longer be included in the profile.

The PATCH method applies partial modifications to a single profile specified by the AlternateID and AlternateIdType parameter combination. Only information specified in the path and values included in the body will be updated in the profile.

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.

This method deactivates and archives preferences associated with the Profile or Contact Elements on a profile across one or more Filters.

To deactivate all preferences across all Contact Elements and Filters on a profile, simply set the GlobalDeactivate parameter to true. Archived preferences are no longer returned via the MyPrefererences standard API.

You can create a Segment to retrieve archived preferences using the MyPreferences Bulk Export API.

This method allows you to permanently delete a profile and all associated preferences. It must be used with caution as the delete operation cannot be reversed.

This method allows you to retrieve the entire history for standard fields associated with a single profile using a specific combination of AlternateID and AlternateIDType. Along with the Profile ID, a collection of current AlternateIDs is also returned with each update. Elements like consents, custom fields, groups, tags, and preferences will not be returned. Standard field history will be returned in ascending order by modified date.

This method will return the entire history for standard fields associated with a single profile. Along with the Profile ID, a collection of current AlternateIDs is also returned with each update. Elements like consents, custom fields, groups, tags, and preferences will not be returned. Standard field history will be returned in ascending order by modified date.

This method will return the current and historical preferences that are associated with a specific AlternateID/AlternateIDType combination. The basic profile, contact elements, and preference history will be returned in the response. Custom fields, consents, groups, and tags will not be returned in the response.

This method will return the current and historical preferences that are associated with the profile id. The basic profile, contact elements, and preference history will be returned in the response. Custom fields, consents, groups, and tags will not be returned in the response.

This method will return the entire custom field history that is associated with a single profile using an AlternateID/AlternateIDType combination. Only the basic profile and custom field history will be returned in the response. Elements like consents, groups, tags, and preferences will not be returned. Custom field history will be returned in ascending order by modified date.

This method will return the entire custom field history that is associated with a single profile. Only the basic profile and custom field history will be returned in the response. Elements like consents, groups, tags, and preferences will not be returned. Custom field history will be returned in ascending order by modified date.

This method allows you to retrieve the entire history of contact elements along with any consent associated for a single profile using a specific combination of AlternateID and AlternateIDType. Profile-only consents, custom fields, groups, tags, and preferences will not be returned.

This method will return the entire consent history that is associated with a single profile id. Only the basic profile and consent history will be returned in the response. Elements like custom fields, groups, tags, and preferences will not be returned. Consent history will be returned in ascending order by Consent Type, Version, and modified date.

This method will return the entire consent history that is associated with a single profile using an AlternateID/AlternateIDType combination.

Only the basic profile and consent history will be returned in the response. Elements like custom fields, groups, tags, and preferences will not be returned.

Consent history will be returned in ascending order by Consent Type, Version, and modified date.