Merge profiles

Merge profiles is a special methodology that can merge two or more profiles (a.k.a temporary profiles) into a single profile (a.k.a canonical profile). The merged profiles are linked to the canonical profile i.e. a GET on a profile that was merged into the canonical profile will return the canonical profile. The API will create a new canonical profile if one does not exist at the time of the merge. However, a 404 Not Found will be returned if a the temporary profile being merged does not exist. 


Profiles can be merged by making a request to url /v1/companies/<companyId>/buckets/<bucketId>/profiles/<profileId> where the canonical profile is represented by the <profileId>. The request should be POST and a successful merge with result in either a 201 CREATED if the merge results in the creation of a canonical profile or 200 OK if temporary profiles are merged into an existing canonical profile. Merge is analogous to update and both the processes can be triggered on a profile at the same time. For a profile to be merged with another, the profile representation posted in the request should contain an array with the key "mergedProfiles". The array can contain any number of temporary profile Ids that should be merged into the canonical profile.

The merge updates the canonical profile with the session (or events in the session), attributes and services of the temporary profile but prioritises sessions (or events in the session), attributes and services of the canonical profile over temporary profiles in case of a match.


NOTE: Merging is not reversible, please consult with your implementation consultant and account manager before performing profile merging on your account's production environment for help with best practices


Required permission profile.merge


Request Headers

Header

Required

Acceptable Value(s)

Description

Content-typeYesapplication/json
AcceptYesapplication/json, application/javascript, image/*Image response will return a 1x1 pixel result.
Content-encodingNogzipCaller can send a gzipped request to the API and set the Content-encoding as gzip.
Accept-encodingNogzip

Caller can request a gzipped response from the API and set the Accept-encoding as gzip.


Query Parameters

Key

Required

Description

app_keyNoAn app key refers to a collectApp. If an app key is specified, the profile data is added as the collectApp corresponding to that app key. If no app key is specified then profile data is added using the default collectApp "web". Similarly, the response will return the collectApp data corresponding to the app key. The returned data will additionally be filtered though any whitelists and/or blacklists configured for this collect app. If no collect app is specified, data and; blacklist and whitelist configurations of collectApp "web" will be used.
max_return_sizeNoMax return size refers to the size of the profile to be returned to the caller. If no max_return_size is specified, the profile of size 500 is returned to the caller. Please read the documentation about profile trimming to learn more about how the profile is trimmed to the specified size.
max_return_eventsNoMax return events refers to the the total number of events to be returned to the caller. The returned events can be distributed over several sessions. The max_return_events can be less than expected in the response if the profile does not have enough events or if the profile becomes larger than the max_return_size.


Response Headers

Header

Description

LocationAbsolute url of the newly created canonical profile resource if the merge resulted in the creation of a canonical profile.
Content-typeContent type of the response body.
VaryWill contain the Accept-encoding header.
Content-encoding

Will contain encoding "gzip".


Example: Merging a temporary profile into a canonical profile


Request Body
{
   "id":"<canonicalProfileId>", 
   "mergedProfiles":[
      "<temporaryProfileId>"
   ]
} 
 

Response body
{
   "profile":{
      "id":"<canonicalProfileId>",
      "version":"1.0",
      "createdAt":<timestamp milliseconds>,
      "mergedProfiles":[
         "<temporaryProfileId>"
      ]
   },
   "links":{
      "self":"http://&lt;hostname&gt;/v1/companies/&lt;companyId&gt;/buckets/&lt;bucketId&gt;/profiles/&lt;canonicalProfileId>"
   }
}