Adobe Experience Platform enables you to bring data fragments together from multiple sources and combine them in order to see a complete view of each of your individual customers. When bringing this data together, merge policies are the rules that Platform uses to determine how data will be prioritized and what data will be combined to create a unified view.
For example, if a customer interacts with your brand across several channels, your organization will have multiple profile fragments related to that single customer appearing in multiple datasets. When these fragments are ingested into Platform, they are merged together in order to create a single profile for that customer. When the data from multiple sources conflicts (for example one fragment lists the customer as “single” while the other lists the customer as “married”) the merge policy determines which information to include in the profile for the individual.
Using RESTful APIs or the user interface, you can create new merge policies, manage existing policies, and set a default merge policy for your organization. This guide provides steps for working with merge policies using the API.
To work with merge policies using the UI, please refer to the merge policies UI guide.
The API endpoint used in this guide is part of the Real-time Customer Profile API. Before continuing, please review the getting started guide for links to related documentation, a guide to reading the sample API calls in this document, and important information regarding required headers that are needed to successfully make calls to any Experience Platform API.
Merge policies are private to your IMS Organization, allowing you to create different policies to merge schemas in the specific ways that you need. Any API accessing Profile data requires a merge policy, though a default will be used if one is not explicitly provided. Platform provides organizations with a default merge policy, or you can create a merge policy for a specific Experience Data Model (XDM) schema class and mark it as the default for your organization.
While each organization can potentially have multiple merge policies per schema class, each class can have only one default merge policy. Any merge policy set as default will be used in cases where the name of the schema class is provided and a merge policy is required but not provided.
When you set a new merge policy as the default, any existing merge policy that was previously set as the default will automatically be updated to no longer be used as the default.
The complete merge policy object represents a set of preferences controlling aspects of merging profile fragments.
Merge policy object
{
"id": "{MERGE_POLICY_ID}",
"name": "{NAME}",
"imsOrgId": "{IMS_ORG}",
"schema": {
"name": "{SCHEMA_CLASS_NAME}"
},
"version": 1,
"identityGraph": {
"type": "{IDENTITY_GRAPH_TYPE}"
},
"attributeMerge": {
"type": "{ATTRIBUTE_MERGE_TYPE}"
},
"default": "{BOOLEAN}",
"updateEpoch": "{UPDATE_TIME}"
}
Property | Description |
---|---|
id |
The system generated unique identifier assigned at creation time |
name |
Friendly name by which the merge policy can be identified in list views. |
imsOrgId |
Organization ID to which this merge policy belongs |
identityGraph |
Identity graph object indicating the identity graph from which related identities will be obtained. Profile fragments found for all related identities will be merged. |
attributeMerge |
Attribute merge object indicating the manner by which the merge policy will prioritize profile attributes in the case of data conflicts. |
schema.name |
Part of the schema object, the name field contains the XDM schema class to which the merge policy relates. For more information on schemas and classes, please read the XDM documentation. |
default |
Boolean value indicating if this merge policy is the default for the specified schema. |
version |
Platform maintained version of merge policy. This read-only value is incremented whenever a merge policy is updated. |
updateEpoch |
Date of the last update to the merge policy. |
Example merge policy
{
"id": "10648288-cda5-11e8-a8d5-f2801f1b9fd1",
"name": "profile-default",
"imsOrgId": "{IMS_ORG}",
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type": "timestampOrdered"
},
"default": true,
"updateEpoch": 1551660639
}
Adobe Experience Platform Identity Service manages the identity graphs used globally and for each organization on Experience Platform. The identityGraph
attribute of the merge policy defines how to determine the related identities for a user.
identityGraph object
"identityGraph": {
"type": "{IDENTITY_GRAPH_TYPE}"
}
Where {IDENTITY_GRAPH_TYPE}
is one of the following:
Example identityGraph
"identityGraph": {
"type": "pdg"
}
A profile fragment is the profile information for just one identity out of the list of identities that exist for a particular user. When the identity graph type used results in more than one identity, there is a potential for conflicting profile attributes and priority must be specified. Using attributeMerge
, you can specify which profile attributes to prioritize in the event of a merge conflict between Key Value (record data) type datasets.
attributeMerge object
"attributeMerge": {
"type": "{ATTRIBUTE_MERGE_TYPE}"
}
Where {ATTRIBUTE_MERGE_TYPE}
is one of the following:
timestampOrdered
: (default) Give priority to the profile which was updated last. Using this merge type, the data
attribute is not required. timestampOrdered
also supports custom timestamps which will take precedence when merging profile fragments within or across datasets. To learn more, see the Appendix section on using custom timestamps.dataSetPrecedence
: Give priority to profile fragments based on the dataset from which they came. This could be used when information present in one dataset is preferred or trusted over data in another dataset. When using this merge type, the order
attribute is required, as it lists the datasets in the order of priority.
order
: When “dataSetPrecedence” is used, an order
array must be supplied with a list of datasets. Any datasets not included in the list will not be merged. In other words, datasets must be explicitly listed to be merged into a profile. The order
array lists the IDs of the datasets in order of priority.attributeMerge
object using dataSetPrecedence
type "attributeMerge": {
"type": "dataSetPrecedence",
"order" : [
"dataSetId_2",
"dataSetId_3",
"dataSetId_1",
"dataSetId_4"
]
}
attributeMerge
object using timestampOrdered
type "attributeMerge": {
"type": "timestampOrdered"
}
The schema object specifies the Experience Data Model (XDM) schema class for which this merge policy is created.
schema
object
"schema": {
"name": "{SCHEMA_NAME}"
}
Where the value of name
is the name of the XDM class upon which the schema associated with the merge policy is based.
Example schema
"schema": {
"name": "_xdm.context.profile"
}
To learn more about XDM and working with schemas in Experience Platform, begin by reading the XDM System overview.
Using the Real-time Customer Profile API, the /config/mergePolicies
endpoint allows you perform a lookup request to view a specific merge policy by its ID, or access all of the merge policies in your IMS Organization, filtered by specific criteria. You can also use the /config/mergePolicies/bulk-get
endpoint to retrieve multiple merge policies by their IDs. Steps for performing each of these calls are outlined in the following sections.
You can access a single merge policy by its ID by making a GET request to the /config/mergePolicies
endpoint and including the mergePolicyId
in the request path.
API format
GET /config/mergePolicies/{mergePolicyId}
Parameter | Description |
---|---|
{mergePolicyId} |
The identifier of the merge policy you want to delete. |
Request
curl -X GET \
'https://platform.adobe.io/data/core/ups/config/mergePolicies/10648288-cda5-11e8-a8d5-f2801f1b9fd1' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}
Response
A successful response returns the details of the merge policy.
{
"id": "10648288-cda5-11e8-a8d5-f2801f1b9fd1",
"imsOrgId": "{IMS_ORG}",
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "pdg"
},
"attributeMerge": {
"type": "timestampOrdered"
},
"default": false,
"updateEpoch": 1551127597
}
See the components of merge policies section at the beginning of this document for details on each of the individual elements that make up a merge policy.
You can retrieve multiple merge policies by making a POST request to the /config/mergePolicies/bulk-get
endpoint and including the IDs of the merge policies you wish to retrieve in the request body.
API format
POST /config/mergePolicies/bulk-get
Request
The request body includes an “ids” array with individual objects containing the “id” for each merge policy for which you would like to retrieve details.
curl -X POST \
'https://platform.adobe.io/data/core/ups/config/mergePolicies/bulk-get' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"ids": [
{
"id": "0bf16e61-90e9-4204-b8fa-ad250360957b"
},
{
"id": "42d4a596-b1c6-46c0-994e-ca5ef1f85130"
}
]
}'
Response
A successful response returns HTTP Status 207 (Multi-Status) and the details of the merge policies whose IDs were provided in the POST request.
{
"results": {
"0bf16e61-90e9-4204-b8fa-ad250360957b": {
"id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
"name": "Profile Default Merge Policy",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
"sandboxName": "prod",
"type": "production",
"default": true
},
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type": "timestampOrdered"
},
"default": true,
"updateEpoch": 1552086578
},
"42d4a596-b1c6-46c0-994e-ca5ef1f85130": {
"id": "42d4a596-b1c6-46c0-994e-ca5ef1f85130",
"name": "Dataset Precedence Merge Policy",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
"sandboxName": "prod",
"type": "production",
"default": true
},
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "pdg"
},
"attributeMerge": {
"type": "dataSetPrecedence",
"order": [
"5b76f86b85d0e00000be5c8b",
"5b76f8d787a6af01e2ceda18"
]
},
"default": false,
"updateEpoch": 1576099719
}
}
}
See the components of merge policies section at the beginning of this document for details on each of the individual elements that make up a merge policy.
You can list multiple merge policies within your IMS Organization by issuing a GET request to the /config/mergePolicies
endpoint and using optional query parameters to filter, order, and paginate the response. Multiple parameters can be included, separated by ampersands (&). Making a call to this endpoint with no parameters will retrieve all merge policies available for your organization.
API format
GET /config/mergePolicies?{QUERY_PARAMS}
Parameter | Description |
---|---|
default |
A boolean value that filters results by whether or not the merge policies are the default for a schema class. |
limit |
Specifies the page size limit to control the number of results that are included in a page. Default value: 20 |
orderBy |
Specifies the field by which to order results as in orderBy=name or orderBy=+name to sort by name in ascending order, or orderBy=-name , to sort in descending order. Omitting this value results in the default sorting of name in ascending order. |
schema.name |
Name of the schema for which to retrieve available merge policies. |
identityGraph.type |
Filters results by the identity graph type. Possible values include “none” and “pdg” (Private graph). |
attributeMerge.type |
Filters results by the attribute merge type used. Possible values include “timestampOrdered” and “dataSetPrecedence”. |
start |
Page offset - specify the starting ID for data to retrieve. Default value: 0 |
version |
Specify this if you are looking to use a specific version of the merge policy. By default, the latest version will be used. |
For more information regarding schema.name
, identityGraph.type
, and attributeMerge.type
, refer to the components of merge policies section provided earlier in this guide.
Request
The following request lists all merge policies for a given schema:
curl -X GET \
'https://platform.adobe.io/data/core/ups/config/mergePolicies?schema.name=_xdm.context.profile' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}
Response
A successful response returns a paginated list of merge policies that meet the criteria specified by the query parameters sent in the request.
{
"_page": {
"totalCount": 2,
"pageSize": 2
},
"children": [
{
"id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
"name": "Profile Default Merge Policy",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
"sandboxName": "prod",
"type": "production",
"default": true
},
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type": "timestampOrdered"
},
"default": true,
"updateEpoch": 1552086578
},
{
"id": "42d4a596-b1c6-46c0-994e-ca5ef1f85130",
"name": "Dataset Precedence Merge Policy",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
"sandboxName": "prod",
"type": "production",
"default": true
},
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "pdg"
},
"attributeMerge": {
"type": "dataSetPrecedence",
"order": [
"5b76f86b85d0e00000be5c8b",
"5b76f8d787a6af01e2ceda18"
]
},
"default": false,
"updateEpoch": 1576099719
}
],
"_links": {
"next": {
"href": "@/mergePolicies?start=K1JJRDpFaWc5QUpZWHY1c2JBQUFBQUFBQUFBPT0jUlQ6MSNUUkM6MiNGUEM6QWdFQUFBQldBQkVBQVBnaFFQLzM4VUIvL2tKQi8rLysvMUpBLzMrMi8wRkFmLzR4UUwvL0VrRC85em4zRTBEcmNmYi92Kzh4UUwvL05rQVgzRi8rMStqNS80WHQwN2NhUUVzQUFBUUFleGpLQ1JnVXRVcEFCQUFFQVBBRA==&orderBy=&limit=2"
}
}
}
Property | Description |
---|---|
_links.next.href |
A URI address for the next page of results. Use this URI as the request parameter for another API call to the same endpoint to view the page. If no next page exists, this value will be an empty string. |
You can create a new merge policy for your organization by making a POST request to the /config/mergePolicies
endpoint.
API format
POST /config/mergePolicies
Request
The following request creates a new merge policy, which is configured by the attribute values provided in the payload:
curl -X POST \
https://platform.adobe.io/data/core/ups/config/mergePolicies \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Loyalty members ordered by ID",
"identityGraph" : {
"type": "none"
},
"attributeMerge" : {
"type":"dataSetPrecedence",
"order" : [
"5b76f86b85d0e00000be5c8b",
"5b76f8d787a6af01e2ceda18"
]
},
"schema": {
"name":"_xdm.context.profile"
},
"default": true
}'
Property | Description |
---|---|
name |
A human-friendly name by which the merge policy can be identified in list views. |
identityGraph.type |
The identity graph type from which to obtain related identities to merge. Possible values: “none” or “pdg” (Private graph). |
attributeMerge |
The manner by which to prioritize profile attribute values in the case of data conflicts. |
schema |
The XDM schema class associated with the merge policy. |
default |
Specifies whether this merge policy is the default for the schema. |
Refer to the components of merge policies section for more information.
Response
A successful response returns the details of the newly created merge policy.
{
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"name": "Loyalty members ordered by ID",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
"sandboxName": "prod",
"type": "production",
"default": true
},
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type": "dataSetPrecedence",
"order": [
"5b76f86b85d0e00000be5c8b",
"5b76f8d787a6af01e2ceda18"
]
},
"default": true,
"updateEpoch": 1551898378
}
See the components of merge policies section at the beginning of this document for details on each of the individual elements that make up a merge policy.
You can modify an existing merge policy by editing individual attributes (PATCH) or by overwriting the entire merge policy with new attributes (PUT). Examples of each are shown below.
You can edit individual fields for a merge policy by making a PATCH request to the /config/mergePolicies/{mergePolicyId}
endpoint:
API format
PATCH /config/mergePolicies/{mergePolicyId}
Parameter | Description |
---|---|
{mergePolicyId} |
The identifier of the merge policy you want to delete. |
Request
The following request updates a specified merge policy by changing the value of its default
property to true
:
curl -X PATCH \
https://platform.adobe.io/data/core/ups/config/mergePolicies/e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"op": "add",
"path": "/default?lang=en",
"value": "true"
}'
Property | Description |
---|---|
op |
Specifies the operation to take. Examples of other PATCH operations can be found in the JSON Patch documentation |
path |
The path of the field to update. Accepted values are: “/name?lang=en”, “/identityGraph.type?lang=en”, “/attributeMerge.type?lang=en”, “/schema.name?lang=en”, “/version?lang=en”, “/default?lang=en” |
value |
The value to set the specified field to. |
Refer to the components of merge policies section for more information.
Response
A successful response returns the details of the newly updated merge policy.
{
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"name": "Loyalty members ordered by ID",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
"sandboxName": "prod",
"type": "production",
"default": true
},
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type": "dataSetPrecedence",
"order": [
"5b76f86b85d0e00000be5c8b",
"5b76f8d787a6af01e2ceda18"
]
},
"default": true,
"updateEpoch": 1551898378
}
Another way to modify a merge policy is to use a PUT request, which overwrites the entire merge policy.
API format
PUT /config/mergePolicies/{mergePolicyId}
Parameter | Description |
---|---|
{mergePolicyId} |
The identifier of the merge policy you want to overwrite. |
Request
The following request overwrites the specified merge policy, replacing its attribute values with those supplied in the payload. Since this request completely replaces an existing merge policy, you are required to supply all of the same fields that were required when originally defining the merge policy. However, this time you are providing updated values for the fields you want to change.
curl -X PUT \
https://platform.adobe.io/data/core/ups/config/mergePolicies/e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Loyalty members ordered by ID",
"imsOrgId": "{IMS_ORG}",
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type": "dataSetPrecedence",
"order": [
"5b76f86b85d0e00000be5c8b",
"5b76f8d787a6af01e2ceda18"
]
},
"default": true,
"updateEpoch": 1551898378
}'
Property | Description |
---|---|
name |
A human-friendly name by which the merge policy can be identified in list views. |
identityGraph |
The identity graph from which to obtain related identities to merge. |
attributeMerge |
The manner by which to prioritize profile attribute values in the case of data conflicts. |
schema |
The XDM schema class associated with the merge policy. |
default |
Specifies whether this merge policy is the default for the schema. |
Refer to the components of merge policies section for more information.
Response
A successful response returns the details of the updated merge policy.
{
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"name": "Loyalty members ordered by ID",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
"sandboxName": "prod",
"type": "production",
"default": true
},
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type": "dataSetPrecedence",
"order": [
"5b76f86b85d0e00000be5c8b",
"5b76f8d787a6af01e2ceda18"
]
},
"default": true,
"updateEpoch": 1551898378
}
A merge policy can be deleted by making a DELETE request to the /config/mergePolicies
endpoint and including the ID of the merge policy that you wish to delete in the request path.
API format
DELETE /config/mergePolicies/{mergePolicyId}
Parameter | Description |
---|---|
{mergePolicyId} |
The identifier of the merge policy you want to delete. |
Request
The following request deletes a merge policy.
curl -X DELETE \
https://platform.adobe.io/data/core/ups/config/mergePolicies/e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
Response
A successful delete request returns HTTP Status 200 (OK) and an empty response body. To confirm the deletion was successful, you can perform a GET request to view the merge policy by its ID. If the merge policy was deleted, you will receive an HTTP Status 404 (Not Found) error.
Now that you know how to create and configure merge policies for your organization, you can use them to adjust the view of customer profiles within Platform and to create audience segments from your Real-time Customer Profile data. Please see the Adobe Experience Platform Segmentation Service documentation to begin defining and working with segments.
This section provides supplemental information related to working with merge policies.
As records are ingested into Experience Platform, a system timestamp is obtained at the time of ingestion and added to the record. When timestampOrdered
is selected as the attributeMerge
type for a merge policy, profiles are merged based on the system timestamp. In other words, merging is done based on the timestamp for when the record was ingested into Platform.
Occasionally there may be use cases, such as backfilling data or ensuring the correct order of events if records are ingested out of order, where it is necessary to supply a custom timestamp and have the merge policy honor the custom timestamp rather than the system timestamp.
In order to use a custom timestamp, the External Source System Audit Details Mixin must be added to your Profile schema. Once added, the custom timestamp can be populated using the xdm:lastUpdatedDate
field. When a record is ingested with the xdm:lastUpdatedDate
field populated, Experience Platform will use that field to merge records or profile fragments within and across datasets. If xdm:lastUpdatedDate
is not present, or not populated, Platform will continue to use the system timestamp.
You must ensure that the xdm:lastUpdatedDate
timestamp is populated when sending a PATCH on the same record.
For step-by-step instructions on working with schemas using the Schema Registry API, including how to add mixins to schemas, please visit the tutorial for creating a schema using the API.
To work with custom timestamps using the UI, refer to the section on using custom timestamps in the merge policies user guide.
The following example shows correctly populated fields in the External Source System Audit Details Mixin. The complete mixin JSON can also be viewed in the public Experience Data Model (XDM) repo on GitHub.
{
"xdm:createdBy": "{CREATED_BY}",
"xdm:createdDate": "2018-01-02T15:52:25+00:00",
"xdm:lastUpdatedBy": "{LAST_UPDATED_BY}",
"xdm:lastUpdatedDate": "2018-01-02T15:52:25+00:00",
"xdm:lastActivityDate": "2018-01-02T15:52:25+00:00",
"xdm:lastReferencedDate": "2018-01-02T15:52:25+00:00",
"xdm:lastViewedDate": "2018-01-02T15:52:25+00:00"
}