The BlueConic REST API is an interface that provides access to BlueConic visitor profile, segment, and interaction information. Through the API you can retrieve visitor profile information as well as add properties to visitor profiles. BlueConic segments and interaction JavaScript can also be retrieved and events can be posted to a BlueConic session.
OAuth signed requests
Methods in the BlueConic REST API that require authentication must use OAuth signed requests to do so. OAuth is an open standard for authorization of requests. OAuth allows private resources to be shared between two entities without requiring username/password credentials to be supplied. BlueConic implements "two-legged OAuth" in which a client communicates directly with BlueConic and the authentication is accomplished in one step.
BlueConic only supports OAuth version 1.0a with HMAC-SHA1 as signature algorithm in the request headers.
Do not use an OAuth 2.0 library to send signed requests as these are incompatible with BlueConic.
In OAuth, the entity that grants the authorization is known as the provider and the entity requesting the authorization is known as the consumer. Each consumer is assigned a publicly known key known as the Consumer Key. The Consumer Secret, which is private for each individual consumer, paired with their Consumer Key is used to grant the authorization for access to resources. The provider knows what the Consumer Key and Consumer Secret is for each consumer. When a request for authorization is received by the provider, it checks the consumer key and consumer secret in order to verify that resources may be accessed.
Request flow
HTTP requests that require signing typically have the following flow:
- An application generates an HTTP request for BlueConic.
- The OAuth library signs the request and sends it to BlueConic.
- BlueConic's API Access Connection receives the request. Using an OAuth library it validates the request and generates an HTTPS response.
- The HTTPS response is sent to the consumer.

Consumer Secret and Consumer Key configuration
In BlueConic the Consumer Key and Consumer Secret are set up by creating a BlueConic API Access Connection. The application manager that creates this connection needs to send the developer of the external software application this information, so the developer can implement OAuth.
Signing requests
Libraries for signing requests can be downloaded here. A BlueConic java example based on Maven and Eclipse can be downloaded here.
Profile methods
The following methods allow you to create, modify, retrieve properties from and delete BlueConic visitor profiles as well as retrieve BlueConic segment information.
Get one profile
Synopsis |
GET https://yourserver.blueconic.net/rest/profiles/[profile] |
Description |
Retrieves the properties of the specified profile, including the IDs of the matching dynamic segments. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Querystring |
expand |
No |
String |
null |
One of:
- "profile.permissions.exceptions"
- "profile.timeline"
|
Expand the information in the result set. Use "profile.permissions.exceptions" to include permission level and exception data. Use "profile.timeline" to include timeline event information. Use multiple "expand" querystring parameters to return combinations. |
Querystring |
properties |
No |
String |
null |
Comma separated list of profile property IDs. |
Only returns the given profile properties in the response. |
Querystring |
eventTypeId |
No |
String |
null |
ID of the timeline event type. |
Filter returned timeline events for a specific type. Only one timeline event type ID is allowed. |
Querystring |
eventCount |
No |
String |
20 |
any number |
The maximum number of timeline events to return. |
Querystring |
fromDate |
No |
String |
null |
any date |
Filter to only include timeline events that are dated later than this date. The format of fromDate is "2018-01-01T00:00Z" or with a timezone offset "2018-01-01T00:00+05:00" |
Querystring |
toDate |
No |
String |
null |
any date |
Filter to only include timeline events that are dated before this date. The format of toDate is "2018-01-01T00:00Z" or with a timezone offset "2018-01-01T00:00+05:00" |
Querystring |
prettyPrint |
No |
String |
null |
"true" |
Set to "true" to return the JSON result in a readable pretty print format. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the specified profile.
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/profiles/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3?alt=xml&expand=profile.timeline
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id>45e2a650-ca17-4e03-8e8d-12d00ed4d9b3</id>
<privacyLegislation>GDPR</privacyLegislation>
<consentedObjectives>
<objective>
<id>objective_id_1</id>
</objective>
<objective>
<id>objective_id_2</id>
</objective>
</consentedObjectives>
<refusedObjectives>
<objective>
<id>objective_id_3</id>
</objective>
</refusedObjectives>
<properties>
<property>
<id>email</id>
<values>
<value>info@test.com</value>
</values>
</property>
<property>
<id>hobby</id>
<values>
<value>soccer</value>
<value>tennis</value>
</values>
</property>
</properties>
<segments>
<segment>
<id>dd69b76f-8e0d-43bf-bf93-56d05bdcef4e</id>
</segment>
<segment>
<id>50622c8f-de0d-4a25-af0d-e52a26b68f40</id>
</segment>
</segments>
<events>
<event>
<data>
<property>
<id>product</id>
<values>
<value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="propertyWrapper">
<value xmlns:ns3="timeline" xsi:type="ns3:timeline">
<id>listprice</id>
<values>
<value xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:float">12.3</value>
</values>
</value>
<value xmlns:ns3="timeline" xsi:type="ns3:timeline">
<id>netprice</id>
<values>
<value xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:float">11.7</value>
</values>
</value>
<value xmlns:ns3="timeline" xsi:type="ns3:timeline">
<id>id</id>
<values>
<value xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">97b328e8ed2220ceb1b3c52d780aa334</value>
</values>
</value>
</value>
</values>
</property>
</data>
<date>2019-11-29T19:00:51Z</date>
<eventTypeId>order</eventTypeId>
<id>ba1d699eacd13e0e0b71a1a2c0eeb2d1</id>
<source>connection_33e4f51a-44e4-420b-a557-f4ba3b6d1176</source>
</event>
</events>
</profile>
|
Create or update one or more profiles at once
Synopsis |
PUT https://yourserver.blueconic.net/rest/profiles PUT https://yourserver.blueconic.net/rest/profiles?objectiveIds=objectiveID_1,objectiveID_2 |
Description |
Create or update one or more profiles in a single request. This is the recommended way of creating or updating profiles.
The format of this API call is different from other profile APIs: it only accepts a JSON body and it will return a JSON response.
|
Parameters |
The querystring of a profile bulk API request may contain an “objectiveIds” parameter. If present, these objective ID’s are matched against the consented objectives of a profile update, in case the profile is governed by one or more legislation zones.
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
objectiveIds |
No |
String |
null |
Comma separated list of objective IDs. |
A list of ID’s that should map on objectives that are configured in the BlueConic UI. If passed, the profiles to be updated that are in the privacy legislation zone are matched against these objectives. If there is no match, the profile won’t be updated (or created, for that matter).
If a profile would have been created/updated, but is skipped because of an objective mismatch, the response will contain a “CONSENT_MISMATCH” state for that profile.
|
The body of a profile bulk API request consists of an array of profile operation objects. A single profile operation object (i.e. one object in the parameters array) may have the following parameters:
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
identifier |
No |
String |
null |
any value |
An (external) identifier which can be passed along with an operation and is returned in the response. |
matching |
No |
Object[][] |
null |
[[{id: "email", value: "test@test.com"}]] |
The profile properties to match. Only profile properties marked as "Unique Identifier" can be used. This is an array of arrays; the items in the outer array have an "OR" relation, the items in the inner array have an "AND" relation. |
profileId |
No |
String |
null |
any BlueConic profile ID |
The profile ID to search for. When used, it overrides possible matching criteria. |
create |
No |
Boolean |
"false" |
"true", "false" |
When true, creates a new profile if no profile is found matching the given criteria. |
domainGroup |
No |
String |
"DEFAULT" |
any domaingroup ID |
Specifies the domain group in which a profile is created. Used for matching and creating profiles. |
permissionLevel |
No |
String |
Default permission level of privacy tab |
"PERSONAL", "ANONYMOUS", "DO_NOT_TRACK" |
The permission used for creating profiles (not for matching). |
privacyLegislation |
No |
String |
null |
One of the privacy legislation zone values |
The default privacy legislation for creating profiles (not for matching). |
restriction |
No |
Object |
null |
"isMemberOfSegment": Any segment UUID |
The possible restriction rules when matching profiles. Only "isMemberOfSegment" is available at the moment. |
properties |
No |
Object[] |
null |
[ { "id": "myproperty1", "values": ["value1", "value2"], "strategy": "ADD" } ] |
The rules that will be executed on this profile. Strategy must be one of the following types: - ADD - SET - SET_IF_EMPTY - SUM - REMOVE
The following properties have a special meaning: “privacy_legislation”: the value passed in this property should be one of the privacy legislation zone values, and is used to determine if a profile should be matched against the passed “objectiveIds” in the querystring.
“consented_objectives”: the value(s) passed in this property are used to match against the passed “objectiveIds” in the querystring. At least one must match in order for the profile to be created/updated, otherwise “CONSENT_MISMATCH” is returned. “refused_objectives”: ”: the value(s) passed in this property are used to set the explicitly refused objectives
|
timeline |
No |
Object[] |
null |
[Event data 1, Event data 2, ...] (see below) |
The events that will be added to the event timeline for this profile. |
Events
Events are data points tied to the BlueConic Timeline of a profile, e.g. an order the customer placed. BlueConic comes out of the box with several predefined BlueConic Timeline event types. Events can be HIGH or LOW priority. There is a maximum number of 250 events per profile allowed. LOW priority events have a time to live of 30 days. HIGH priority events are constrained by the total number of events and take precedence over LOW priority events, which are capped at 50 if there are 200 or more HIGH priority events.
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
id |
No |
String |
null |
any value |
An identifier to identify the event. Preferred to be unique, although it isn't required to be. If an event with the same ID is present on the profile's timeline, it will be overwritten. Note that the combination of ID, event type ID, and date uniquely identifies an event. |
eventTypeId |
Yes |
String |
null |
any event type id that is defined in BlueConic |
The type identifier of the event. See https://yourserver.blueconic.net/rest/timelineEventTypes?alt=json for the list of defined event types. |
source |
No |
String |
null |
any value |
A string to identify the source of the data. Will be set by BlueConic when known, e.g. when events are imported by a connection. |
data |
Yes |
Object[] |
null |
Data structure has to match the definition of the timeline event type |
The event data as structured data. See Event data below. |
strategy |
Yes |
String |
null |
Has to be specified. Only "SET" is currently supported. |
How the event will be applied to the timeline. |
date |
No |
String |
Now |
|
Timestamp for the event. The format of date is "2018-01-01T00:00Z" or with a timezone offset "2018-01-01T00:00+05:00". If empty, "now" will be used. |
Event data
Event data is structured to the definition of the timeline event type (see https://yourserver.blueconic.net/rest/timelineEventTypes?alt=json). Simplified for brevity, a timeline event type definition will look something like this:
{ "fieldTypes": [ { "key": "product", "values": { "value": [ { "key": "quantity", "values": {"value": "NUMBER"} }, { "key": "netprice", "values": {"value": "DECIMAL"} }, { "key": "coupon", "values": {"value": "TEXT"} }, { "key": "deliverydate", "values": {"value": "DATETIME"} } ] } }, { "key": "quantity", "values": {"value": "NUMBER"} } ], "id": "order", "name": "Order", "priority": "HIGH" }
There are field types that contain key value pairs which can be nested. The data structure of the order event above boils down to something like this:
- product
- quantity: NUMBER
- netprice: DECIMAL
- coupon: TEXT
- deliverydate: DATETIME
- quantity: NUMBER
This then maps to the JSON event data structure to be used as value for "data". The recipe is to keep the same definition JSON structure in place, then replace "key" with "id", and replace the type string by the actual data point (e.g. replace "NUMBER" by 2, and "DECIMAL" by 3.45). Key value pairs are not mandatory and may be omitted.
{
"id": "eb20c911-4d23-4791-a3e7-d113e7a326d9",
"eventTypeId": "order",
"data": [{
"id": "product",
"values": {
"value": [
[{
"id": "quantity",
"values": {
"value": [2]
}
}, {
"id": "netprice",
"values": {
"value": [3.45]
}
}, {
"id": "coupon",
"values": {
"value": ["FREETV"]
}
}, {
"id": "deliverydate",
"values": {
"value": ["2020-01-23T23:45:56.789Z"]
}
}]
]
}
}, {
"id": "quantity",
"values": {
"value": [1]
}
}],
"strategy": "SET"
}
Privacy legislation
Any “objectiveIds” passed in the querystring are matched against the profile that is being created.
Matching is done against the special profile property “consented_objectives”, which reflects the objective IDs that the profile has explicitly consented to. So, for the profile to be created, the “properties” should at least contain one of the objective IDs passed in the querystring, for the property with id “consented_objectives”. Otherwise, the “CONSENT_MISMATCH” state is returned in the response.
The following values are valid privacy legislation zone values.
Name |
Description |
CCPA |
Indicates that a profile is governed by CCPA in the state of California. |
GDPR |
Indicates that a profile is governed by GDPR in Europe. |
NYPA |
Indicates that a profile is governed by NYPA in the state of New York. |
PIPEDA |
Indicates that a profile is governed by PIPEDA in Canada. |
SB220 |
Indicates that a profile is governed by SB220 in the state of Nevada. |
NONE |
The profile is not governed by a known privacy legislation zone; profile will just be created. |
Strategy
The following values are valid property rule strategies.
Name |
Description |
ADD |
Values will be added to the values that already existed in the profile property. Duplicates will not be added. |
SET |
Values will overwrite the values that already existed in the profile property. |
SET_IF_EMPTY |
Only set values if the profile property is empty. |
SUM |
Add the value to the value already stored in the profile property. |
REMOVE |
Remove the value from the list of values already stored in the profile property. |
|
Authentication |
Yes |
Responses |
- 200 - Returns a summary of the executed bulk request.
- 400 - The specified body is not valid.
- 401 - Authentication failed (unauthorized).
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/profiles?alt=json
Request body
[{
"profileId": "dd9ba129-017f-4c54-bde9-22e66a46df28",
"properties": [{
"id": "crm_id",
"values": ["003Kz4Bsaa14"],
"strategy": "SET"
}]
},
{
"matching": [
[{
"id": "email",
"value": "jane@example.com"
}],
[{
"id": "crm_id",
"value": "002wC4BadR1w"
}]
],
"properties": [{
"id": "zipcode",
"values": ["02111", "02112"],
"strategy": "ADD"
},
{
"id": "email",
"values": ["jane@example.com"],
"strategy": "SET"
},
{
"id": "crm_id",
"values": ["002wC4BadR1w"],
"strategy": "SET"
}],
"timeline": [{
"id": "eb20c911-4d23-4791-a3e7-d113e7a326d9",
"eventTypeId": "order",
"data": [{
"id": "product",
"values": {
"value": [
[{
"id": "quantity",
"values": {
"value": [2]
}
}, {
"id": "netprice",
"values": {
"value": [3.45]
}
}, {
"id": "coupon",
"values": {
"value": ["FREETV"]
}
}, {
"id": "deliverydate",
"values": {
"value": ["2020-01-23T23:45:56.789Z"]
}
}]
]
}
}, {
"id": "quantity",
"values": {
"value": [1]
}
}],
"strategy": "SET"
}],
"create": "true",
"domainGroup": "2a9ba2ea-011c-4c2d-ada9-62e2a4b1df2b"
}]
This request contains two operations:
- The first operation looks up a specific BlueConic profile by its id, then sets the property with id crm_id to 003Kz4Bsaa14. If the profile cannot be found, nothing will happen.
- The second operation tries to find profiles that either have an email address jane@example.com or a crm_id of 002wC4BadR1w in the specified domain. If any profile is found, three properties will be set:
- Zip codes 02111 and 02112 will be added
- Email address will be set to jane@example.com
- crm_id will be set to 002wC4BadR1w
Also an order event will be added to the timeline for an order of quantity 2, net price 3.45, coupon "FREETV" and delivery date 23/1/2020 at 11:45 PM. If no match can be found, a new profile is created in the specified domain, the three properties will be set in it and the order event will be added to the timeline.
JSON Response
Every bulk operation is returned in the response as well. The state can be one of the following values: "CREATED", "MODIFIED", "UNCHANGED", "NOTFOUND", "RESTRICTION_MISMATCH" or “CONSENT_MISMATCH”.
[{
"state": "CREATED",
"profileId": "profile-UUID of the created profile",
"identifier": " my-external-identifier"
}]
|
Delete one profile
Synopsis |
DELETE https://yourserver.blueconic.net/rest/profiles/[profile] |
Description |
Deletes the specified BlueConic profile. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the deleted profile.
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
DELETE https://yourserver.blueconic.net/rest/profiles/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3?alt=xml
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id>45e2a650-ca17-4e03-8e8d-12d00ed4d9b3</id>
<properties>
<property>
<id>email</id>
<values>
<value>info@test.com</value>
</values>
</property>
<property>
<id>hobby</id>
<values>
<value>soccer</value>
<value>tennis</value>
</values>
</property>
</properties>
<segments>
<segment>
<id>dd69b76f-8e0d-43bf-bf93-56d05bdcef4e</id>
</segment>
<segment>
<id>50622c8f-de0d-4a25-af0d-e52a26b68f40</id>
</segment>
</segments>
</profile>
|
Create one new profile
Synopsis |
POST https://yourserver.blueconic.net/rest/profiles |
Description |
Creates one new empty BlueConic profile. We recommend you use the method Create or update one or more profiles (bulk) instead, as it allows you to not only create one or more new profiles, but also provide them with values at the same time. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
domainGroupId |
No |
String |
"DEFAULT" |
|
Specifies the domain group to use when creating the new profile |
|
Authentication |
Yes |
Responses |
- 200 - Returns the created profile.
- 401 - Authentication failed (unauthorized).
- 503 - The server is too busy to handle the request.
|
Example |
Request
POST https://yourserver.blueconic.net/rest/profiles?alt=xml
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id>9efb8a28-bfdf-4a10-b4f4-c0fb3a9a8dcc</id>
<properties />
<segments>
<segment>
<id>e83a67ea-1cf6-4af5-aa6d-09666d7d7781</id>
</segment>
</segments>
</profile>
|
Replace a profile
Synopsis |
PUT https://yourserver.blueconic.net/rest/profiles/[profile] |
Description |
Replaces an existing BlueConic profile using the replaceBy parameter. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
replaceBy |
No |
String |
null |
any UUID |
The ID of the profile that replaces this profile. All future requests for the profile ID containing the replaceBy property will be routed to the "replace by" profile ID. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the updated profile.
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/profiles/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3?alt=xml
replaceBy=1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id>45e2a650-ca17-4e03-8e8d-12d00ed4d9b3</id>
<replaceBy>
<profile>
<id>d1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6</id>
</profile>
</replaceBy>
<properties />
<segments />
</profile>
|
Set the permission level of a profile
Synopsis |
PUT https://yourserver.blueconic.net/rest/profiles/[profile]/permissions |
Description |
Updates the permission level of a profile. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
level |
Yes |
String |
null |
"ANONYMOUS", "PERSONAL" |
The level to set. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the updated profile.
- 400 - One or more required parameters is missing or invalid.
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/profiles/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3/permissions?alt=xml
level=PERSONAL
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id>45e2a650-ca17-4e03-8e8d-12d00ed4d9b3</id>
<permissions>
<level>PERSONAL</level>
</permissions>
<properties />
<segments />
</profile>
|
Set the permission level exceptions of a profile
Synopsis |
PUT https://yourserver.blueconic.net/rest/profiles/[profile]/permissions/permissions/exceptions/[mode]/[type] |
Description |
Updates the permission level exceptions of a profile. Plugin IDs and profile property IDs can be used to optin or optout for the usage of them. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Path |
mode |
Yes |
String |
null |
optIn, optOut |
Specifies optin or optout. |
Path |
type |
Yes |
String |
null |
plugins, profileProperties |
Specifies the type of the exception. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
ids |
Yes |
String |
null |
any UUID |
The ids of the exceptions to set. |
|
Authentication |
Yes |
Responses |
- 200 - No specific content.
- 400 - One or more required parameters is missing or invalid.
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/profiles/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3/permissions/exceptions/optIn/plugins
ids=plugin1&ids=plugin2
|
Search for profiles
Synopsis |
GET https://yourserver.blueconic.net/rest/profiles |
Description |
Searches for BlueConic profiles based on a specific values for an indexed (unique) properties. Multiple name/value pairs can be used to refine the search. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Querystring |
property |
Yes |
String |
null |
any String |
Specifies the id of property to search for ("email" for example). |
Querystring |
value |
Yes |
String |
null |
any String |
The value of the property to search for ("john.smith@blueconic.com" for example). |
|
Authentication |
Yes |
Responses |
- 200 - Returns the ID of the top 100 matching profiles.
- 400 - One or more required parameters is missing or invalid.
- 401 - Authentication failed (unauthorized).
- 501 - The specified property is not classified as indexed (unique) (not implemented).
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/profiles?property=email&value=john.smith@blueconic.com&alt=xml
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profiles total="2">
<profile>
<id>61835134-e910-49da-a09e-79d41af9b96</id>
</profile>
<profile>
<id>45e2a650-ca17-4e03-8e8d-12d00ed4d9b3</id>
</profile>
<itemsPerPage>1</itemsPerPage>
<startIndex>0</startIndex>
<totalPages>1</totalPages>
<totalResults>1</totalResults>
</profiles>
|
Get timeline events for one profile
Synopsis |
GET https://yourserver.blueconic.net/rest/profiles/[profile]/timeline |
Description |
Retrieves timeline events for the specified profile. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Querystring |
eventTypeId |
No |
String |
null |
ID of the timeline event type. |
Filter returned timeline events for a specific type. Only one timeline event type ID is allowed. |
Querystring |
count |
No |
String |
20 |
any number |
The maximum number of timeline events to return. |
Querystring |
fromDate |
No |
String |
null |
any date |
Filter to only include timeline events that are dated later than this date. The format of fromDate is "2018-01-01T00:00Z" or with a timezone offset "2018-01-01T00:00+05:00" |
Querystring |
toDate |
No |
String |
null |
any date |
Filter to only include timeline events that are dated before this date. The format of toDate is "2018-01-01T00:00Z" or with a timezone offset "2018-01-01T00:00+05:00" |
Querystring |
prettyPrint |
No |
String |
null |
"true" |
Set to "true" to return the JSON result in a readable pretty print format. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the ID of the top 100 matching profiles.
- 400 - One or more required parameters is missing or invalid.
- 401 - Authentication failed (unauthorized).
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/profiles/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3?alt=xml
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileTimeline>
<events>
<event>
<data>
<property>
<id>product</id>
<values>
<value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="propertyWrapper">
<value xmlns:ns3="timeline" xsi:type="ns3:timeline">
<id>listprice</id>
<values>
<value xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:float">12.3</value>
</values>
</value>
<value xmlns:ns3="timeline" xsi:type="ns3:timeline">
<id>netprice</id>
<values>
<value xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:float">11.7</value>
</values>
</value>
<value xmlns:ns3="timeline" xsi:type="ns3:timeline">
<id>id</id>
<values>
<value xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">97b328e8ed2220ceb1b3c52d780aa334</value>
</values>
</value>
</value>
</values>
</property>
</data>
<date>2019-11-29T19:00:51Z</date>
<eventTypeId>order</eventTypeId>
<id>ba1d699eacd13e0e0b71a1a2c0eeb2d1</id>
<source>connection_33e4f51a-44e4-420b-a557-f4ba3b6d1176</source>
</event>
</events>
</profileTimeline>
|
Profile Event methods
The following methods allow you to retrieve profile event information.
Get events for a profile
Synopsis |
GET https://yourserver.blueconic.net/rest/profileEvents/[profile] |
Description |
Retrieves the events of a profile. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the events.
- 401 - Authentication failed (unauthorized).
- 404 - The profile never existed.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/profileEvents/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileEvents>
<events>
<itemsPerPage>20</itemsPerPage>
<startIndex>0</startIndex>
<totalPages>1</totalPages>
<totalResults>1</totalResults>
<event>
<date>2012-08-17T14:31+0200</date>
<properties>
<property>
<id>ToLevel</id>
<values>
<value>ANONYMOUS</value>
</values>
</property>
<property>
<id>FromLevel</id>
<values>
<value>PERSONAL</value>
</values>
</property>
</properties>
<type>PermissionLevelChanged</type>
</event>
</events>
<profile>
<id>7bce7bfe-f433-4be4-82f2-5018c6dff5b2</id>
</profile>
</profileEvents>
|
Interaction methods
The following methods allow you to retrieve and post interaction event information.
Get interactions
Synopsis |
GET https://yourserver.blueconic.net/rest/interactions |
Description |
Retrieves the interactions for a page view. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Querystring |
url |
Yes |
String |
null |
any URL |
The URL of the current page. |
Querystring |
profile |
No |
String |
null |
any UUID |
The ID of the profile. |
|
Authentication |
No |
Responses |
- 200 - Returns the interactions.
- 400 - One or more required parameters is missing or invalid.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/interactions?profile=45e2a650-ca17-4e03-8e8d-12d00ed4d9b3&url=http%3A%2F%2Fwww.example.com%2F
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<interactions total="2">
<interaction>
<defaultLocale>nl_NL</defaultLocale>
<id>6d2dc916-08ce-412f-aa5d-f75eb95f8a9c</id>
<name>Sample Interactions</name>
<parameters>
<parameter>
<id>sampleparameter</id>
<values locale="en_US">
<value>en 1</value>
<value>en 2</value>
</values>
<values locale="nl_NL">
<value>dutch</value>
</values>
</parameter>
<parameter>
<id>width</id>
<values locale="en_US">
<value>800</value>
</values>
<values locale="nl_NL">
<value>800</value>
</values>
</parameter>
</parameters>
<position>position_1</position>
</interaction>
<interaction>
<defaultLocale>nl_NL</defaultLocale>
<id>demolistenerinteractiontype</id>
<name>demolistenerinteractiontype</name>
</interaction>
</interactions>
|
Register pageview events
Synopsis |
POST https://yourserver.blueconic.net/rest/pageviewEvents |
Description |
Registers pageview events for reporting. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Form |
url |
Yes |
String |
null |
any URL |
The URL of the current page. |
Form |
referrer |
No |
String |
null |
any URL |
The URL of the previous (referring) page. |
Form |
profile |
No |
String |
null |
any UUID |
The ID of the profile that triggered the event. For this profile, the properties "firstvisit", "visiteddomain" and "visitedchannel" are updated. |
|
Authentication |
No |
Responses |
- 200 - No specific content.
- 400 - One or more required parameters is missing or invalid.
- 503 - The server is too busy to handle the request.
|
Register interaction events
Synopsis |
POST https://yourserver.blueconic.net/rest/interactionEvents |
Description |
Registers interaction events for reporting. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
type |
Yes |
String |
null |
"VIEW", "CLICK", "CONVERSION" |
The event type. |
Querystring |
interaction |
Yes |
String |
null |
any UUID |
The ID of the interaction. |
Querystring |
url |
Yes |
String |
null |
any URL |
The URL of the current page. |
|
Authentication |
No |
Responses |
- 200 - No specific content.
- 400 - One or more required parameters is missing or invalid.
- 503 - The server is too busy to handle the request.
|
URL mapping methods
The following methods allow you to retrieve and post URL mapping information.
Create new URL mapping
Synopsis |
POST https://yourserver.blueconic.net/rest/urlmappings |
Description |
Creates a new URL mapping. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
url |
Yes |
String |
null |
any URL |
The target URL of the mapping. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the created urlmapping.
- 400 - One or more required parameters is missing or invalid.
- 401 - Authentication failed (unauthorized).
- 503 - The server is too busy to handle the request.
|
Example |
Request
POST https://yourserver/rest/urlmappings?alt=xml
url=http%3A%2F%2Fwww.example.com
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<urlmapping>
<id>4Q</id>
<properties />
<url>http://www.example.com</url>
</urlmapping>
|
Get one URL mapping
Synopsis |
GET https://yourserver.blueconic.net/rest/urlmappings/[urlmapping] |
Description |
Retrieves the metadata of the specified URL mapping. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
urlmapping |
Yes |
String |
null |
any UUID |
The ID of the URL mapping. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the urlmapping.
- 401 - Authentication failed (unauthorized).
- 404 - The specified URL mapping doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/urlmappings/4Q
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<urlmapping>
<id>4Q</id>
<properties />
<url>http://www.example.com</url>
</urlmapping>
|
Update URL mapping properties
Synopsis |
PUT https://yourserver.blueconic.net/rest/urlmappings/[urlmapping]/properties |
Description |
Updates the stored properties of the specified URL mapping. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
urlmapping |
Yes |
String |
null |
any UUID |
The ID of the URL mapping. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
property=value |
Yes |
String |
null |
any name-value pair |
The property and value to set, multiple values for properties are allowed. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the urlmapping.
- 401 - Authentication failed (unauthorized).
- 404 - The specified URL mapping doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/urlmappings/4Q/properties?alt=xml
property1=value1&property1=value2&property2=value3
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<urlmapping>
<id>4Q</id>
<properties>
<property>
<id>property1</id>
<values>
<value>value1</value>
<value>value2</value>
</values>
</property>
<property>
<id>property2</id>
<values>
<value>value3</value>
</values>
</property>
</properties>
<url>http://www.example.com</url>
</urlmapping>
|
Domain methods
The following methods allow you to create, modify, retrieve properties from and delete BlueConic domains, channels and positions.
Get all domains
Synopsis |
GET https://yourserver.blueconic.net/rest/domains |
Description |
Retrieves the domains. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Querystring |
startIndex |
No |
String |
0 |
any number |
Specifies the index of the first item to include in the result. |
Querystring |
count |
No |
String |
20 |
any number |
Specifies the number of results to return. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the domains.
- 401 - Authentication failed (unauthorized).
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/domains
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains>
<itemsPerPage>20</itemsPerPage>
<startIndex>0</startIndex>
<totalPages>1</totalPages>
<totalResults>1</totalResults>
<domain>
<channels>
<channel>
<aliases>
<alias>alias2</alias>
<alias>alias3</alias>
<alias>alias1</alias>
</aliases>
<hostname>www.example.com</hostname>
<id>da94cd6a-c741-4962-9feb-492fed796b26</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326
/channels/da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>Example channel</name>
<type>WEBSITE</type>
<visitorCount>0</visitorCount>
</channel>
</channels>
<id>885f0954-fd4e-4a08-a987-e2a047c9f326</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<logo>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/logo
?etag=005310aba7fd1ef3ff0223ca166b9c
</href>
<rel>self</rel>
</link>
</logo>
<name>Test domain 1327052341899</name>
<visitorCount>0</visitorCount>
</domain>
</domains>
|
Get one domain
Synopsis |
GET https://yourserver.blueconic.net/rest/domains/[domainid] |
Description |
Retrieves a single domain. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the domain.
- 401 - Authentication failed (unauthorized).
- 404 - The domain doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain>
<channels />
<id>bf6af51d-b077-4565-9bac-8a97d42f807c</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<logo />
<name>Example domain 2</name>
<visitorCount>0</visitorCount>
</domain>
|
Create new domain
Synopsis |
POST https://yourserver.blueconic.net/rest/domains |
Description |
Creates a domain. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
name |
No |
String |
null |
any String |
The name of the domain. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the created domain.
- 401 - Authentication failed (unauthorized).
- 503 - The server is too busy to handle the request.
|
Example |
Request
POST https://yourserver.blueconic.net/rest/domains
name=Example+domain
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain>
<channels />
<id>bf6af51d-b077-4565-9bac-8a97d42f807c</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<logo />
<name>Example domain</name>
<visitorCount>0</visitorCount>
</domain>
|
Update a domain
Synopsis |
PUT https://yourserver.blueconic.net/rest/domains/[domain] |
Description |
Updates a domain. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domain |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
name |
No |
String |
null |
any String |
The name of the domain. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the updated domain.
- 401 - Authentication failed (unauthorized).
- 404 - The domain doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c
name=Example+domain+2
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain>
<channels />
<id>bf6af51d-b077-4565-9bac-8a97d42f807c</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<logo />
<name>Example domain 2</name>
<group>9efb8a28-bfdf-4a10-b4f4-c0fb3a9a8dcc</group>
<visitorCount>0</visitorCount>
</domain>
|
Delete a domain
Synopsis |
DELETE https://yourserver.blueconic.net/rest/domains/[domainid] |
Description |
Updates a domain. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the deleted domain.
- 401 - Authentication failed (unauthorized).
- 404 - The domain doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
DELETE https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain>
<channels />
<id>bf6af51d-b077-4565-9bac-8a97d42f807c</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<logo />
<name>Example domain 2</name>
<visitorCount>0</visitorCount>
</domain>
|
Get channels of a domain
Synopsis |
GET https://yourserver.blueconic.net/rest/domains/[domainid]/channels |
Description |
Retrieves all channels of a domain. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns all channels.
- 401 - Authentication failed (unauthorized).
- 404 - The domain doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<channels>
<channel>
<aliases>
<alias>alias2</alias>
<alias>alias3</alias>
<alias>alias1</alias>
</aliases>
<hostname>www.example.com</hostname>
<id>da94cd6a-c741-4962-9feb-492fed796b26</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326
/channels/da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>Example channel</name>
<positions>
<position>
<id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
</position>
</positions>
<type>WEBSITE</type>
<visitorCount>0</visitorCount>
</channel>
</channels>
|
Get one channel
Synopsis |
GET https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid] |
Description |
Retrieves a single channel. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Path |
channelid |
Yes |
String |
null |
any UUID |
The ID of the channel. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the channel.
- 401 - Authentication failed (unauthorized).
- 404 - The channel doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<channel>
<aliases>
<alias>alias2</alias>
<alias>alias3</alias>
<alias>alias1</alias>
</aliases>
<hostname>www.example.com</hostname>
<id>da94cd6a-c741-4962-9feb-492fed796b26</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>Example channel</name>
<positions>
<position>
<id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
</position>
</positions>
<type>WEBSITE</type>
<visitorCount>0</visitorCount>
</channel>
|
Create new channel
Synopsis |
POST https://yourserver.blueconic.net/rest/domains/[domainid]/channels |
Description |
Creates a channel. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
name |
No |
String |
null |
any String |
The name of the channel. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the created channel.
- 401 - Authentication failed (unauthorized).
- 404 - The domain doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
POST https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
name=Example+channel
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<channel>
<aliases/>
<id>da94cd6a-c741-4962-9feb-492fed796b26</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>Example channel</name>
<positions/>
<type>WEBSITE</type>
<visitorCount>0</visitorCount>
</channel>
|
Update a channel
Synopsis |
PUT https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid] |
Description |
Updates a channel. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Path |
channelid |
Yes |
String |
null |
any UUID |
The ID of the channel. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
name |
No |
String |
null |
any String |
The name of the channel. |
Form |
type |
No |
String |
null |
"WEBSITE", "EMAIL", "TWITTER", or "FACEBOOK" |
The type of the domain. |
Form |
hostname |
No |
String |
null |
any String |
The hostname of the channel. |
Form |
alias |
No |
String |
null |
any String |
The zero or more aliases of the channel. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the updated channel.
- 400 - An invalid channel type was specified.
- 401 - Authentication failed (unauthorized).
- 404 - The channel doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26
name=Example+channel&type=WEBSITE&hostname=www.example.com&alias=alias1&alias=alias2&alias=alias3
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<channel>
<aliases>
<alias>alias2</alias>
<alias>alias3</alias>
<alias>alias1</alias>
</aliases>
<hostname>www.example.com</hostname>
<id>da94cd6a-c741-4962-9feb-492fed796b26</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>Example channel</name>
<positions>
<position>
<id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
</position>
</positions>
<type>WEBSITE</type>
<visitorCount>0</visitorCount>
</channel>
|
Delete a channel
Synopsis |
DELETE https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid] |
Description |
Deletes a channel. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Path |
channelid |
Yes |
String |
null |
any UUID |
The ID of the channel. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the deleted channel.
- 401 - Authentication failed (unauthorized).
- 404 - The channel doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
DELETE https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<channel>
<aliases>
<alias>alias2</alias>
<alias>alias3</alias>
<alias>alias1</alias>
</aliases>
<hostname>www.example.com</hostname>
<id>da94cd6a-c741-4962-9feb-492fed796b26</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>Example channel</name>
<positions>
<position>
<id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
</position>
</positions>
<type>WEBSITE</type>
<visitorCount>0</visitorCount>
</channel>
|
Get positions of a channel
Synopsis |
GET https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]/positions |
Description |
Retrieves all positions of a channel. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Path |
channelid |
Yes |
String |
null |
any UUID |
The ID of the channel. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns all positions of a channel.
- 401 - Authentication failed (unauthorized).
- 404 - The channel doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26/positions
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<positions>
<position>
<id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>New position</name>
</position>
<position>
<id>c3633c12-8ed4-45c7-ac31-d95921648189</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26/positions/c3633c12-8ed4-45c7-ac31-d95921648189?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>New position</name>
</position>
</positions>
|
Get one position
Synopsis |
GET https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]/positions/[positionid] |
Description |
Retrieves a single position. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Path |
channelid |
Yes |
String |
null |
any UUID |
The ID of the channel. |
Path |
positionid |
Yes |
String |
null |
any UUID |
The ID of the position. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the position.
- 401 - Authentication failed (unauthorized).
- 404 - The position doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<position>
<id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>Banner 01</name>
<positionIdentifier>banner01</positionIdentifier>
</position>
|
Create new position
Synopsis |
POST https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]/positions |
Description |
Creates a position. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Path |
channelid |
Yes |
String |
null |
any UUID |
The ID of the channel. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
name |
No |
String |
null |
any String |
The name of the position. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the created position.
- 401 - Authentication failed (unauthorized).
- 404 - The channel doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
POST https://yourserver.blueconic.com/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26/positions
name=Banner+01
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<position>
<id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>Banner 01</name>
</position>
|
Update a position
Synopsis |
PUT https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]/positions/[positionid] |
Description |
Updates a position. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Path |
channelid |
Yes |
String |
null |
any UUID |
The ID of the channel. |
Path |
positionid |
Yes |
String |
null |
any UUID |
The ID of the position. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
name |
No |
String |
null |
any String |
The name of the position. |
Form |
positionIdentifier |
No |
String |
null |
any String |
The identifier of the position, e.g. the ID of a DIV. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the updated position.
- 401 - Authentication failed (unauthorized).
- 404 - The position doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2
name=Banner+01&positionIdentifier=banner01
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<position>
<id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>Banner 01</name>
<positionIdentifier>banner01</positionIdentifier>
</position>
|
Delete a position
Synopsis |
DELETE https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]/positions/[positionid] |
Description |
Updates a position. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
domainid |
Yes |
String |
null |
any UUID |
The ID of the domain. |
Path |
channelid |
Yes |
String |
null |
any UUID |
The ID of the channel. |
Path |
positionid |
Yes |
String |
null |
any UUID |
The ID of the position. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the deleted position.
- 401 - Authentication failed (unauthorized).
- 404 - The position doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
DELETE https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<position>
<id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
</href>
<rel>self</rel>
<type>xml</type>
</link>
</links>
<name>Banner 01</name>
<positionIdentifier>banner01</positionIdentifier>
</position>
|
Profile property methods
The following methods allow you to retrieve profile properties.
Get all profile properties
Synopsis |
GET https://yourserver.blueconic.net/rest/profileProperties |
Description |
Retrieves the profile properties. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Querystring |
count |
No |
String |
20 |
any integer |
Specifies the number of results to return. |
Querystring |
startIndex |
No |
String |
0 |
any integer |
Specifies the index of the first item to include in the result. |
Querystring |
filterType |
No |
String |
no filtering |
"SELECT", "RANGE", "DATETIME" |
The filterType of the profile properties e.g "SELECT", "RANGE" AND "DATETIME". Multiple values are allowed. |
Querystring |
filterValue |
No |
String |
no filtering |
any filter |
If specified, a label of the name of the profile properties must match the value. The label with the matching filterLocale is used. If this is not specified, then all name labels are checked. If no labels exist, then the id is checked. |
Querystring |
filterLocale |
No |
String |
all locales |
any locale |
The locale for filtering on the name label, e.g. "nl_NL" or "en_US". |
|
Authentication |
Yes |
Responses |
- 200 - Returns the profile properties.
- 401 - Authentication failed (unauthorized).
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/profileProperties?startIndex=4&count=2
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileProperties>
<itemsPerPage>2</itemsPerPage>
<startIndex>4</startIndex>
<totalPages>14</totalPages>
<totalResults>27</totalResults>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/profileProperties?startIndex=4&count=2&alt=application/json
</href>
<rel>alt</rel>
<type>application/json</type>
</link>
</links>
<profileProperty>
<filterType>SELECT</filterType>
<id>osversion</id>
<indexed>false</indexed>
<name>
<label locale="en_US">Operating System Version</label>
<label locale="nl_NL">Operating systeem versie</label>
</name>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/profileProperties/osversion?alt=application/xml
</href>
<rel>self</rel>
<type>application/xml</type>
</link>
</links>
</profileProperty>
<profileProperty>
<description>
<label locale="en_US">
The total number of times a website visitor has viewed a web page in your universe during the
current visit.
</label>
<label locale="nl_NL">
Het aantal keer dat de website bezoeker een webpagina binnen het universum heeft bezocht binnen
het huidige bezoek dat hij brengt.
</label>
</description>
<filterType>RANGE</filterType>
<id>visitclicks</id>
<indexed>false</indexed>
<name>
<label locale="nl_NL">Pagina impressies (huidig bezoek)</label>
<label locale="en_US">Page Views (current visit)</label>
</name>
<unit>
<id>views</id>
<name>
<label locale="nl_NL">Impressies</label>
<label locale="en_US">Views</label>
</name>
</unit>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/profileProperties/visitclicks?alt=application/xml
</href>
<rel>self</rel>
<type>application/xml</type>
</link>
</links>
</profileProperty>
</profileProperties>
|
Get one profile property
Synopsis |
GET https://yourserver.blueconic.net/rest/profileProperties/[id] |
Description |
Retrieves a single profile property. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
id |
Yes |
String |
None |
any id |
The ID of the profile property. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the profile property.
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile property doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/profileProperties/clickcount
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileProperty>
<description>
<label locale="en_US">
The total number of times a website visitor has viewed a web page in your universe during all visits
(metered over time).
</label>
<label locale="nl_NL">
Het aantal keer dat de website bezoeker een webpagina binnen het universum heeft bezocht
(gemeten over alle bezoeken).
</label>
</description>
<filterType>RANGE</filterType>
<id>clickcount</id>
<indexed>false</indexed>
<name>
<label locale="en_US">Page Views (all visits)</label>
<label locale="nl_NL">Pagina impressies (alle bezoeken)</label>
</name>
<unit>
<id>views</id>
<name>
<label locale="nl_NL">Impressies</label>
<label locale="en_US">Views</label>
</name>
</unit>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/profileProperties/clickcount?alt=application/json
</href>
<rel>alt</rel>
<type>application/json</type>
</link>
</links>
</profileProperty>
|
Create/update profile property
Synopsis |
PUT https://yourserver.blueconic.net/rest/profileProperties/[id] |
Description |
Creates or updates a profile property. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
id |
Yes |
String |
None |
any id |
The ID of the profile property to create or update. A valid id may consist of letters, numbers, hyphens (-), and underscores (_) and is at least one character long |
Form |
filterType |
No |
String |
None |
"SELECT", "RANGE", "DATETIME" |
The filtertype of the profile property. |
Form |
indexed |
No |
Boolean |
False |
a Boolean |
Whether the profile property is indexed (unique). |
Form |
unit |
No |
String |
None |
any String |
The unit of the profile property. |
Form |
permissionLevel |
No |
PermissionLevel |
"PERSONAL" |
"DO_NOT_TRACK", "ANONYMOUS", "PERSONAL" |
The permission level of the profile property. |
Form |
mergeStrategy |
No |
MergeStrategy |
None |
"BOTH", "SUM", "HIGHEST", "LOWEST", "LATEST", "KEEP_CURRENT" |
The merge strategy of the profile property. |
Form |
name |
No |
String |
None |
any String |
The name of the profile property (for all locales). |
Form |
description |
No |
String |
None |
any String |
The description of the profile property (for all locales). |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the created / updated profile property.
- 400 - Either, the specified profile property exists but is created by a plugin and cannot be created / updated through REST, or the id, filtertype, permission level, or merge strategy is invalid.
- 401 - Authentication failed (unauthorized).
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/profileProperties/myProperty
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileProperty>
<filterType>RANGE</filterType>
<id>myProperty</id>
<indexed>false</indexed>
<unit>
<id>existingUnit</id>
<name>
<label locale="nl_NL">Existing Unit</label>
<label locale="en_US">Bestaande eenheid</label>
</name>
</unit>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/profileProperties/myProperty?alt=application/json
</href>
<rel>alt</rel>
<type>application/json</type>
</link>
</links>
</profileProperty>
|
Delete profile property
Synopsis |
DELETE https://yourserver.blueconic.net/rest/profileProperties/[id] |
Description |
Deletes a profile property. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
id |
Yes |
String |
None |
any id |
The ID of the profile property. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the deleted profile property.
- 400 - The specified profile property exists but is created by a plugin and cannot be deleted.
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile property doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
DELETE https://yourserver.blueconic.net/rest/profileProperties/myProperty
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileProperty>
<filterType>RANGE</filterType>
<id>myProperty</id>
<indexed>false</indexed>
<name>
<label locale="en_US">My own property</label>
<label locale="nl_NL">Mijn eigen eigenschap </label>
</name>
<description>
<label locale="en_US">This is my profile property created through REST.</label>
<label locale="nl_NL">Dit is mijn profieleigenschap die aangemaakt is via REST.</label>
</description>
<unit>
<id>existingUnit</id>
<name>
<label locale="nl_NL">Existing Unit</label>
<label locale="en_US">Bestaande eenheid</label>
</name>
</unit>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/profileProperties/myProperty?alt=application/json
</href>
<rel>alt</rel>
<type>application/json</type>
</link>
</links>
</profileProperty>
|
Segment methods
The following methods allow you to retrieve properties from segments.
Get all segments
Synopsis |
GET https://yourserver.blueconic.net/rest/segments |
Description |
Retrieves the id and name of segments. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Querystring |
startIndex |
No |
String |
0 |
any number |
Specifies the index of the first item to include in the result. |
Querystring |
count |
No |
String |
20 |
any number |
Specifies the number of results to return. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the segments.
- 401 - Authentication failed (unauthorized).
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/segments
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<segments>
<itemsPerPage>20</itemsPerPage>
<startIndex>0</startIndex>
<totalPages>1</totalPages>
<totalResults>2</totalResults>
<segment>
<id>aac8d07f-030e-4ce3-b269-13e56d8e8181</id>
<name>Example segment</name>
</segment>
<segment>
<id>0cabb4ed-a5e8-4e6a-82e0-f7f409266697</id>
<name>Example segment2</name>
</segment>
</segments>
|
Get segment profiles
Synopsis |
GET https://yourserver.blueconic.net/rest/segments/[id]/profiles |
Description |
Retrieves the profiles of the segment. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
id |
Yes |
String |
None |
any id |
The ID of the segment. |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Querystring |
startIndex |
No |
String |
0 |
any number |
Specifies the index of the first item to include in the result. |
Querystring |
count |
No |
String |
20 |
smaller than or equal to 1.000.000 |
Specifies the number of results to return. |
Querystring |
properties |
No |
String |
null |
One or more profile property ids, separated by a comma. |
Specifies for which profile properties values will be returned for each profile. If not specified, the values of all profile properties will be returned, which may result in a large result set. |
Querystring |
expand |
No |
String |
null |
One of:
- "profiles.profile.permissions"
- "profiles.profile.replace"
- "profiles.profile.segments"
- "profiles.profile.timeline"
|
Expand the information in the result set. Use "profiles.profile.permissions" to include permission level and exception data. Use "profiles.profile.replace" to include profile merge information. Use "profiles.profile.segments" to include the segments a profile is part of. Use "profiles.profile.timeline" to include timeline event information. Use multiple "expand" querystring parameters to return combinations. |
Querystring |
eventTypeId |
No |
String |
null |
ID of the timeline event type. |
Filter returned timeline events for a specific type. Only one timeline event type ID is allowed. |
Querystring |
eventCount |
No |
String |
20 |
any number |
The maximum number of timeline events to return. |
Querystring |
fromDate |
No |
String |
null |
any date |
Filter to only include timeline events that are dated later than this date. The format of fromDate is "2018-01-01T00:00Z" or with a timezone offset "2018-01-01T00:00+05:00" |
Querystring |
toDate |
No |
String |
null |
any date |
Filter to only include timeline events that are dated before this date. The format of toDate is "2018-01-01T00:00Z" or with a timezone offset "2018-01-01T00:00+05:00" |
Querystring |
prettyPrint |
No |
String |
null |
"true" |
Set to "true" to return the JSON result in a readable pretty print format. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the segment export.
- 401 - Authentication failed (unauthorized).
- 404 - The specified segment doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
GET https://yourserver.blueconic.net/rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=xml&startIndex=2&count=2
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profiles>
<itemsPerPage>2</itemsPerPage>
<startIndex>2</startIndex>
<totalPages>1</totalPages>
<totalResults>2</totalResults>
<links>
<link>
<href>
https://yourserver.blueconic.net/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
/profiles?alt=xml&startIndex=0&count=2
</href>
<rel>first</rel>
<type>xml</type>
</link>
<link>
<href>
https://yourserver.blueconic.net/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
/profiles?alt=xml&startIndex=0&count=2
</href>
<rel>previous</rel>
<type>xml</type>
</link>
<link>
<href>
https://yourserver.blueconic.net/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
/profiles?alt=xml&startIndex=4&count=2
</href>
<rel>next</rel>
<type>xml</type>
</link>
<link>
<href>
https://yourserver.blueconic.net/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
/profiles?alt=xml&startIndex=10&count=2
</href>
<rel>last</rel>
<type>xml</type>
</link>
</links>
<profile>
<id>45e2a650-ca17-4e03-8e8d-12d00ed4d9b3</id>
<properties>
<property>
<id>email</id>
<values>
<value>info@test.com</value>
</values>
</property>
<property>
<id>hobby</id>
<values>
<value>soccer</value>
<value>tennis</value>
</values>
</property>
</properties>
</profile>
<profile>
<id>9efb8a28-bfdf-4a10-b4f4-c0fb3a9a8dcc</id>
<properties />
</profile>
</profiles>
|
Objectives methods
The following methods allow you to control the consented and refused objectives of a profile
Update the privacy legislation of a profile
Synopsis |
PUT https://yourserver.blueconic.net/rest/profiles/[profile]/legislation |
Description |
Updates the privacy legislation of an existing BlueConic profile. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
Form |
privacyLegislation |
Yes |
String |
null |
One of the privacy legislation zone values |
The new privacy legislation that governs the profile. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the updated profile.
- 400 - Bad request (invalid privacy legislation)
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/profiles/f17e2071-4a00-4bfc-b16a-d78458801aa1/legislation?alt=xml&privacyLegislation=NONE
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id> f17e2071-4a00-4bfc-b16a-d78458801aa1</id>
<privacyLegislation>NONE</privacyLegislation>
<replaceBy />
<properties />
<segments />
</profile>
|
Add consented objectives to a profile
Synopsis |
POST https://yourserver.blueconic.net/rest/profiles/[profile]/consentedObjectives |
Description |
Updates the consented objectives of an existing BlueConic profile. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
JSON Body |
|
Yes |
Array of strings |
null |
List of objective UUID’s. |
The body of the request should contain the objective UUID’s that should be added to the list of existing consented objectives. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the updated profile.
- 400 - Bad request (empty body)
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
POST https://yourserver.blueconic.net/rest/profiles/f17e2071-4a00-4bfc-b16a-d78458801aa1/consentedObjectives?alt=xml
JSON Body
["objective_id_1","objective_id_2"]
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id> f17e2071-4a00-4bfc-b16a-d78458801aa1</id>
<privacyLegislation>GDPR</privacyLegislation>
<consentedObjectives>
<objective>
<id>objective_id_1</id>
</objective>
<objective>
<id>objective_id_2</id>
</objective>
</consentedObjectives>
<refusedObjectives/>
<replaceBy />
<properties />
<segments />
</profile>
|
Set consented objectives of a profile
Synopsis |
PUT https://yourserver.blueconic.net/rest/profiles/[profile]/consentedObjectives |
Description |
Set the consented objectives of an existing BlueConic profile. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
JSON Body |
|
Yes |
Array of strings |
null |
List of objective UUID’s. |
The body of the request should contain the objective UUID’s that should overwrite the list of existing consented objectives. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the updated profile.
- 400 - Bad request (empty body)
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/profiles/f17e2071-4a00-4bfc-b16a-d78458801aa1/consentedObjectives?alt=xml
JSON Body
["objective_id_2"]
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id> f17e2071-4a00-4bfc-b16a-d78458801aa1</id>
<privacyLegislation>GDPR</privacyLegislation>
<consentedObjectives>
<objective>
<id>objective_id_2</id>
</objective>
</consentedObjectives>
<refusedObjectives />
<replaceBy />
<properties />
<segments />
</profile>
|
Add refused objectives to a profile
Synopsis |
POST https://yourserver.blueconic.net/rest/profiles/[profile]/refusedObjectives |
Description |
Updates the refused objectives of an existing BlueConic profile. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
JSON Body |
|
Yes |
Array of strings |
null |
List of objective UUID’s. |
The body of the request should contain the objective UUID’s that should be added to the list of existing refused objectives. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the updated profile.
- 400 - Bad request (empty body)
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
POST https://yourserver.blueconic.net/rest/profiles/f17e2071-4a00-4bfc-b16a-d78458801aa1/refusedObjectives?alt=xml
JSON Body
["objective_id_1","objective_id_2"]
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id> f17e2071-4a00-4bfc-b16a-d78458801aa1</id>
<privacyLegislation>GDPR</privacyLegislation>
<consentedObjectives />
<refusedObjectives>
<objective>
<id>objective_id_1</id>
</objective>
<objective>
<id>objective_id_2</id>
</objective>
<replaceBy />
<properties />
<segments />
</profile>
|
Set refused objectives of a profile
Synopsis |
PUT https://yourserver.blueconic.net/rest/profiles/[profile]/refusedObjectives |
Description |
Set the refused objectives of an existing BlueConic profile. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Path |
profile |
Yes |
String |
null |
any UUID |
The ID of the profile |
Querystring |
alt |
No |
String |
"xml" |
"xml", "json" |
Specifies the format in which to return the result. |
JSON Body |
|
Yes |
Array of strings |
null |
List of objective UUID’s. |
The body of the request should contain the objective UUID’s that should overwrite the list of existing refused objectives. |
|
Authentication |
Yes |
Responses |
- 200 - Returns the updated profile.
- 400 - Bad request (empty body)
- 401 - Authentication failed (unauthorized).
- 404 - The specified profile doesn't exist.
- 503 - The server is too busy to handle the request.
|
Example |
Request
PUT https://yourserver.blueconic.net/rest/profiles/f17e2071-4a00-4bfc-b16a-d78458801aa1/refusedObjectives?alt=xml
JSON Body
["objective_id_2"]
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id> f17e2071-4a00-4bfc-b16a-d78458801aa1</id>
<privacyLegislation>GDPR</privacyLegislation>
<refusedObjectives>
<objective>
<id>objective_id_2</id>
</objective>
</refusedObjectives>
<consentedObjectives />
<replaceBy />
<properties />
<segments />
</profile>
|
Generate recommendations
To work with recommendations, you will have to set up a content collector or a product collector.
Synopsis |
POST https://yourserver.blueconic.net/rest/recommendations |
Description |
Generate BlueConic recommendations for a specific profile based on the provided parameters. |
Parameter(s) |
Parameter Type |
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
Querystring |
profileId |
No |
String |
null |
Any UUID |
The ID of the BlueConic profile. |
Querystring |
storeId |
Yes |
String |
null |
Any UUID |
The ID of the content store to get the items from. |
Querystring |
itemId |
No |
String |
null |
Any string |
Optional ID of the current item being shown. Some algorithms are based on this information. It also excludes this item from being returned in the result. |
Querystring |
frequencyCap |
No |
Int |
Null |
Any number |
The number of times an item can be recommended to a profile before being hidden from future recommendations. |
Querystring |
imageWidth |
No |
Int |
Null |
Any number |
Width of the images to return. |
Querystring |
imageHeight |
No |
Int |
Null |
Any number |
Height of the images to return. |
Querystring |
manualViewCounting |
No |
Boolean |
false |
true, false |
Prevent updating recommendation statistics for the recommended items. Can be used to generate offline recommendation items without influencing the profile. |
The body of a recommendations request consists of a JSON array that holds one or more sets of recommendation definition objects. Each recommendation definition object contains a combination of algorithms and filters and a number of items that should be returned. This allows you to return items based on different mixes of algorithms. You can also define a default to fall back to when not enough matching recommendations can be found.
Name |
Required |
Data Type |
Default |
Value(s) |
Description |
id |
Yes |
String |
null |
“first”, “second” or “default” |
The order of execution of the definition objects: “first” will be executed first, “second” will be executed next. If the total count has not been reached, the remainder items will be from the “default” definition. |
boosts |
Yes |
Object[] |
[] |
[{"value": "1.5", "algorithm": "RECENCY"}] |
The algorithms that will be executed to determine the recommendations with their boost value and parameters.
value: Boost value can be a whole or half number: 1, 1.5, 2, 2.5, …, 9.5, 10.
algorithm: Available boosting algorithms:
- COLLABORATIVE_FILTERING
- INTEREST
- LOOK_ALIKE
- RECENCY
- RECENT_CTR
- RECENT_ENTRYPAGE
- RECENT_VIEW
- RECENTLY_BOUGHT
- RECENTLY_SHOPPINGCART
- RECENTLY_VIEWED
- SAME_CATEGORY
rampUp: Ramp up value for algorithms that use it:
- INSTANT
- VERY_SLOW
- SLOW
- NORMAL
- FAST
|
count |
No |
Int |
null |
Any number |
The maximum number of items that should be returned for this definition. |
filters |
No |
String[] |
[] |
["category:news", "viewed"] |
Item filters, see below. |
The following boosting algorithms are supported:
Name |
Description |
Example |
Breaking news |
Items most viewed by all visitors in the time frame defined in the collector. |
"boosts": [{"value": 1, "algorithm": "RECENT_VIEW"}] |
Viral news |
Items most used as a landing page by all visitors in the time frame defined in the collector. |
"boosts": [{"value": 1, "algorithm": "RECENT_ENTRYPAGE"}] |
Recency |
Items most recently added items based on the publication date property. |
"boosts": [{"value": 1, "algorithm": "RECENCY"}] |
Recent high CTRs |
Items most clicked-through from BlueConic recommendations by all visitors in the time frame defined in the collector. |
"boosts": [{"value": 1, "algorithm": "RECENT_CTR"}] |
Recently bought items |
Items recently bought by the provided profileId. |
"boosts": [{"value": 1, "algorithm": "RECENTLY_BOUGHT"}] |
Recently carted items |
Items recently put in the shopping cart by the provided profileId. |
"boosts": [{"value": 1, "algorithm": "RECENTLY_SHOPPINGCART"}] |
Same category |
Items of the same category as the item with the provided itemId. |
"boosts": [{"value": 1, "algorithm": "SAME_CATEGORY" }] |
Look-alike-articles |
Items that have similar content to the item with the provided itemId. |
"boosts": [{"value": 1, "algorithm": " LOOK_ALIKE" }] |
Seen articles |
Items the provided profileId recently viewed. |
"boosts": [{"value": 1, "algorithm": " RECENTLY_VIEWED" }] |
Same interest |
Items that look similar to the items already viewed by the provided profileId. |
"boosts": [{"value": 1, "algorithm": "INTEREST", "rampUp": "FAST"}] |
Collaborative filtering |
Items popular with other profiles who viewed the same items as the provided profileId. |
"boosts": [{"value": 1, "algorithm": "COLLABORATIVE_FILTERING", "rampUp": "FAST"}] |
Recommendation definition objects may contain filters that restrict the items that may be returned:
Example |
Description |
"filters": ["VIEWED"] |
Exclude the items already viewed by the provided profileId. |
"filters": ["SHOPPINGCART"] |
Exclude the items in the shopping of the provided profileId. |
"filters": ["BOUGHT"] |
Exclude the items already bought by the provided profileId. |
"filters": ["VIEWED_ONLY"] |
Include only items that were viewed by the provided profileId. |
"filters": ["SHOPPINGCART_ONLY"] |
Include only items that were in the shoppingcart of the provided profileId. |
"filters": ["BOUGHT_ONLY"] |
Include only items that were bought by the provided profileId. |
"filters": ["SAME_CATEGORY"] |
Include only items that have the same category as the provided itemId. |
"filters": ["IN_STOCK"] |
Include only items that are in stock. |
"filters": ["publicationDate>2018-06-01T00:00+02:00"] |
Include only items with a publication date after June 1st 2018. The format of publicationDate is “2018-01-01T00:00Z” or with a timezone offset “2018-01-01T00:00+05:00” |
"filters": ["publicationDate<=2018-06-01T00:00+02:00"] |
Include only items with a publication date before June 1st 2018. The format of publicationDate is “2018-01-01T00:00Z” or with a timezone offset “2018-01-01T00:00+05:00” |
"filters": ["category:politics"] |
Include only items that have a specific value for a specific property, e.g. “politics” for property “category”. |
"filters": ["!category:politics"] |
Exclude items that do not have a specific value, e.g. “politics” for property “category”. |
"filters": ["category:politics","category:sports"] |
Include only items that have all specific values, e.g. “politics” and “sports” for property “category”. |
"filters": ["category:politics,sports"] |
Include only items that have any of the specified values, e.g. “politics” or “sports” for property “category”. |
"filters": ["!category:politics","!category:sports"] |
Include only items that do not have any of the specified values, e.g. “politics” or “sports” for property “category”. |
"filters": ["!category:politics,sports"] |
Include only items that do not have all of the specified values, e.g. “politics” and “sports” for property “category”. |
"filters": ["hasproperty:image"] |
Include only items that have an image. |
|
Authentication |
Yes |
Responses |
- 200 – Returns recommendations.
- 400 – The specified body is not valid.
- 503 – The server is too busy to handle the request.
|
Example |
Request
POST https://yourserver.blueconic.net/rest/recommendations?profileId=5a68374b-2311-aad2-1ba2-f32f7ccd1131&storeId=b6827f3-a3c1-2112-f522-aa2ccd113124&itemId=http%3A%2F%2Fwww.example.com%2Fnews%2Fkitten-saved-from-tree&imageWidth=150&imageHeight=150&manualViewCounting=true
JSON body
[
{
"id": "first",
"boosts": [
{"value": "1", "algorithm": "RECENCY"},
{"value": "2", "algorithm": "COLLABORATIVE_FILTERING", "rampUp": "FAST"},
{"value": "1", "algorithm": "RECENT_VIEW"},
{"value": "1", "algorithm": "RECENT_CTR"}
],
"filters": [
"category:politics",
"viewed"
],
"count": 3
},
{
"id": "second",
"boosts": [
{"value": "2","algorithm": " COLLABORATIVE_FILTERING ", "rampup": "SLOW"},
{"value": "1","algorithm": " RECENT_CTR"}
],
"filters": [
"category:politics",
"!category:economie",
"VIEWED"
],
"count": 3
},
{
"id": "default",
"filters": [
"publicationDate>2018-06-17T14:30+0200",
"!category:economie",
"VIEWED"
],
"boosts": [
{"value": "1","algorithm": "RECENT_CTR"}
]
}
]
Response
{
"recommendationBlock":
[
{
"id": "first",
"recommendations": [
{
"score": 0.12063565363854145,
"trackingUrl": "http://taylor-news.com/1"
"id": "www.taylor-news.com/news/1111",
"url": "https://www.taylor-news.com/news/1111",
"name": "Name 1",
"description": "Description 1.",
"category": ["sport", "baseball"],
"image": "https://img.taylor-news.com/img1.jpg",
"customProperties": {
"pubdate": ["tuesday 12 juni 2018, 09:45"],
"story": []
}
},
{
"score": 0.001113261296046081,
"trackingUrl": "http://taylor-news.com/2"
"id": "www.taylor-news.com/news/2222",
"url": "https://www.taylor-news.com/news/2222",
"name": "Name 2",
"description": "Description 2.",
"category": ["news", "politics"],
"image": "https://img.taylor-news.com/img2.jpg",
"customProperties": {
"pubdate": ["wednesday 13 juni 2018, 09:45"],
"story": []
}
}
]
},
{
"id": "second",
"recommendations": [
{
"score": 1.0,
"trackingUrl": "http://taylor-news.com/3"
"id": "www.taylor-news.com/news/3333",
"url": "https://www.taylor-news.com/news/2317578",
"name": "Name 3",
"description": "Description 3.",
"category": ["sport", "basketball"],
"image": "https://img.taylor-news.com/img3.jpg",
"customProperties": {
"pubdate": ["tuesday 12 juni 2018, 09:45"],
"story": []
}
},
{
"score": 1.0,
"trackingUrl": "http://taylor-news.com/4"
"id": "www.taylor-news.com/news/4444",
"url": "https://www.taylor-news.com/news/2317578",
"name": "Name 4",
"description": "Description 4.",
"category": [],
"image": "https://img.taylor-news.com/img4.jpg",
"customProperties": {
"pubdate": ["tuesday 12 juni 2018, 09:45"],
"story": []
}
}
]
}
],
"recommendationId": "97258279-baf7-45de-aab3-457dc42904be",
"trackingPixel": "http://track.com"
}
|
REST API example
In this section an expanded example of using the BlueConic REST API is described. In the example, a visitor who already has a BlueConic profile ("Profile A") in one channel in the BlueConic universe (website) visits a different channel in the universe (mobile) and, since the visitor is not recognized, a new visitor profile is created, in this case "Profile B". The new visitor profile is then populated with segment data based on his or her activity. By retrieving the visitor's second profile and searching for a matching property/value in the other profiles, it is determined that "Profile A" and "Profile B" belong to the same visitor. The profiles are then merged into "Profile A" and "Profile B" becomes inactive:

In your merge implementation, you must decide which values to keep when both profiles contain the same property with different values. A REST method then sets the replaceBy property which specifies that "Profile A" replaces "Profile B". From then on, the visitor's active BlueConic profile is "Profile A". "Profile B" is kept but no longer updated:

Retrieve the profile ID for "Profile B" from the cookie request
The visitor with "Profile B" sends a cookie request (BCSessionID) to the mobile channel. The ID from "Profile B" is retrieved from the request.
For example:

In this case, the profile ID from the cookie is:
99db747f-2061-43d3-a508-76a977a18ba4
Retrieve the visitor profile
Now that we have the BlueConic ID of "Profile B", we can retrieve the BlueConic profile (99db747f-2061-43d3-a508-76a977a18ba4):
GET https://yourserver.blueconic.net/rest/profiles/99db747f-2061-43d3-a508-76a977a18ba4
Returns:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id>99db747f-2061-43d3-a508-76a977a18ba4</id>
<properties>
<property>
<id>email</id>
<values>
<value>jsmith@blueconic.com</value>
</values>
</property>
<property>
<id>clickcount</id>
<values>
<value>11</value>
</values>
</property>
<property>
<id>device</id>
<values>
<value>iPhone</value>
</values>
</property>
<property>
<id>country</id>
<values>
<value>Netherlands</value>
</values>
</property>
</properties>
</profile>
Retrieve the BlueConic profile ID(s) with the matching email address
Now that we know the email address, we can retrieve other BlueConic profile(s) based on the known property to see if there are any other profiles containing the same email address. Note: A property must be indexed (unique) in order to be retrievable using this method.
GET https://yourserver.blueconic.net/rest/profiles?alt=xml&property=email&value=jsmith@blueconic.com
Returns:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profiles total="2">
<profile>
<id>1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6</id>
</profile>
<profile>
<id>99db747f-2061-43d3-a508-76a977a18na4</id>
</profile>
</profiles>
Retrieve the profile that matches the property
In the previous step we retrieved the profile ID(s) that match the specified email address. You can now retrieve the profile that matches the profile ("Profile A" in this case).
GET https://yourserver.blueconic.net/rest/profile/1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6
Returns:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id>1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6</id>
<properties>
<property>
<id>name</id>
<values>
<value>John Smith</value>
</values>
</property>
<property>
<id>email</id>
<values>
<value>jsmith@blueconic.com</value>
</values>
</property>
<property>
<id>visitclicks</id>
<values>
<value>7</value>
</values>
</property>
<property>
<id>preferences</id>
<values>
<value>Football</value>
<value>Ajax</value>
</values>
</property>
</properties>
</profile>
Merge profiles
Now that know that the two profiles belong to the same visitor, we can merge the profiles. To do so, the values from one profile are added to the other in a merge operation. In addition to merging the values, you must also indicate which profile is the primary or main profile, that is, the one that contains all profile properties that have been gathered by both profiles. Once you determine which profile will be the main profile, you indicate in the profile that will become inactive, the ID of the main profile that replaces it. All future requests for the inactive profile are rerouted to the main profile. You must decide in your implementation the criteria that determine which profile becomes the primary, main profile.
Using the PUT https://yourserver.blueconic.net/rest/profiles/ method, you can individually write all the desired properties present in "Profile B" to "Profile A" using name/value pairs.
The result:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id>1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6</id>
<properties>
<property>
<id>name</id>
<values>
<value>John Smith</value>
</values>
</property>
<property>
<id>email</id>
<values>
<value>jsmith@blueconic.com</value>
</values>
</property>
<property>
<id>visitclicks</id>
<values>
<value>7</value>
</values>
</property>
<property>
<id>preferences</id>
<values>
<value>Football</value>
<value>Ajax</value>
</values>
</property>
<property>
<id>clickcount</id>
<values>
<value>11</value>
</values>
</property>
<property>
<id>device</id>
<values>
<value>iPhone</value>
</values>
</property>
<property>
<id>country</id>
<values>
<value>Netherlands</value>
</values>
</property>
</properties>
</profile>
Replace "Profile B" with "Profile A"
Now that the properties are merged into "Profile A", you want to indicate in "Profile B" that it has been replaced by "Profile A". As a result, all future requests for "Profile B" will be routed to "Profile A". The following method replaces "Profile B" with "Profile A", in the body, you include the "replaceBy" parameter and the ID of the profile that replaces the current profile. In this case profile ID 1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6 replaces 99db747f-2061-43d3-a508-76a977a18ba4:
PUT https://yourserver.blueconic.net/rest/profiles/99db747f-2061-43d3-a508-76a977a18ba4
replaceBy=1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6
Returns:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
<id>99db747f-2061-43d3-a508-76a977a18ba4</id>
<replaceBy>
<profile>
<id>1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6</id>
</profile>
</replaceBy>
<properties>
<property>
<id>email</id>
<values>
<value>jsmith@blueconic.com</value>
</values>
</property>
<property>
<id>clickcount</id>
<values>
<value>11</value>
</values>
</property>
<property>
<id>device</id>
<values>
<value>iPhone</value>
</values>
</property>
<property>
<id>country</id>
<values>
<value>Netherlands</value>
</values>
</property>
</properties>
</profile>