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.

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.



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.

Create new profile

Synopsis POST /rest/profiles
Description Creates a new BlueConic 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.
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 /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>

Get one profile

Synopsis GET /rest/profiles/[profile]
Description Retrieves the properties of the specified profile, including the IDs of the matching dynamic segments.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path profile Yes String null any UUID The ID of the profile
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Querystring expand No String null "profile.permissions.exceptions" Specifies to include the permission level exceptions in the result.
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 /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>e-mail</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>

Update a profile

Synopsis PUT /rest/profiles/[profile]
Description Updates an existing BlueConic profile with 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 /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>

Update or create multiple profiles at once (bulk) 

Synopsis PUT /rest/profiles
Description

Update or create multiple profiles in a single request. This API call should be used when modifying large numbers of profiles instead of doing separate calls for each profile.

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 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.
domainGroupId 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).
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

 

Strategy

The following values are valid property rule strategies.

Name

Description

ADD

Values will be added to the values that already existed in the profile property. Duplicates will not be added.

SET

Values will overwrite the values that already existed in the profile property.

SET_IF_EMPTY

Only set values if the profile property is empty.
   

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 /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"
    }],
    "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:
    • Zipcodes 02111 and 02112 will be added
    • Email address will be set to jane@example.com
    • crm_id will be set to 002wC4BadR1w
    If no match can be found, a new profile is created in the specified domain and the three properties will be set in it.

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

[{
      "state": "CREATED",
      "profileId": "profile-UUID of the created profile",
      "identifier": " my-external-identifier"
}]

Set the permission level of a profile

Synopsis PUT /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 /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 /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 /rest/profiles/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3/permissions/exceptions/optIn/plugins
ids=plugin1&ids=plugin2

Update one profile property

Synopsis PUT /rest/profiles/[profile]/properties/[property]
Description Sets the values of a property in a 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
Path property Yes String null any property id The ID of the property to update.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Form values Yes String[] null any String The values 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 /rest/profiles/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3/properties/hobby
values=soccer&values=tennis

Delete one profile

Synopsis DELETE /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 /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>e-mail</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>

Search for profiles

Synopsis GET /rest/profiles
Description Searches for BlueConic profiles based on a specific values for an indexed 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 (not implemented).
  • 503 - The server is too busy to handle the request.
Example Request 
GET /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>

Profile Event methods

The following methods allow you to retrieve profile event information.

Get events for a profile

Synopsis GET /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 /rest/profileEvents/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileEvents>
  <events>
    <itemsPerPage>20</itemsPerPage>
    <startIndex>0</startIndex>
    <totalPages>1</totalPages>
    <totalResults>1</totalResults>
    <event>
      <date>2012-08-17T14:31+0200</date>
      <properties>
        <property>
          <id>ToLevel</id>
          <values>
            <value>ANONYMOUS</value>
          </values>
        </property>
        <property>
          <id>FromLevel</id>
          <values>
            <value>PERSONAL</value>
          </values>
        </property>
      </properties>
      <type>PermissionLevelChanged</type>
    </event>
  </events>
  <profile>
    <id>7bce7bfe-f433-4be4-82f2-5018c6dff5b2</id>
  </profile>
</profileEvents>

Interaction methods

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

Get interactions

Synopsis GET /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 /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 /rest/pageviewEvents
Description Registers pageview events for reporting.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Querystring url Yes String null any URL The URL of the current page.
Querystring referrer No String null any URL The URL of the previous (referring) page.
Querystring profile No String null any UUID The ID of the profile that triggered the event. For this profile, the properties "lastvisit", "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 /rest/interactionEvents
Description Registers interaction events for reporting.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Querystring type Yes String null "VIEW", "CLICK", "CONVERSION" The event type.
Querystring interaction Yes String null any UUID The ID of the interaction.
Querystring url Yes String null any URL The URL of the current page.
Authentication No
Responses
  • 200 - No specific content.
  • 400 - One or more required parameters is missing or invalid.
  • 503 - The server is too busy to handle the request.

URL mapping methods

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

Create new URL mapping

Synopsis POST /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 /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 /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 /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 /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 /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 /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 /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>
              http://blueconic.example.com/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>
          http://blueconic.example.com/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326?alt=xml
        </href>
        <rel>self</rel>
        <type>xml</type>
      </link>
    </links>
    <logo>
      <link>
        <href>
          http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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 /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 /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>
          http://blueconic.example.com/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>
              http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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>
            http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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>
            http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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>
            http://blueconic.example.com/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 /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 /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>
          http://blueconic.example.com/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>
          http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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 /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 /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>
        http://blueconic.example.com/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>
    <category>
      <id>technical_info</id>
      <name>
        <label locale="en_US">Technical Info</label>
        <label locale="nl_NL">Technische info</label>
      </name>
      <links>
        <link>
          <href>
            http://blueconic.example.com/rest/profilePropertyCategories/technical_info?alt=application/xml
          </href>
          <rel>self</rel>
          <type>application/xml</type>
        </link>
      </links>
    </category>
    <links>
      <link>
        <href>
          http://blueconic.example.com/rest/profileProperties/osversion?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </profileProperty>
  <profileProperty>
    <description>
      <label locale="en_US">
        The total number of times a website visitor has viewed a web page in your universe during the
        current visit.
      </label>
      <label locale="nl_NL">
        Het aantal keer dat de website bezoeker een webpagina binnen het universum heeft bezocht binnen
        het huidige bezoek dat hij brengt.
      </label>
    </description>
    <filterType>RANGE</filterType>
    <id>visitclicks</id>
    <indexed>false</indexed>
    <name>
      <label locale="nl_NL">Pagina impressies (huidig bezoek)</label>
      <label locale="en_US">Page Views (current visit)</label>
    </name>
    <unit>
      <id>views</id>
      <name>
        <label locale="nl_NL">Impressies</label>
        <label locale="en_US">Views</label>
      </name>
    </unit>
    <category>
      <id>statistics</id>
      <name>
        <label locale="nl_NL">Statistieken</label>
        <label locale="en_US">Statistics</label>
      </name>
      <links>
        <link>
          <href>
            http://blueconic.example.com/rest/profilePropertyCategories/statistics?alt=application/xml
          </href>
          <rel>self</rel>
          <type>application/xml</type>
        </link>
      </links>
    </category>
    <links>
      <link>
        <href>
          http://blueconic.example.com/rest/profileProperties/visitclicks?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </profileProperty>
</profileProperties>

Get one profile property

Synopsis GET /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 /rest/profileProperties/clickcount
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileProperty>
  <description>
    <label locale="en_US">
        The total number of times a website visitor has viewed a web page in your universe during all visits
        (metered over time).
    </label>
    <label locale="nl_NL">
        Het aantal keer dat de website bezoeker een webpagina binnen het universum heeft bezocht
        (gemeten over alle bezoeken).
    </label>
  </description>
  <filterType>RANGE</filterType>
  <id>clickcount</id>
  <indexed>false</indexed>
  <name>
    <label locale="en_US">Page Views (all visits)</label>
    <label locale="nl_NL">Pagina impressies (alle bezoeken)</label>
  </name>
  <unit>
    <id>views</id>
    <name>
      <label locale="nl_NL">Impressies</label>
      <label locale="en_US">Views</label>
    </name>
  </unit>
  <category>
    <id>statistics</id>
    <name>
      <label locale="en_US">Statistics</label>
      <label locale="nl_NL">Statistieken</label>
    </name>
    <links>
      <link>
        <href>
          http://blueconic.example.com/rest/profilePropertyCategories/statistics?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </category>
  <links>
    <link>
     <href>
       http://blueconic.example.com/rest/profileProperties/clickcount?alt=application/json
     </href>
     <rel>alt</rel>
     <type>application/json</type>
   </link>
  </links>
</profileProperty>

Create/update profile property

Synopsis PUT /rest/profileProperties/[id]
Description Creates or updates a profile property.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path id Yes String None any id The ID of the profile property to create or update. A valid id may consist of letters, numbers, hyphens (-), and underscores (_) and is at least one character long
Form filterType No String None "SELECT", "RANGE", "DATETIME" The filtertype of the profile property.
Form indexed No Boolean False a Boolean Whether the profile property is indexed.
Form category No String None any String The category of the profile property.
Form unit No String None any String The unit of the profile property.
Form permissionLevel No PermissionLevel "PERSONAL" "DO_NOT_TRACK", "ANONYMOUS", "PERSONAL" The permission level of the profile property.
Form mergeStrategy No MergeStrategy None "BOTH", "SUM", "HIGHEST", "LOWEST", "LATEST", "KEEP_CURRENT" The merge strategy of the profile property.
Form name No String None any String The name of the profile property (for all locales).
Form description No String None any String The description of the profile property (for all locales).
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the created / updated profile property.
  • 400 - Either, the specified profile property exists but is created by a plugin and cannot be created / updated through REST, or the id, filtertype, permission level, or merge strategy is invalid.
  • 401 - Authentication failed (unauthorized).
  • 503 - The server is too busy to handle the request.
Example Request 
PUT /rest/profileProperties/myProperty
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileProperty>
  <filterType>RANGE</filterType>
  <id>myProperty</id>
  <indexed>false</indexed>
  <unit>
    <id>existingUnit</id>
    <name>
      <label locale="nl_NL">Existing Unit</label>
      <label locale="en_US">Bestaande eenheid</label>
    </name>
  </unit>
  <category>
    <id>existingCategory</id>
    <name>
      <label locale="en_US">Existing Category</label>
      <label locale="nl_NL">Bestaande categorie</label>
    </name>
    <links>
      <link>
        <href>
          http://blueconic.example.com/rest/profilePropertyCategories/myCategory?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </category>
  <links>
    <link>
     <href>
       http://blueconic.example.com/rest/profileProperties/myProperty?alt=application/json
     </href>
     <rel>alt</rel>
     <type>application/json</type>
   </link>
  </links>
</profileProperty>

Create/update profile property name labels

Synopsis PUT /rest/profileProperties/[id]/name/[locale]
Description Creates/updates profile property labels.
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.
Path locale Yes String None any String The locale for which the label is updated, e.g. "en_US"
Form value Yes String None any String The value of the updated label, e.g. "My own property"
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the created or updated profile property labels.
  • 400 - The specified profile property exists but is created by a plugin and its labels cannot be set.
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified profile property doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
PUT /rest/profileProperties/myProperty/name/en_US
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<name>
  <label locale="en_US">My own property</label>
</name>

Create/update profile property description labels

Synopsis PUT /rest/profileProperties/[id]/description/[locale]
Description Creates/updates profile property description labels.
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.
Path locale Yes String None any String The locale for which the label is updated, e.g. "en_US"
Form value Yes String None any String The value of the updated label, e.g. "my description"
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the created or updated profile property description labels.
  • 400 - The specified profile property exists but is created by a plugin and its description labels cannot be set.
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified profile property doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
PUT /rest/profileProperties/myProperty/description/en_US
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<description>
  <label locale="en_US">This is my profile property created through REST.</label>
</description>

Delete profile property

Synopsis DELETE /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 /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>
  <category>
    <id>existingCategory</id>
    <name>
      <label locale="en_US">Existing Category</label>
      <label locale="nl_NL">Bestaande categorie</label>
    </name>
    <links>
      <link>
        <href>
          http://blueconic.example.com/rest/profilePropertyCategories/myCategory?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </category>
  <links>
    <link>
     <href>
       http://blueconic.example.com/rest/profileProperties/myProperty?alt=application/json
     </href>
     <rel>alt</rel>
     <type>application/json</type>
   </link>
  </links>
</profileProperty>

Get all profile property categories

Synopsis GET /rest/profilePropertyCategories
Description Retrieves the profile property categories.
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.
Authentication Yes
Responses
  • 200 - Returns the profile property categories.
  • 401 - Authentication failed (unauthorized).
  • 503 - The server is too busy to handle the request.
Example Request 
GET /rest/profilePropertyCategories?startIndex=3&count=2
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profilePropertyCategories>
  <itemsPerPage>2</itemsPerPage>
  <startIndex>3</startIndex>
  <totalPages>3</totalPages>
  <totalResults>5</totalResults>
  <links>
    <link>
      <href>
        http://blueconic.example.com/rest/profilePropertyCategories?startIndex=3&count=2&alt=application/json
      </href>
      <rel>alt</rel>
      <type>application/json</type>
    </link>
  </links>
  <profilePropertyCategory>
    <id>personal_info</id>
    <name>
      <label locale="en_US">Personal Info</label>
      <label locale="nl_NL">Persoonlijke informatie</label>
    </name>
    <links>
      <link>
        <href>
          http://blueconic.example.com/rest/profilePropertyCategories/personal_info?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </profilePropertyCategory>
  <profilePropertyCategory>
    <id>statistics</id>
    <name>
      <label locale="nl_NL">Statistieken</label>
      <label locale="en_US">Statistics</label>
    </name>
    <links>
      <link>
        <href>
          http://blueconic.example.com/rest/profilePropertyCategories/statistics?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </profilePropertyCategory>
</profilePropertyCategories>

Get one profile property category

Synopsis GET /rest/profilePropertyCategories/[id]
Description Retrieves a single profile property category.
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 category.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the profile property category.
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified profile property category doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
GET /rest/profilePropertyCategories/statistics
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profilePropertyCategory>
  <id>statistics</id>
  <name>
    <label locale="en_US">Statistics</label>
    <label locale="nl_NL">Statistieken</label>
  </name>
  <links>
    <link>
      <href>
        http://blueconic.example.com/rest/profilePropertyCategories/statistics?alt=application/json
      </href>
      <rel>alt</rel>
      <type>application/json</type>
    </link>
  </links>
</profilePropertyCategory>

Segment methods

The following methods allow you to retrieve properties from segments.

Get all segments

Synopsis GET /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 /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 /rest/segments/[id]/profiles
Description Retrieves the profiles of the segment.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path id Yes String None any id The ID of the segment.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Querystring startIndex No String 0 any number Specifies the index of the first item to include in the result.
Querystring count No String 20 smaller than or equal to 1.000.000 Specifies the number of results to return.
Authentication Yes
Responses
  • 200 - Returns the segment export.
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified segment doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
GET /rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=xml&startIndex=2&count=2
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profiles>
  <itemsPerPage>2</itemsPerPage>
  <startIndex>2</startIndex>
  <totalPages>1</totalPages>
  <totalResults>2</totalResults>
  <links>
    <link>
      <href>
        http://blueconic.example.com/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
          /profiles?alt=xml&startIndex=0&count=2
      </href>
      <rel>first</rel>
      <type>xml</type>
    </link>
    <link>
      <href>
        http://blueconic.example.com/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
          /profiles?alt=xml&startIndex=0&count=2
      </href>
      <rel>previous</rel>
      <type>xml</type>
      </link>
    <link>
      <href>
        http://blueconic.example.com/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
          /profiles?alt=xml&startIndex=4&count=2
      </href>
      <rel>next</rel>
      <type>xml</type>
    </link>
    <link>
      <href>
        http://blueconic.example.com/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
          /profiles?alt=xml&startIndex=10&count=2
      </href>
      <rel>last</rel>
      <type>xml</type>
    </link>
  </links>
  <profile>
    <id>45e2a650-ca17-4e03-8e8d-12d00ed4d9b3</id>
    <properties>
      <property>
        <id>e-mail</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>

REST API example

In this section an expanded example of using the BlueConic REST API is described. In the example, a visitor who already has a BlueConic profile ("Profile A") in one channel in the BlueConic universe (website) visits a different channel in the universe (mobile) and, since the visitor is not recognized, a new visitor profile is created, in this case "Profile B". The new visitor profile is then populated with segment data based on his or her activity. By retrieving the visitor's second profile and searching for a matching property/value in the other profiles, it is determined that "Profile A" and "Profile B" belong to the same visitor. The profiles are then merged into "Profile A" and "Profile B" becomes inactive:

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

Retrieve the profile ID for "Profile B" from the cookie request

The visitor with "Profile B" sends a cookie request (BCSessionID) to the mobile channel. The ID from "Profile B" is retrieved from the request.

For example:

In this case, the profile ID from the cookie is:

99db747f-2061-43d3-a508-76a977a18ba4

Retrieve the visitor profile

Now that we have the BlueConic ID of "Profile B", we can retrieve the BlueConic profile (99db747f-2061-43d3-a508-76a977a18ba4):

GET /rest/profiles/99db747f-2061-43d3-a508-76a977a18ba4

Returns:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
  <id>99db747f-2061-43d3-a508-76a977a18ba4</id>
  <properties>
    <property>
      <id>e-mail</id>
      <values>
        <value>jsmith@blueconic.com</value>
      </values>
    </property>
    <property>
      <id>clickcount</id>
      <values>
        <value>11</value>
      </values>
    </property>
    <property>
      <id>device</id>
      <values>
        <value>iPhone</value>
      </values>
    </property>
    <property>
      <id>country</id>
      <values>
      <value>Netherlands</value>
      </values>
    </property>
  </properties>
</profile>

Retrieve the BlueConic profile ID(s) with the matching e-mail address

Now that we know the e-mail address, we can retrieve other BlueConic profile(s) based on the known property to see if there are any other profiles containing the same e-mail address. Note: A property must be indexed in order to be retrievable using this method.

GET /rest/profiles?alt=xml&property=e-mail&value=jsmith@blueconic.com

Returns:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profiles total="2">
  <profile>
    <id>1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6</id>
  </profile>
  <profile>
    <id>99db747f-2061-43d3-a508-76a977a18na4</id>
  </profile>
</profiles>

Retrieve the profile that matches the property

In the previous step we retrieved the profile ID(s) that match the specified e-mail address. You can now retrieve the profile that matches the profile ("Profile A" in this case).

GET /rest/profile/1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6

Returns:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
  <id>1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6</id>
  <properties>
    <property>
      <id>name</id>
      <values>
        <value>John Smith</value>
      </values>
    </property>
    <property>
      <id>e-mail</id>
      <values>
        <value>jsmith@blueconic.com</value>
      </values>
    </property>
    <property>
      <id>visitclicks</id>
      <values>
        <value>7</value>
      </values>
    </property>
    <property>
      <id>preferences</id>
      <values>
        <value>Football</value>
        <value>Ajax</value>
      </values>
    </property>
  </properties>
</profile>

Merge profiles

Now that know that the two profiles belong to the same visitor, we can merge the profiles. To do so, the values from one profile are added to the other in a merge operation. In addition to merging the values, you must also indicate which profile is the master profile, that is, the one that contains all profile properties that have been gathered by both profiles. Once you determine which profile will be the master, you indicate in the profile that will become inactive the ID of the profile that replaces it. All future requests for the inactive profile are rerouted to the master profile. You must decide in your implementation the criteria that determine which profile becomes the master.

Using the PUT /rest/profiles/[profile]/properties/[property] method, you can individually write all the desired properties present in "Profile B" to "Profile A" using name/value pairs. A separate method call for each name/value pair is required.

The result:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
  <id>1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6</id>
  <properties>
    <property>
      <id>name</id>
      <values>
        <value>John Smith</value>
      </values>
    </property>
    <property>
      <id>e-mail</id>
      <values>
        <value>jsmith@blueconic.com</value>
      </values>
    </property>
    <property>
      <id>visitclicks</id>
      <values>
        <value>7</value>
      </values>
    </property>
    <property>
      <id>preferences</id>
      <values>
        <value>Football</value>
        <value>Ajax</value>
      </values>
    </property>
    <property>
      <id>clickcount</id>
      <values>
        <value>11</value>
      </values>
    </property>
    <property>
      <id>device</id>
      <values>
        <value>iPhone</value>
      </values>
    </property>
    <property>
      <id>country</id>
      <values>
      <value>Netherlands</value>
      </values>
    </property>
  </properties>
</profile>

Replace "Profile B" with "Profile A"

Now that the properties are merged into "Profile A", you want to indicate in "Profile B" that it has been replaced by "Profile A". As a result, all future requests for "Profile B" will be routed to "Profile A". The following method replaces "Profile B" with "Profile A", in the body, you include the "replaceBy" parameter and the ID of the profile that replaces the current profile. In this case profile ID 1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6 replaces 99db747f-2061-43d3-a508-76a977a18ba4:

PUT /rest/profiles/99db747f-2061-43d3-a508-76a977a18ba4
replaceBy=1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6

Returns:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
  <id>99db747f-2061-43d3-a508-76a977a18ba4</id>
  <replaceBy>
    <profile>
    <id>1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6</id>
    </profile>
  </replaceBy>
  <properties>
    <property>
      <id>e-mail</id>
      <values>
        <value>jsmith@blueconic.com</value>
      </values>
    </property>
    <property>
      <id>clickcount</id>
      <values>
        <value>11</value>
      </values>
    </property>
    <property>
      <id>device</id>
      <values>
        <value>iPhone</value>
      </values>
    </property>
    <property>
      <id>country</id>
      <values>
      <value>Netherlands</value>
      </values>
    </property>
  </properties>
</profile>