Merge policies endpoint
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. To learn more about merge policies in general, and their role within Experience Platform, please begin by reading the merge policies overview.
Getting started
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.
Components of merge policies components-of-merge-policies
Merge policies are private to your 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.
To ensure all profile consumers are working with the same view on edges, merge policies can be marked as active on edge. In order for an audience to be activated on edge (marked as an edge audience), it must be tied to a merge policy that is marked as active on edge. If an audience is not tied to a merge policy that is marked as active on edge, the audience will not be marked as active on edge, and will be marked as a streaming audience.
Additionally, each organization can only have one merge policy that is active on edge. If a merge policy is active on edge, it can be used for other systems on edge, such as Edge Profile, Edge Segmentation, and Destinations on Edge.
Complete merge policy object
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": "{ORG_ID}",
"schema": {
"name": "{SCHEMA_CLASS_NAME}"
},
"version": 1,
"identityGraph": {
"type": "{IDENTITY_GRAPH_TYPE}"
},
"attributeMerge": {
"type": "{ATTRIBUTE_MERGE_TYPE}"
},
"isActiveOnEdge": "{BOOLEAN}",
"default": "{BOOLEAN}",
"updateEpoch": "{UPDATE_TIME}"
}
id
name
imsOrgId
schema.name
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.version
identityGraph
attributeMerge
isActiveOnEdge
false
.default
updateEpoch
Example merge policy
{
"id": "10648288-cda5-11e8-a8d5-f2801f1b9fd1",
"name": "profile-default",
"imsOrgId": "{ORG_ID}",
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type": "timestampOrdered"
},
"isActiveOnEdge": false,
"default": true,
"updateEpoch": 1551660639
}
Identity graph identity-graph
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:
- “none”: Perform no identity stitching.
- “pdg”: Perform identity stitching based on your private identity graph.
Example identityGraph
"identityGraph": {
"type": "pdg"
}
Attribute merge attribute-merge
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, thedata
attribute is not required.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, theorder
attribute is required, as it lists the datasets in the order of priority.order
: When “dataSetPrecedence” is used, anorder
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. Theorder
array lists the IDs of the datasets in order of priority.
Example attributeMerge
object using dataSetPrecedence
type
"attributeMerge": {
"type": "dataSetPrecedence",
"order": [
"dataSetId_2",
"dataSetId_3",
"dataSetId_1",
"dataSetId_4"
]
}
Example attributeMerge
object using timestampOrdered
type
"attributeMerge": {
"type": "timestampOrdered"
}
Schema schema
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.
Access merge policies access-merge-policies
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 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.
Access a single merge policy by ID
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}
{mergePolicyId}
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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}
Response
A successful response returns the details of the merge policy.
{
"id": "10648288-cda5-11e8-a8d5-f2801f1b9fd1",
"imsOrgId": "{ORG_ID}",
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "pdg"
},
"attributeMerge": {
"type": "timestampOrdered"
},
"isActiveOnEdge": "false",
"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.
Retrieve multiple merge policies by their IDs
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: {ORG_ID}' \
-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": "{ORG_ID}",
"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"
},
"isActiveOnEdge": true,
"default": true,
"updateEpoch": 1552086578
},
"42d4a596-b1c6-46c0-994e-ca5ef1f85130": {
"id": "42d4a596-b1c6-46c0-994e-ca5ef1f85130",
"name": "Dataset Precedence Merge Policy",
"imsOrgId": "{ORG_ID}",
"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"
]
},
"isActiveOnEdge": false,
"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.
List multiple merge policies by criteria
You can list multiple merge policies within your 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}
default
limit
orderBy
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.isActiveOnEdge
schema.name
identityGraph.type
attributeMerge.type
start
version
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: {ORG_ID}' \
-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": "{ORG_ID}",
"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"
},
"isActiveOnEdge": true,
"default": true,
"updateEpoch": 1552086578
},
{
"id": "42d4a596-b1c6-46c0-994e-ca5ef1f85130",
"name": "Dataset Precedence Merge Policy",
"imsOrgId": "{ORG_ID}",
"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"
]
},
"isActiveOnEdge": false,
"default": false,
"updateEpoch": 1576099719
}
],
"_links": {
"next": {
"href": "@/mergePolicies?start=K1JJRDpFaWc5QUpZWHY1c2JBQUFBQUFBQUFBPT0jUlQ6MSNUUkM6MiNGUEM6QWdFQUFBQldBQkVBQVBnaFFQLzM4VUIvL2tKQi8rLysvMUpBLzMrMi8wRkFmLzR4UUwvL0VrRC85em4zRTBEcmNmYi92Kzh4UUwvL05rQVgzRi8rMStqNS80WHQwN2NhUUVzQUFBUUFleGpLQ1JnVXRVcEFCQUFFQVBBRA==&orderBy=&limit=2"
}
}
}
_links.next.href
Create a merge policy
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: {ORG_ID}' \
-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"
},
"isActiveOnEdge": true,
"default": true
}'
name
identityGraph.type
attributeMerge
schema
isActiveOnEdge
default
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": "{ORG_ID}",
"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"
]
},
"isActiveOnEdge": true,
"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.
Update a merge policy update
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.
Edit individual merge policy fields
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}
{mergePolicyId}
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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"op": "add",
"path": "/default",
"value": "true"
}'
op
path
value
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": "{ORG_ID}",
"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"
]
},
"isActiveOnEdge": true,
"default": true,
"updateEpoch": 1551898378
}
Overwrite a merge policy
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}
{mergePolicyId}
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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Loyalty members ordered by ID",
"imsOrgId": "{ORG_ID}",
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type": "dataSetPrecedence",
"order": [
"5b76f86b85d0e00000be5c8b",
"5b76f8d787a6af01e2ceda18"
]
},
"isActiveOnEdge": true,
"default": true,
"updateEpoch": 1551898378
}'
name
identityGraph
attributeMerge
schema
isActiveOnEdge
default
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": "{ORG_ID}",
"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"
]
},
"isActiveOnEdge": true,
"default": true,
"updateEpoch": 1551898378
}
Delete a merge policy
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}
{mergePolicyId}
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: {ORG_ID}' \
-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.
Next steps
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 audiences from your Real-Time Customer Profile data.
Please see the Adobe Experience Platform Segmentation Service documentation to begin defining and working with audiences.