Knowledge Base

BlueConic REST API

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:

  1. An application generates an HTTP request for BlueConic.
  2. The OAuth library signs the request and sends it to BlueConic.
  3. BlueConic's API Access Connection receives the request. Using an OAuth library it validates the request and generates an HTTPS response.
  4. The HTTPS response is sent to the consumer.



Does the BlueConic customer data platform have a REST API? Yes, here it is

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 BlueConic Profile UUID The ID of the BlueConic profile
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Querystring collapse No String null "profile.segments" Collapse the information in the result set. Use "profile.segments" to exclude segment information.
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 retention period between 1 and 365 days (the default is 30 days). HIGH priority events have a retention period of 1 day and up. The default is indefinitely, however they 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. 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 No 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

"SET", "UPSERT", "UPDATE", "DELETE"

 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.
identifier No String null any value An (external) identifier which can be passed along with a timeline event operation and is returned in the response.

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",
            "identifier" : "id",
            "name": "Product name",
            "description": "Product description"
            "values": {
                "value": [ 
                    {
                        "key": "id",
                        "values": {"value": "TEXT"}, 
                        "name": "Id name", 
                        "description": "Id description" 
                    },
                    { 
                        "key": "quantity", 
                        "values": {"value": "NUMBER"},
                        "name": "Quantity name",
                        "description": "Quantity description" 
                    },
                    { 
                        "key": "netprice",
                        "values": {"value": "DECIMAL"},
                        "name": "Netprice name", 
                        "description": "Netprice description"
                    }, 
                    {
                        "key": "coupon",
                        "values": {"value": "TEXT"},
                        "name": "Coupon name", 
                        "description": "Coupon description"
                    },
                    {
                        "key": "deliverydate",
                        "values": {"value": "DATETIME"},
                        "name": "Deliverydate name",
                        "description": "Deliverydate description"
                    }
                ]
            }
        },
        {
            "key": "quantity",
            "values": {"value": "NUMBER"}
            "name": "Quantity name",
            "description": "Quantity description"
        }
    ],
    "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
    • id: TEXT
      • This is the product identifier
    • quantity: NUMBER
    • netprice: DECIMAL
    • coupon: TEXT
    • deliverydate: DATETIME
  • quantity: NUMBER

Note that the product identifier can be changed through the timeline event types tab in BlueConic.

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": "id",
            "values": {
              "value": ["PRODUCT-5469878987"]
            }
          },
          {
            "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"
}

Partial updates

Or in case of a partial update the snippet below:

  • Will update (or insert if not exists) the order event with the given id

    • date is optional and may be omitted, causing all events with the given id to be updated

  • Will add (or update if it exists) a product with id:PRODUCT-5469878987 to product

    • Note that the strategy can be left empty when the identifier is specified

  • Will set quantity to 2 if the product does not have quantity set yet

  • Will add FREETV-CHRISTMAS-SPECIAL to coupon for the product

  • Will set quantity to 1 for this order

Notes on using an identifier for nested timeline event properties.

  • A timeline event type property marked as identifier can only contain one value, more values will be ignored (first value is used)

  • When sending an identifier in the bulk API, it may not be empty

{
      "id": "eb20c911-4d23-4791-a3e7-d113e7a326d9",
      "date": "2018-01-01T00:00Z",
      "eventTypeId": "order",
      "data": [{
        "id": "product",
        "values": {
          "value":
            [{
              "id": "id",
              "values": {
                "value": ["PRODUCT-5469878987"]
              }
            },
            {
              "id": "quantity",
              "values": {
                "value": [2]
              }
              "strategy": "SET_IF_EMPTY"
            }, {
              "id": "coupon",
              "values": {
                "value": ["FREETV-CHRISTMAS-SPECIAL"]
              },
              "strategy": "ADD"
            }]
          ]
        }
        "strategy": "UPSERT"
      }, {
        "id": "quantity",
        "values": {
          "value": [1]
        }
        "strategy": "SET"
      }],
      "strategy": "UPSERT"
}

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 or timeline event property. Duplicates will not be added.
SET Values will overwrite the values that already existed in the profile or timeline event property.
SET_IF_EMPTY Only set values if the profile or timeline event property is empty.
SUM

Add the value to the value already stored in the profile property.

This is not supported for timeline event properties.
REMOVE Remove the value from the list of values already stored in the profile property.
This is not yet supported for timeline event properties.

Timeline Strategy

The following values are valid timeline strategies. These can either be used for the strategy property for a timeline event as a whole, or when passing rules to apply on nested timeline event properties.

Name Description
SET Timeline event will be added to the profile timeline as is, possibly replacing the existing event with the same ID, event type ID, and date.
UPSERT Will update (and insert if not found) the timeline event with the given ID, event type ID, and date, based on the rules that are passed along.
UPDATE Will update (but doesn’t insert if not found) the timeline event with the given ID, event type ID, and date, based on the rules that are passed along.
DELETE Will delete the timeline event with the given ID, event type ID and, optionally, a date. If not passed, all events matching the ID and event type ID will be deleted.
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"
}]

When the profile operation contains timeline events, the response will also contain a response per timeline event supplied. The state can be one of the following values: “CREATED”, “SET”, “MODIFIED”, “REJECTED”, “NOTFOUND” or “DELETED”.

[{
      "state": "CREATED",
      "profileId": "profile-UUID of the created profile",
      "identifier": " my-external-identifier",
      "timeline": [{
          "id": "order_1",
          "identifier": "my-external-order-identifier",
          "state": "REJECTED",
          "validationErrors": ["#/total_revenue/0: expected type: Number, found: String"]
        }
      ]
}]

 

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

One or more IDs of a timeline event type

 Filter for the returned timeline events for specific types.
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>2021-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. When optional parameter `profile` is set, the interaction ID will be added to the profile property "interactions_viewed" (in case of "VIEW"), "interactions_clicked" (in case of "CLICK") or "interactions_converted" (in case of "CONVERSION") of that profile.
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.
Querystring profile No String null any profile ID The ID of a BlueConic profile.
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 channels 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 channels 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", "CURRENCY", "DECIMAL", "EMAIL"

 The filtertype of the profile property. Note that changing the type might lead to loss of information.
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 "ANONYMOUS" "ANONYMOUS", "PERSONAL" The permission level of the profile property.
Form mergeStrategy No MergeStrategy None

"BOTH", "SUM", "HIGHEST", "LOWEST", "LATEST", "KEEP_CURRENT", "OLDEST"

 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).
Form createNewProfile No Boolean False

a Boolean

 Whether a visitor will switch to a new profile when a new value for the profile property is set. This will prevent potential profile hijacking. Only applicable when "indexed" is "true."
Form isAvailableForSegmentation No Boolean False

a Boolean

 Whether the profile property is available as a filter to create segments.
Form showInUI No Boolean True

a Boolean

 Whether the profile property is shown in the segments UI. Only applicable when "isAvailableForSegmentation" is "true."
Form canRead No Boolean False a Boolean

Whether the visitor's browser is allowed to retrieve the value for this profile property.
Form canWrite No Boolean False a Boolean

Whether the visitor's browser is allowed to write a (new) value into this profile property.
Form value No String[] None any String When selecting this profile property as filter for segmentation, these values will be selectable next to the values that are in the profiles. Only applicable when "isAvailableForSegmentation" is "true."
Form precision No Int 0 an Integer The precision of a profile property, e.g. 3. Only applicable when the “filterType” is "DECIMAL."
Form currency No String None

A currency ISO code

 The currency ISO code, e.g. "USD". Only applicable when the filterType is "CURRENCY."
Form dataSensitivity No DataSensitivity “NON_PII”

“NON_PII”,
”PII”

 The data sensitivity for 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 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 
 indexed=false&createNewProfile=false&isAvailableForSegmentation=true&showInUI=true&canRead=true&canWrite=true&filterType=SELECT&description=&permissionLevel=ANONYMOUS&mergeStrategy=LATEST&value=firstvalue&value=anothervalue&unit=&name=example
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 cursor No String  

One of: 

  • "*"
  • A value returned in "nextCursor"
 Defines the starting point of the page for pagination. When cursors are used, each page, except the last page, returns a "nextCursor" value which can be used to retrieve the next page. This is the preferred pagination method, especially for large segments. This parameter cannot be combined with "startIndex".
Querystring startIndex No String 0 any number Specifies the index of the first item to include in the result. When paginating large segments, use the "cursor" parameter instead.
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 One or more IDs of a timeline event type. Filter for the returned timeline events for specific types.
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.
  • 400 – Bad request: the "cursor" and "startIndex" parameters cannot be combined.
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified segment doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request (first page) 
GET https://yourserver.blueconic.net/rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=xml&cursor=*&count=2

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <profiles>
    <itemsPerPage>2</itemsPerPage>
    <totalPages>2</totalPages>
    <totalResults>3</totalResults>
    <cursor>*</cursor>
    <nextCursor>AoJ6p42zg84CPwVkYTMzZWRhNy1iNDNiLTRjZTAtODVmZS02YWY2NDc4Yzc0M2U</nextCursor>
    <links>
        <link>
            <href>https://yourserver.blueconic.net/rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=application/xml&cursor=*&count=2</href>
            <rel>first</rel>
            <type>application/xml</type>
        </link>
        <link>
            <href>https://yourserver.blueconic.net/rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=application/xml&cursor=AoJ6p42zg84CPwVkYTMzZWRhNy1iNDNiLTRjZTAtODVmZS02YWY2NDc4Yzc0M2U&count=2</href>
            <rel>next</rel>
            <type>application/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>
  Request (next page) 
GET https://yourserver.blueconic.net/rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=xml&cursor=AoJ6p42zg84CPwVkYTMzZWRhNy1iNDNiLTRjZTAtODVmZS02YWY2NDc4Yzc0M2U&count=2

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <profiles>
    <itemsPerPage>2</itemsPerPage>
    <totalPages>2</totalPages>
    <totalResults>3</totalResults>
    <cursor>AoJ6p42zg84CPwVkYTMzZWRhNy1iNDNiLTRjZTAtODVmZS02YWY2NDc4Yzc0M2U</cursor>
    <nextCursor>AoJznvzMnfkCPwUyNWZjNTYzMC0zMmYwLTQxODItYmRiYS04NTg0YWUwMWZkZTg</nextCursor>
    <links>
        <link>
          <href>https://yourserver.blueconic.net/rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=application/xml&cursor=*&count=2</href>
          <rel>first</rel>
          <type>application/xml</type>
        </link>
        <link>
          <href>https://yourserver.blueconic.net/rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=application/xml&cursor=AoJznvzMnfkCPwUyNWZjNTYzMC0zMmYwLTQxODItYmRiYS04NTg0YWUwMWZkZTg&count=2</href>
          <rel>next</rel>
          <type>application/xml</type>
        </link>
    </links>
    <profile>
      <id>63648a6c-fdc8-4c1c-94db-aa93b4920953</id>
      <properties>
        <property>
          <id>email</id>
          <values>
            <value>info@example.com</value>
          </values>
        </property>
        <property>
          <id>hobby</id>
          <values>
            <value>music</value>
          </values>
        </property>
      </properties>
    </profile>
 </profiles>
  Request (last page) 
GET https://yourserver.blueconic.net/rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=xml&cursor=AoJznvzMnfkCPwUyNWZjNTYzMC0zMmYwLTQxODItYmRiYS04NTg0YWUwMWZkZTg&count=2

XML Response

The last page does not return a "nextCursor" value.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <profiles>
    <itemsPerPage>2</itemsPerPage>
    <totalPages>2</totalPages>
    <totalResults>3</totalResults>
    <cursor>AoJznvzMnfkCPwUyNWZjNTYzMC0zMmYwLTQxODItYmRiYS04NTg0YWUwMWZkZTg</cursor>
    <links>
        <link>
            <href>https://yourserver.blueconic.net/rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=application/xml&cursor=*&count=2</href>
           <rel>first</rel>
            <type>application/xml</type>
        </link>
    </links>
 </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"
  }

 

Audit Events

The Audit Event API allows users to connect BlueConic to a SIEM system. We recommend using this API to periodically receive security-related activities based on a rolling window. The API has a 30-day retention period.

The API logs the following audit events:

Object Events
BlueConic hostname Create, Update, Delete
Channel Create, Update, Delete
Connection Create, Update, Delete
Dashboard Create, Update, Delete
Dialogue Create, Update, Delete
Group Read, Update, Delete
Group type Create, Update, Delete
Ip range Create, Update, Delete
Language Create, Update, Delete
Lifecycle Create, Update, Delete
Notebook Create, Update, Delete
Objective Create, Update, Delete
Plugin Create, Update, Delete
Profile Read, Update, Delete
Profile property Create, Update, Delete
Role Create, Update, Delete
Segment Create, Update, Delete
Tracker Create, Update, Delete
User Login, Login failed, Logout, Create, Update, Delete

Only Profile and Group viewed, updated, or deleted by a user from the Profile and Groups tab are logged.

The following events are not considered as human actions, and therefore not covered in the Platform Audit Event API:

  • Connections that import or export profiles
  • Profile and group creation (profiles can only be created by a visitor or by an import connection)
  • AI Workbench

Event data

The following event data is available:

Field

Description

Example values

date

Datetime in UTC when the event occurred. The date is in the https://www.ietf.org/rfc/rfc3339.txt format.

2020-11-11T11:24:01.183Z

username

(BlueConic) Identifier (email address) of the user who did the action.

Value is empty for failed login attempts.

test@blueconic.com

objectType

Object of the action.
  • BLUECONIC_HOSTNAME
  • CHANNEL
  • CONNECTION
  • DASHBOARD
  • DIALOGUE
  • GROUP
  • GROUP_TYPE
  • IP_RANGE
  • LANGUAGE
  • LIFECYCLE
  • LISTENER
  • NOTEBOOK
  • OBJECTIVE
  • PLUGIN
  • PROFILE
  • PROFILE_PROPERTY
  • ROLE
  • SEGMENT
  • TRACKER
  • USER

objectId

  • Email address in case of a user.

    • In the case of LOGIN_FAILED and a user tried to login with an invalid format email address, it could be that the user filled the password in the email address field. In that case the objectId is empty
  • Grouptype_GroupID in case of a group
  • UUID or identifier in case of other object types.
  • 1b1e50a5-c46a-4309-a95c-d4e19985fbbb
  • test@blueconic.com
  • test_objective
  • test_profile_property

objectName

Human readable name of the object.

For Profiles, the name is determined by the first value that is not empty:

  1. fullname
  2. email
  3. BlueConic ID (UUID)

For Users, the name is determined by the first value that is not empty:

  1. fullname
  2. email
  • In the case of LOGIN_FAILED and a user tried to login with an invalid format email address, it could be that the user filled the password in the email address field. In that case, the objectName is empty.

For groups, the name is the group id.
  • SFTP connection
  • test@blueconic.om
  • Keyword Interest Ranking

operation

Action performed on the object.
  • CREATE
  • UPDATE
  • DELETE
  • READ
  • LOGIN
  • LOGIN_FAILED
  • LOGOUT

ipAddress

The source IP address from which the event was triggered.

192.168.1.100

Authorization

The API supports OAuth version 1.0a with HMAC-SHA1. See OAuth signed requests for more information.

The API has one method: Get Audit Events

Get audit events

Synopsis

GET https://yourserver.blueconic.net/rest/auditEvents

Description

Retrieves the audit events

Parameter(s)

Parameter

Type

Name

Required

Data Type

Default

Value(s)

Description

Querystring

fromDate

No

String

null

any date

Only return entries that are created later than this date. The fromDate is in the https://www.ietf.org/rfc/rfc3339.txt format. E.g.2020-11-10T11:21:33.872Z

Querystring

count

No

String

100

any number

Page size for the result.

Maximum limit is 1.000

Pagination

For pagination the count in combination with the fromDate parameter can be used. E.g.https://yourserver.blueconic.net/rest/auditEvents?count=5&fromDate=2020-11-10T11:21:33.872Z.

Authentication

Yes

Responses
  • 200 - Returns the audit events
  • 400 - One or more required parameters is missing or invalid.
  • 401 - Authentication failed (unauthorized).

Example

Requests

  • Returns the first 10 registered events

https://yourserver.blueconic.net/rest/auditEvents?&count=10

  • Returns 100 audit events starting from 2020-11-10T11:21:33.872Z

https://yourserver.blueconic.net/rest/auditEvents?&fromDate=2020-11-10T11:21:33.872Z&count=100

Response 

{
  "auditEvents": [
    {
      "date": "2020-11-10T11:21:33.872Z",
      "username": "test@blueconic.com",
      "objects": [
        {
          "id": "68a02413-98d0-4a2b-b65c-4617a3c26fd0",
          "name": "Campaign Tracker Listener ds"
        }
      ],
      "objectType": "LISTENER",
      "operation": "UPDATE",
      "ipAddress": "192.168.1.100"
    },
    {
      "date": "2020-11-10T11:21:33.672Z",
      "username": "test@blueconic.com",
      "objectType": "PROFILEPROPERTY",
      "objects": [
        {
          "id": "responded_to_campaigns",
          "name": "responded_to_campaigns"
        }
      ],
      "operation": "CREATE",
      "ipAddress": "192.168.1.100"
    },
    {
      "date": "2020-11-09T12:51:32.702Z",
      "username": "test@blueconic.com",
      "objectType": "USER",
      "objects": [
        {
          "id": "test@blueconic.com",
          "name": "test@blueconic.com"
        }
      ],
      "operation": "LOGIN",
      "ipAddress": "192.168.1.100"
    },
    {
      "date": "2020-11-09T12:51:32.702Z",
      "objectType": "USER",
      "objects": [
        {
          "id": "wrongpassword@blueconic.com",
          "name": "wrongpassword@blueconic.com"
        }
      ],
      "operation": "LOGIN_FAILED",
      "ipAddress": "192.168.1.100"
    },
    {
      "date": "2020-11-09T12:51:32.702Z",
      "objectType": "USER",
      "objects": [
        {
          "id": "",
          "name": ""
        }
      ],
      "operation": "LOGIN_FAILED",
      "ipAddress": "192.168.1.100"
    },
    {
      "date": "2020-11-09T12:51:32.702Z",
      "objectType": "USER",
      "objects": [
        {
          "id": "nonexistingusername@blueconic.com",
          "name": "nonexistingusername@blueconic.com"
        }
      ],
      "operation": "LOGIN_FAILED",
      "ipAddress": "192.168.1.100"
    },
    {
      "date": "2020-11-09T12:51:32.702Z",
      "username": "test@blueconic.com",
      "objectType": "PROFILE",
      "objects": [
        {
          "id": "4dc2a97e-707e-4049-a03a-badcce564f3c",
          "name": "4dc2a97e-707e-4049-a03a-badcce564f3c"
        },
        {
          "id": "test@blueconic.com",
          "name": "33f53658-3dc8-4946-b239-ecb65dea9827"
        }
      ],
      "operation": "READ",
      "ipAddress": "192.168.1.100"
    }
  ]
}