Skip to main content
All CollectionsDeveloper ToolsREST API
BlueConic REST API v1
BlueConic REST API v1
Updated over a month ago

The BlueConic REST API v1 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.

Important

Developers creating new BlueConic applications should use the newer, updated BlueConic REST API v2, available at rest.apidoc.blueconic.com.

Time frame: BlueConic is ending support for REST API v1 on March 31, 2024, and this version is officially retired as of July 1, 2024. See BlueConic REST API migration for details.

Using the REST API v1

If you have an existing external software application that needs to be integrated with BlueConic, you can use the BlueConic REST API v1 (below).

You can make use of the BlueConic REST API v1 in these three steps:

  1. An application manager creates a BlueConic API Access Connection in BlueConic.
    This will provide a Consumer Key and a Consumer Secret that the developer of the external software application needs.

  2. A developer implements OAuth in the external software application.

  3. With OAuth up and running, the developer can use the full BlueConic REST API to integrate with BlueConic.

Table of contents

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

Create or update one or more profiles at once

Delete one profile

Create one new profile

Replace a profile

Set the permission level of a profile

Set the permission level exceptions of a profile

Search for profiles

Get timeline events for one profile

Profile Event methods

The following methods allow you to retrieve profile event information.

Get events for a profile

Interaction methods

The following methods allow you to retrieve and post interaction event information.

Get interactions

Register pageview events

Register interaction events

URL mapping methods

The following methods allow you to retrieve and post URL mapping information.

Create new URL mapping

Get one URL mapping

Update URL mapping properties

Domain methods

The following methods allow you to create, modify, retrieve properties from, and delete BlueConic domains, channels, and positions.

Get all domains

Get one domain

Create new domain

Update a domain

Delete a domain

Get channels of a domain

Get one channel

Create new channel

Update a channel

Delete a channel

Get positions of a channel

Get one position

Create new position

Update a position

Delete a position

Profile property methods

The following methods allow you to retrieve profile properties.

Get all profile properties

Get one profile property

Create/update profile property

Delete profile property

Segment methods

The following methods allow you to retrieve properties from segments.

Get all segments

Get segment profiles

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>[email protected]</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>[email protected]</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

Add consented objectives to a profile

Set consented objectives of a profile

Add refused objectives to a profile

Set refused objectives of a profile

Generate recommendations

To work with recommendations, you will have to set up a content collector or a product collector.

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

BlueConic Support Access

Update (for each change)

Channel

Create, Update, Delete

Clean up rule

Create, Update, Delete

Connection

Create, Update, Delete

Manual run, scheduled run

Dashboard

Create, Update, Delete

Dialogue

Create, Update, Delete

Domain Group

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

Merge rule

Create, Update, Delete

Notebook

Create, Update, Delete

Manual run, scheduled run, Editor run

OAuth application

Create, Update, Delete

OAuth token

Create, Update, Delete

Objective

Create, Update, Delete

Plugin

Create, Update, Delete

Privacy setting

Update (for each change)

Profile

Read, Update, Delete

Profile property

Create, Update, Delete

Role

Create, Update, Delete

Segment

Create, Update, Delete

Single Sign On Setting

Update (for each change)

Supported Legislation Zone

Create, Delete, Update

Tracker

Create, Update, Delete

User

Login, Login failed, Logout, Create, Update, Delete

Password reset requested, Password change

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)

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.

[email protected]

objectType

Object of the action.

  • BLUECONIC_HOSTNAME

  • BLUECONIC_SUPPORT_ACCESS_SETTING

  • CHANNEL

  • CLEAN_UP_RULE

  • CONNECTION

  • DASHBOARD

  • DIALOGUE

  • DOMAIN_GROUP

  • GROUP

  • GROUP_TYPE

  • IP_RANGE

  • LANGUAGE

  • LIFECYCLE

  • LISTENER

  • MERGE_RULE

  • NOTEBOOK

  • OBJECTIVE

  • PLUGIN

  • PRIVACY_SETTING

  • PROFILE

  • PROFILE_PROPERTY

  • ROLE

  • SEGMENT

  • SINGLE_SIGN_ON_SETTING

  • SUPPORTED_LEGISLATION_ZONE

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

  • For PRIVACY_SETTING and SINGLE_SIGN_ON_SETTING, the objectId is the name(s) of the changed setting. E.g. Status, Identity_Provider_Issuer_URL_Entity_ID.

  • For BLUECONIC_SUPPORT_ACCESS_SETTING the objectID contains the new settings.

    • "objects" : [ {"name" : "No Access", "id" : "none" } ] or

    • "objects" : [ {"name" : "User name here", "id" : "[email protected]" },{"name" : "User name 2 here", "id" : "[email protected]" }], (contains the new list) or

    • "objects" : [ {"name" : "All BlueConic support employees", "id" : "all" } ],

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.

For PRIVACY_SETTING and SINGLE_SIGN_ON_SETTING, the objectName is the name(s) of the changed setting. E.g. Status, Identity_Provider_Issuer_URL_Entity_ID.

For BLUECONIC_SUPPORT_ACCESS_SETTING the objectName contains the new settings.

  • "objects" : [ {"name" : "No Access", "id" : "none" } ] or

  • "objects" : [ {"name" : "User name here", "id" : "[email protected]" },{"name" : "User name 2 here", "id" : "[email protected]" }], (contains the new list) or

  • "objects" : [ {"name" : "All BlueConic support employees", "id" : "all" } ],

operation

Action performed on the object.

  • CREATE

  • UPDATE

  • DELETE

  • EDITOR_RUN

  • READ

  • LOGIN

  • LOGIN_FAILED

  • LOGOUT

  • MANUAL_RUN

  • PASSWORD_RESET_REQUESTED

  • PASSWORD_CHANGE

  • SCHEDULED_RUN

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

Related Articles
Overview: BlueConic REST API
Using the BlueConic REST API v2
BlueConic REST API migration
Guide for Migration from BlueConic API v1 to v2
Q3-2023 BlueConic Release Notes
Did this answer your question?