REST API

Please note: this set of APIs is scheduled for deprecation in 2017. New implementations should start by using the newly released Evaluation API


A segment can be evaluated if the following preconditions are met

  1.  A segment is created using the segments resource.
  2. The segment is enabled.
  3. The profile on which the segment is to be evaluated exists.

Segment evaluation can be done by making a request to url /v1/companies/<companyId>/buckets/<bucketId>/segment-evaluation. The request should be GET and a successful segment evaluation will result in a 200 OK. The segment-evaluation resource must be called with query parameters profile_id and segment_id.


Required permission segment.evaluation


Request Headers

Header

Required

Acceptable Value(s)

Description

AcceptYesapplication/json
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 parameter

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.
profile_idYesReferences an existing profile.
segment_idYesReferences an existing segment. The segments are created using the Config API's segments resource.
filteredProfileNofilteredProfile can have a value of "true" or "false". If filteredProfile is set to true and the result of the segment evaluation is true, then the response json will contain an additional field called filteredProfile. The filtered profile contains the parts of the profile which matched the segment evaluation.


Example: Response of requesting a Segment Evaluation


Response Body
{
 
   "segment-evaluation":{
      "result":<true|false>
   },
   "links":{
      "self":"http://&lt;hostname&gt;/v1/companies/&lt;companyId&gt;/buckets/&lt;bucketId>/segment-evaluation"
   }
 
}


Example: Response of requesting a Segment Evaluation with filteredProfile set to true and a successful evaluation


Response Body
{
 
   "segment-evaluation":{
      "result":true,
      "filteredProfile":{
         "id":"<profileId>",
         "sessions":[
            ...
         ],
         "attributes":[
            ...
         ]
      }
   },
   "links":{
      "self":"https://&lt;hostname&gt;/v1/companies/&lt;companyId&gt;/buckets/&lt;bucketId>/segment-evaluation"
   }
 
}


Please note: this set of APIs is scheduled for deprecation in 2017. New implementations should start by using the newly released Evaluation API. 


An IQL can be evaluated if the following preconditions are met

  1. The profile on which the IQL is to be evaluated must exist.


IQL evaluation can be done by making a request to url /v1/companies/<companyId>/buckets/<bucketId>/segment-evaluation. The request should be GET and a successful segment evaluation will result in a 200 OK. The segment-evaluation resource must be called with query parameters profile_id and iql.


Request Headers

Header

Required

Acceptable Value(s)

Description

AcceptYesapplication/json
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 parameter

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.
profile_idYesReferences an existing profile.
iqlYesRefers to an IQL expression.
filteredProfileNofilteredProfile can have a value of "true" or "false". If filteredProfile is set to true and the result of the iql evaluation is true, then the response json will contain an additional field called filteredProfile. The filtered profile contains the parts of the profile which matched the iql evaluation.


Example: Response of a requested a IQL Evaluation


Response Body
{
 
   "segment-evaluation":{
      "result":<true|false>
   },
   "links":{
      "self":"http://&lt;hostname&gt;/v1/companies/&lt;companyId&gt;/buckets/&lt;bucketId>/segment-evaluation"
   }
 
}


Example: Response of requesting an IQL Evaluation with filteredProfile set to true and a successful evaluation


Response Body
{
 
   "segment-evaluation":{
      "result":true,
      "filteredProfile":{
         "id":"<profileId>",
         "sessions":[
           ...
         ],
         "attributes":[
           ...
         ]
      }
   },
   "links":{
      "self":"https://&lt;hostname&gt;/v1/companies/&lt;companyId&gt;/buckets/&lt;bucketId>/segment-evaluation"
   }
 
}

Profile locking is used to permanently delete a Profile by clearing its data and preventing any further data inserts to the specified Profile. Normal delete will only wipe the profile contents, but will allow subsequent data inserts.


Whenever a profile exists, it's lock exists. This lock can either be true or false and is false by default. A lock is never created through the API because it is automatically created when the profile is created. The locked is never deleted from the API, it is automatically removed when the profile is removed.

A profile's lock shares the id of the profile. It can be retrieved or updated using the id of the profile. Locks can also be retrieved using the profile's merged ids if any exist. Lock id and profile id are synonyms from the perspective of profile locking.


There are some important points to remember while working with profile locks.

  • When a profile is locked, its sessions, attributes and services are removed. Unlocking a profile will essentially return an empty profile.
  • When a temporary profile is locked and then merged into a canonical profile, the canonical profile will be locked as well. The profile cannot be operated on neither through the temporary profile Id nor the canonical profile Id.
  • When the canonical profile is unlocked, then both the canonical profile id and the temporary profile id(s) can be used to operate on the profile.


Update a Profile Lock

Profile lock can be updated by making a PUT request to /v1/companies/:companyId/buckets/:bucketId/profile-locks/lockId where lockId is the id of the profile. The response if successful will return a status code of 200 OK and an entity with the updated representation of the resource.


Required permission profile.lock.update


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.


Example: Updating a profile lock


Request Body
{
   "id":"<lockId>",
    "lock":<true|false>


Response body
{
    "profileLock":{
       "id":"<lockId>",
       "lock":"<true|false>"
   },
   "links":{
       "self":"<url>"
   }
}



Get a Profile Lock

Profile lock can be retrieved by making a GET request to /v1/companies/:companyId/buckets/:bucketId/profile-locks/lockId where lockId is the id of the profile. The response if successful will return a status code of 200 OK and an entity with the representation of the resource.


Required permission profile.lock.read


Request Headers

Header

Required

Acceptable Value(s)

Description

AcceptYesapplication/json, application/javascript, image/*Image response will return a 1x1 pixel result.
Accept-encodingNogzip

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


Example: Retrieve a profile lock


Response body
{
    "profileLock":{
       "id":"<lockId>",
      "lock":"<true|false>"
   },
   "links":{
       "self":"<url>"
   }
}

Getting a locked profile

Retrieving a locked profile will return a response with the status code 403 FORBIDDEN. Since there are multiple reasons for a 403 FORBIDDEN, therefore, if more detail about why the response was 403 FORBIDDEN is required, then the entity of the response body must be read. The entity contains, the "statusCode", "subStatusCode" and "message" fields. Sub status code for a locked profile will be 2.


Example: Forbidden profile response


Response body

   "statusCode":403,
   "subStatusCode":2,
   "message":"Profile with id <profileId> is locked"
}



The Profile Cloud API provides support for web apis through query parameters. The list of supported query parameters and their description is specified below.


Query parameter

Acceptable values

Description

typejson, jsonp, imgIf type is specified as a query parameter for a request, then the corresponding response will be of that type. The query parameter overrides the Accept HTTP request header.
methodGET, POST, PUT, DELETEIf a method query parameter is specified then the request url will be called with that method. A typical use case would be to override a GET request with a POST, PUT or DELETE
callback<callbackMethodName>callback query parameter is used in conjunction with type=jsonp. The callback query parameter represents the callback method name for jsonp responses. Default value for callback is "callback" or none if type is not jsonp. The response json will be encapsulated as "callback && callback({"...":"...", ...});
data<jsonData>It is possible to specify the json data to be supplied in a request in the request url as data query parameter. Typical use case is to create or update a profile from an <img /> tag which only supports method GET.
limitSize<Int>It is possible to limit the size of the returned profiile by specifying the size of profile in Kilobytes.
returnProfiletrue or falseIt is possible to disable returning of the profile by specifying the returnProfile query parameter. Default value for returnProfile is true.
suppress_response_codetrue or falseIt is possible to always get a 200 OK back from the API by specifying the query paramter suppress_response_code as true. Default value for supress_response_code is false.