Profile API

Introduction

Data Handler API allows clients (browsers, devices etc) to interact with Profile Cloud's backend. The API complies with HTTP/1.1 protocol specifications and follows the REST architectural style as much as possible. This document explains the usage of the API and the related data structures.

IMPORTANT NOTE: This article is not being maintained and is scheduled for sunsetting by end of 2017. Readers are encouraged to use the new API reference here: http://docs.innomdc.com/

API Requirements

The API requires the setup of a "Company" and "Bucket". All profiles exist for a Company and Bucket. We will refer to company, bucket and profile as "<companyId>", "<bucketId>" and "<profileId>" respectively.

API Limits

If Innometrics Profile API receives too much traffic from a single client, it may return a Too Many Requests response. There are limits on total requests sent per second as well as a much stricter limit on number of requests per second to a single profile.

Profile ID requirements

If new profiles are created from a device (web, mobile device or any other connection that is not a secure server-to-server connection) then then UUIDs should be chosen or profile IDs should otherwise chosen from a keyspace with large number of random bits (for instance, web library generates keys with 32 characters a-z0-9, example eser4xdjclozet5rrtqwyfz9rnrjerkg).

Structure of the Profile

A profile has three main parts, namely, "Sessions", "Attributes" and "Services". Each of these in turn have their own structures. The structure of a profile can be represented by the following JSON structure. Please read the Profile Format Specification document for more details about the profile.


The table below describes the profile in further detail

KeyTypeRequiredDescription
idStringYesRepresents a profile. The API expects the "id" to be created by the caller. The "id" should be unique
versionStringNoRepresents the version of profile JSON. The API does not expect it from the caller and will ignore it if supplied.
createdAtNumberNoRepresents the time this profile was created. createdAt can be specified by the client. If no createdAt is specified, the server will add a createdAt value. The createdAt value can never be modified and all future createdAt values will be ignored. This value will be interpreted in milliseconds.
sessionsArray of sessionsNoAn array of sessions.
attributesArray of attributesNoAn array of attributes
servicesArray of servicesNoAn array of services. Some services such as "geo location" will be included in the profile by the API.
mergedProfilesArray of stringsNoId of profiles merged into this profile. Profile merging is a special function that combines multiple temporary profiles into a single canonical profile. Please read the Merge section for more details.

Profile Cloud API

The profile cloud API revolves around the concept of a profile. Using the API, one can do CRUD operations on a profile.

Create a new profile

A new profile can be created from either the profiles resource or profile resource.

  • A new profile can be created by calling the url /v1/companies/<companyId>/buckets/<bucketId>/profiles. The method should be POST and a successful profile creation will result in a response status 201 CREATED
  • This can also be done by calling the url /v1/companies/<companyId>/buckets/<bucketId>/profiles/<profileId>. The method should be POST and a successful profile creation will result in a response status 201 CREATED.


Required permission profile.create

Request Headers

HeaderRequiredAcceptable 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

KeyRequiredDescription
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"
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 /wiki/spaces/DOCS/pages/5079061 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

HeaderDescription
LocationAbsolute url of the newly created resource.
Content-typeContent type of the response body.
VaryWill contain the Accept-encoding header.
Content-encodingWill contain encoding "gzip".


Example 1: A typical request and response body


Example 2: A minimal request and response body

Update a profile

A profile can be updated by calling the url /v1/companies/<companyId>/buckets/<bucketId>/profiles/<profileId>. The method should be POST and a successful profile update will result in a response status 200 OK. The update to a profile is a partial update and any portion of the profile namely "session", "attributes" or "services" can be updated. The resource still takes a profile representation as request body. Sessions, attributes or services in this profile will by inserted into the existing profile. If any session (or events inside a session), attribute or service matches with an existing session (or events inside the session), attribute or service, the exiting will be updated to the new with priority to the new values.


Required permission profile.update

Request Headers

HeaderRequiredAcceptable 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

KeyRequiredDescription
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 /wiki/spaces/DOCS/pages/5079061 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

HeaderDescription
LocationAbsolute url of the newly created resource.
Content-typeContent type of the response body.
VaryWill contain the Accept-encoding header.
Content-encodingWill contain encoding "gzip".


Example 1: Request and response body when updating existing profile with a new session

Assume that a profile represented with the following JSON exists


Then an update is issued on this profile with the following JSON in request body


The resultant JSON for this request will be


Example 2: Request and response body when updating existing profile with an existing session but different event

Assume that a profile represented with the following JSON exists


Then an update is issued on this profile with the following JSON in request body


The resultant JSON for this request will be


Example 3: Request and response body when updating existing profile with an existing session and existing event

Assume that a profile represented with the following JSON exists


Then an update is issued on this profile with the following JSON in request body


The resultant JSON for this request will be

Get an existing profile

An existing profile can be retrieved by calling the url /v1/companies/<companyId>/buckets/<bucketId>/profiles/<profileId>. The method should be GET and a successful profile get will result in a response status 200 OK.


Required permission profile.read

Request Headers

HeaderRequiredAcceptable 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.


Query Parameters

KeyRequiredDescription
app_keyNoAn app key refers to a collectApp. If an app key is specified, only the profile data that was added as the collectApp and the data of those apps that are allowed through the configured whitelist and/or blacklist will be retrieved. If no app key is specified then collectApp web along with its configured whitelist and/or blacklist will be used.
max_return_sizeNo

Max 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 /wiki/spaces/DOCS/pages/5079061 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

HeaderDescription
Content-typeContent type of the response body.
VaryWill contain the Accept-encoding header.
Content-encodingWill contain encoding "gzip".


Example: Get an existing profile

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

HeaderRequiredAcceptable 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

KeyRequiredDescription
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 /wiki/spaces/DOCS/pages/5079061 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

Delete Profiles

A profile can be deleted by calling the url /v1/companies/<companyId>/buckets/<bucketId>/profiles/<profileId>. The method should be DELETE and a successful profile deletion will result in a response status 204 NO CONTENT. A profile can be deleted using it's temporary profile id(s) or it's canonical profile id. Deleting a profile with multiple id(s) (temporary and canonical) will result in the removal of all those ids and corresponding data. These id(s) can be reused to create new profiles. 

Required permission profile.delete

Query Parameters

KeyRequiredDescription
app_keyNo

An app key refers to the app which has the permission to delete profiles. If app key is is not specified that "web" app should have the permission to delete profiles.

Evaluating Segments and IQL

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

Segment Evaluation

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

HeaderRequiredAcceptable 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 parameterRequiredDescription
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


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

IQL Evaluation

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

HeaderRequiredAcceptable 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 parameterRequiredDescription
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


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

Profile Locking

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

HeaderRequiredAcceptable 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

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

HeaderRequiredAcceptable 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

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


API Web support

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 parameterAcceptable valuesDescription
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.