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 https://yourserver.blueconic.net/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.
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>

Get one profile

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

Update a profile

Synopsis PUT https://yourserver.blueconic.net/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 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>

Update or create multiple profiles at once (bulk) 

Synopsis PUT https://yourserver.blueconic.net/rest/profiles
PUT https://yourserver.blueconic.net/rest/profiles?objectiveIds=objectiveID_1,objectiveID_2
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 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 in the “GDPR” privacy legislation zone.
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 GDPR 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 “GDPR”, “NONE” 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

The following properties have a special meaning:
“privacy_legislation”: the value passed in this property should either be “GDPR” or “NONE”, 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

Privacy legislation

The following values are valid privacy legislation values.

Name Description
GDPR Indicates that a profile is in the “GDPR zone”. 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.
NONE The profile is not in the GDPR zone; profile will just be created.

Strategy

The following values are valid property rule strategies.

Name Description
ADD Values will be added to the values that already existed in the profile property. Duplicates will not be added.
SET Values will overwrite the values that already existed in the profile property.
SET_IF_EMPTY Only set values if the profile property is empty.
   
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"
    }],
    "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
    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" or “CONSENT_MISMATCH”.

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

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

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>

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>

Profile Event methods

The following methods allow you to retrieve profile event information.

Get events for a profile

Synopsis GET https://yourserver.blueconic.net/rest/profileEvents/[profile]
Description Retrieves the events of a profile.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path profile Yes String null any UUID The ID of the profile
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the events.
  • 401 - Authentication failed (unauthorized).
  • 404 - The profile never existed.
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/profileEvents/45e2a650-ca17-4e03-8e8d-12d00ed4d9b3
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileEvents>
  <events>
    <itemsPerPage>20</itemsPerPage>
    <startIndex>0</startIndex>
    <totalPages>1</totalPages>
    <totalResults>1</totalResults>
    <event>
      <date>2012-08-17T14:31+0200</date>
      <properties>
        <property>
          <id>ToLevel</id>
          <values>
            <value>ANONYMOUS</value>
          </values>
        </property>
        <property>
          <id>FromLevel</id>
          <values>
            <value>PERSONAL</value>
          </values>
        </property>
      </properties>
      <type>PermissionLevelChanged</type>
    </event>
  </events>
  <profile>
    <id>7bce7bfe-f433-4be4-82f2-5018c6dff5b2</id>
  </profile>
</profileEvents>

Interaction methods

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

Get interactions

Synopsis GET https://yourserver.blueconic.net/rest/interactions
Description Retrieves the interactions for a page view.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Querystring url Yes String null any URL The URL of the current page.
Querystring profile No String null any UUID The ID of the profile.
Authentication No
Responses
  • 200 - Returns the interactions.
  • 400 - One or more required parameters is missing or invalid.
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/interactions?profile=45e2a650-ca17-4e03-8e8d-12d00ed4d9b3&url=http%3A%2F%2Fwww.example.com%2F
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<interactions total="2">
  <interaction>
    <defaultLocale>nl_NL</defaultLocale>
    <id>6d2dc916-08ce-412f-aa5d-f75eb95f8a9c</id>
    <name>Sample Interactions</name>
    <parameters>
      <parameter>
        <id>sampleparameter</id>
        <values locale="en_US">
          <value>en 1</value>
          <value>en 2</value>
        </values>
        <values locale="nl_NL">
          <value>dutch</value>
        </values>
      </parameter>
      <parameter>
        <id>width</id>
        <values locale="en_US">
          <value>800</value>
        </values>
        <values locale="nl_NL">
          <value>800</value>
        </values>
      </parameter>
    </parameters>
    <position>position_1</position>
  </interaction>
  <interaction>
    <defaultLocale>nl_NL</defaultLocale>
    <id>demolistenerinteractiontype</id>
    <name>demolistenerinteractiontype</name>
  </interaction>
</interactions>

Register pageview events

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

URL mapping methods

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

Create new URL mapping

Synopsis POST https://yourserver.blueconic.net/rest/urlmappings
Description Creates a new URL mapping.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Form url Yes String null any URL The target URL of the mapping.
Authentication Yes
Responses
  • 200 - Returns the created urlmapping.
  • 400 - One or more required parameters is missing or invalid.
  • 401 - Authentication failed (unauthorized).
  • 503 - The server is too busy to handle the request.
Example Request 
POST https://yourserver/rest/urlmappings?alt=xml
url=http%3A%2F%2Fwww.example.com
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<urlmapping>
  <id>4Q</id>
  <properties />
  <url>http://www.example.com</url>
</urlmapping>

Get one URL mapping

Synopsis GET https://yourserver.blueconic.net/rest/urlmappings/[urlmapping]
Description Retrieves the metadata of the specified URL mapping.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path urlmapping Yes String null any UUID The ID of the URL mapping.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the urlmapping.
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified URL mapping doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/urlmappings/4Q
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<urlmapping>
  <id>4Q</id>
  <properties />
  <url>http://www.example.com</url>
</urlmapping>

Update URL mapping properties

Synopsis PUT https://yourserver.blueconic.net/rest/urlmappings/[urlmapping]/properties
Description Updates the stored properties of the specified URL mapping.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path urlmapping Yes String null any UUID The ID of the URL mapping.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Form property=value Yes String null any name-value pair The property and value to set, multiple values for properties are allowed.
Authentication Yes
Responses
  • 200 - Returns the urlmapping.
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified URL mapping doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
PUT https://yourserver.blueconic.net/rest/urlmappings/4Q/properties?alt=xml
property1=value1&property1=value2&property2=value3
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<urlmapping>
  <id>4Q</id>
  <properties>
    <property>
      <id>property1</id>
      <values>
        <value>value1</value>
        <value>value2</value>
      </values>
    </property>
    <property>
      <id>property2</id>
      <values>
        <value>value3</value>
      </values>
    </property>
  </properties>
  <url>http://www.example.com</url>
</urlmapping>

Domain methods

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

Get all domains

Synopsis GET https://yourserver.blueconic.net/rest/domains
Description Retrieves the domains.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Querystring startIndex No String 0 any number Specifies the index of the first item to include in the result.
Querystring count No String 20 any number Specifies the number of results to return.
Authentication Yes
Responses
  • 200 - Returns the domains.
  • 401 - Authentication failed (unauthorized).
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/domains
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains>
  <itemsPerPage>20</itemsPerPage>
  <startIndex>0</startIndex>
  <totalPages>1</totalPages>
  <totalResults>1</totalResults>
  <domain>
    <channels>
      <channel>
        <aliases>
          <alias>alias2</alias>
          <alias>alias3</alias>
          <alias>alias1</alias>
        </aliases>
        <hostname>www.example.com</hostname>
        <id>da94cd6a-c741-4962-9feb-492fed796b26</id>
        <links>
          <link>
            <href>
              https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326
                /channels/da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
            </href>
            <rel>self</rel>
            <type>xml</type>
          </link>
        </links>
        <name>Example channel</name>
        <type>WEBSITE</type>
        <visitorCount>0</visitorCount>
      </channel>
    </channels>
    <id>885f0954-fd4e-4a08-a987-e2a047c9f326</id>
    <links>
      <link>
        <href>
          https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326?alt=xml
        </href>
        <rel>self</rel>
        <type>xml</type>
      </link>
    </links>
    <logo>
      <link>
        <href>
          https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/logo
            ?etag=005310aba7fd1ef3ff0223ca166b9c
        </href>
        <rel>self</rel>
      </link>
    </logo>
    <name>Test domain 1327052341899</name>
    <visitorCount>0</visitorCount>
  </domain>
</domains>

Get one domain

Synopsis GET https://yourserver.blueconic.net/rest/domains/[domainid]
Description Retrieves a single domain.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the domain.
  • 401 - Authentication failed (unauthorized).
  • 404 - The domain doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain>
  <channels />
  <id>bf6af51d-b077-4565-9bac-8a97d42f807c</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <logo />
  <name>Example domain 2</name>
  <visitorCount>0</visitorCount>
</domain>

Create new domain

Synopsis POST https://yourserver.blueconic.net/rest/domains
Description Creates a domain.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Form name No String null any String The name of the domain.
Authentication Yes
Responses
  • 200 - Returns the created domain.
  • 401 - Authentication failed (unauthorized).
  • 503 - The server is too busy to handle the request.
Example Request 
POST https://yourserver.blueconic.net/rest/domains
name=Example+domain
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain>
  <channels />
  <id>bf6af51d-b077-4565-9bac-8a97d42f807c</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <logo />
  <name>Example domain</name>
  <visitorCount>0</visitorCount>
</domain>

Update a domain

Synopsis PUT https://yourserver.blueconic.net/rest/domains/[domain]
Description Updates a domain.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domain Yes String null any UUID The ID of the domain.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Form name No String null any String The name of the domain.
Authentication Yes
Responses
  • 200 - Returns the updated domain.
  • 401 - Authentication failed (unauthorized).
  • 404 - The domain doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
PUT https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c
name=Example+domain+2
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain>
  <channels />
  <id>bf6af51d-b077-4565-9bac-8a97d42f807c</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <logo />
  <name>Example domain 2</name>
  <group>9efb8a28-bfdf-4a10-b4f4-c0fb3a9a8dcc</group>
  <visitorCount>0</visitorCount>
</domain>

Delete a domain

Synopsis DELETE https://yourserver.blueconic.net/rest/domains/[domainid]
Description Updates a domain.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the deleted domain.
  • 401 - Authentication failed (unauthorized).
  • 404 - The domain doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
DELETE https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain>
  <channels />
  <id>bf6af51d-b077-4565-9bac-8a97d42f807c</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <logo />
  <name>Example domain 2</name>
  <visitorCount>0</visitorCount>
</domain>

Get channels of a domain

Synopsis GET https://yourserver.blueconic.net/rest/domains/[domainid]/channels
Description Retrieves all channels of a domain.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns all channels.
  • 401 - Authentication failed (unauthorized).
  • 404 - The domain doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<channels>
  <channel>
    <aliases>
      <alias>alias2</alias>
      <alias>alias3</alias>
      <alias>alias1</alias>
    </aliases>
    <hostname>www.example.com</hostname>
    <id>da94cd6a-c741-4962-9feb-492fed796b26</id>
    <links>
      <link>
        <href>
          https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326
            /channels/da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
        </href>
        <rel>self</rel>
        <type>xml</type>
      </link>
    </links>
    <name>Example channel</name>
    <positions>
      <position>
        <id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
        <links>
          <link>
            <href>
              https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
                /da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
            </href>
            <rel>self</rel>
            <type>xml</type>
          </link>
        </links>
      </position>
    </positions>
    <type>WEBSITE</type>
    <visitorCount>0</visitorCount>
  </channel>
</channels>

Get one channel

Synopsis GET https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]
Description Retrieves a single channel.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Path channelid Yes String null any UUID The ID of the channel.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the channel.
  • 401 - Authentication failed (unauthorized).
  • 404 - The channel doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<channel>
  <aliases>
    <alias>alias2</alias>
    <alias>alias3</alias>
    <alias>alias1</alias>
  </aliases>
  <hostname>www.example.com</hostname>
  <id>da94cd6a-c741-4962-9feb-492fed796b26</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
          /da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <name>Example channel</name>
  <positions>
    <position>
      <id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
      <links>
        <link>
          <href>
            https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
              /da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
          </href>
          <rel>self</rel>
          <type>xml</type>
        </link>
      </links>
    </position>
  </positions>
  <type>WEBSITE</type>
  <visitorCount>0</visitorCount>
</channel>

Create new channel

Synopsis POST https://yourserver.blueconic.net/rest/domains/[domainid]/channels
Description Creates a channel.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Form name No String null any String The name of the channel.
Authentication Yes
Responses
  • 200 - Returns the created channel.
  • 401 - Authentication failed (unauthorized).
  • 404 - The domain doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
POST https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
name=Example+channel
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<channel>
  <aliases/>
  <id>da94cd6a-c741-4962-9feb-492fed796b26</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
          /da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <name>Example channel</name>
  <positions/>
  <type>WEBSITE</type>
  <visitorCount>0</visitorCount>
</channel>

Update a channel

Synopsis PUT https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]
Description Updates a channel.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Path channelid Yes String null any UUID The ID of the channel.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Form name No String null any String The name of the channel.
Form type No String null "WEBSITE", "EMAIL", "TWITTER", or "FACEBOOK" The type of the domain.
Form hostname No String null any String The hostname of the channel.
Form alias No String null any String The zero or more aliases of the channel.
Authentication Yes
Responses
  • 200 - Returns the updated channel.
  • 400 - An invalid channel type was specified.
  • 401 - Authentication failed (unauthorized).
  • 404 - The channel doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
PUT https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26
name=Example+channel&type=WEBSITE&hostname=www.example.com&alias=alias1&alias=alias2&alias=alias3
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<channel>
  <aliases>
    <alias>alias2</alias>
    <alias>alias3</alias>
    <alias>alias1</alias>
  </aliases>
  <hostname>www.example.com</hostname>
  <id>da94cd6a-c741-4962-9feb-492fed796b26</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
          /da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <name>Example channel</name>
  <positions>
    <position>
      <id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
      <links>
        <link>
          <href>
            https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
              /da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
          </href>
          <rel>self</rel>
          <type>xml</type>
        </link>
      </links>
    </position>
  </positions>
  <type>WEBSITE</type>
  <visitorCount>0</visitorCount>
</channel>

Delete a channel

Synopsis DELETE https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]
Description Deletes a channel.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Path channelid Yes String null any UUID The ID of the channel.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the deleted channel.
  • 401 - Authentication failed (unauthorized).
  • 404 - The channel doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
DELETE https://yourserver.blueconic.net/rest/domains/bf6af51d-b077-4565-9bac-8a97d42f807c
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<channel>
  <aliases>
    <alias>alias2</alias>
    <alias>alias3</alias>
    <alias>alias1</alias>
  </aliases>
  <hostname>www.example.com</hostname>
  <id>da94cd6a-c741-4962-9feb-492fed796b26</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
          /da94cd6a-c741-4962-9feb-492fed796b26?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <name>Example channel</name>
  <positions>
    <position>
      <id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
      <links>
        <link>
          <href>
            https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
              /da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
          </href>
          <rel>self</rel>
          <type>xml</type>
        </link>
      </links>
    </position>
  </positions>
  <type>WEBSITE</type>
  <visitorCount>0</visitorCount>
</channel>

Get positions of a channel

Synopsis GET https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]/positions
Description Retrieves all positions of a channel.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Path channelid Yes String null any UUID The ID of the channel.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns all positions of a channel.
  • 401 - Authentication failed (unauthorized).
  • 404 - The channel doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26/positions
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<positions>
  <position>
    <id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
    <links>
      <link>
        <href>
          https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
            /da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
        </href>
        <rel>self</rel>
        <type>xml</type>
      </link>
    </links>
    <name>New position</name>
  </position>
  <position>
    <id>c3633c12-8ed4-45c7-ac31-d95921648189</id>
    <links>
      <link>
        <href>
          https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
            /da94cd6a-c741-4962-9feb-492fed796b26/positions/c3633c12-8ed4-45c7-ac31-d95921648189?alt=xml
        </href>
        <rel>self</rel>
        <type>xml</type>
      </link>
    </links>
    <name>New position</name>
  </position>
</positions>

Get one position

Synopsis GET https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]/positions/[positionid]
Description Retrieves a single position.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Path channelid Yes String null any UUID The ID of the channel.
Path positionid Yes String null any UUID The ID of the position.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the position.
  • 401 - Authentication failed (unauthorized).
  • 404 - The position doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<position>
  <id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
          /da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <name>Banner 01</name>
  <positionIdentifier>banner01</positionIdentifier>
</position>

Create new position

Synopsis POST https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]/positions
Description Creates a position.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Path channelid Yes String null any UUID The ID of the channel.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Form name No String null any String The name of the position.
Authentication Yes
Responses
  • 200 - Returns the created position.
  • 401 - Authentication failed (unauthorized).
  • 404 - The channel doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
POST https://yourserver.blueconic.com/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26/positions
name=Banner+01
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<position>
  <id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
          /da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <name>Banner 01</name>
</position>

Update a position

Synopsis PUT https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]/positions/[positionid]
Description Updates a position.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Path channelid Yes String null any UUID The ID of the channel.
Path positionid Yes String null any UUID The ID of the position.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Form name No String null any String The name of the position.
Form positionIdentifier No String null any String The identifier of the position, e.g. the ID of a DIV.
Authentication Yes
Responses
  • 200 - Returns the updated position.
  • 401 - Authentication failed (unauthorized).
  • 404 - The position doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
PUT https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2
name=Banner+01&positionIdentifier=banner01
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<position>
  <id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
          /da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <name>Banner 01</name>
  <positionIdentifier>banner01</positionIdentifier>
</position>

Delete a position

Synopsis DELETE https://yourserver.blueconic.net/rest/domains/[domainid]/channels/[channelid]/positions/[positionid]
Description Updates a position.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path domainid Yes String null any UUID The ID of the domain.
Path channelid Yes String null any UUID The ID of the channel.
Path positionid Yes String null any UUID The ID of the position.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the deleted position.
  • 401 - Authentication failed (unauthorized).
  • 404 - The position doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
DELETE https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels/da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<position>
  <id>b33db6d6-93da-4275-aa68-2e87e27d06c2</id>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/domains/885f0954-fd4e-4a08-a987-e2a047c9f326/channels
          /da94cd6a-c741-4962-9feb-492fed796b26/positions/b33db6d6-93da-4275-aa68-2e87e27d06c2?alt=xml
      </href>
      <rel>self</rel>
      <type>xml</type>
    </link>
  </links>
  <name>Banner 01</name>
  <positionIdentifier>banner01</positionIdentifier>
</position>

Profile property methods

The following methods allow you to retrieve profile properties.

Get all profile properties

Synopsis GET https://yourserver.blueconic.net/rest/profileProperties
Description Retrieves the profile properties.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Querystring count No String 20 any integer Specifies the number of results to return.
Querystring startIndex No String 0 any integer Specifies the index of the first item to include in the result.
Querystring filterType No String no filtering "SELECT", "RANGE", "DATETIME" The filterType of the profile properties e.g "SELECT", "RANGE" AND "DATETIME". Multiple values are allowed.
Querystring filterValue No String no filtering any filter If specified, a label of the name of the profile properties must match the value. The label with the matching filterLocale is used. If this is not specified, then all name labels are checked. If no labels exist, then the id is checked.
Querystring filterLocale No String all locales any locale The locale for filtering on the name label, e.g. "nl_NL" or "en_US".
Authentication Yes
Responses
  • 200 - Returns the profile properties.
  • 401 - Authentication failed (unauthorized).
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/profileProperties?startIndex=4&count=2
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileProperties>
  <itemsPerPage>2</itemsPerPage>
  <startIndex>4</startIndex>
  <totalPages>14</totalPages>
  <totalResults>27</totalResults>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/profileProperties?startIndex=4&count=2&alt=application/json
      </href>
      <rel>alt</rel>
      <type>application/json</type>
    </link>
  </links>
  <profileProperty>
    <filterType>SELECT</filterType>
    <id>osversion</id>
    <indexed>false</indexed>
    <name>
      <label locale="en_US">Operating System Version</label>
      <label locale="nl_NL">Operating systeem versie</label>
    </name>
    <category>
      <id>technical_info</id>
      <name>
        <label locale="en_US">Technical Info</label>
        <label locale="nl_NL">Technische info</label>
      </name>
      <links>
        <link>
          <href>
            https://yourserver.blueconic.net/rest/profilePropertyCategories/technical_info?alt=application/xml
          </href>
          <rel>self</rel>
          <type>application/xml</type>
        </link>
      </links>
    </category>
    <links>
      <link>
        <href>
          https://yourserver.blueconic.net/rest/profileProperties/osversion?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </profileProperty>
  <profileProperty>
    <description>
      <label locale="en_US">
        The total number of times a website visitor has viewed a web page in your universe during the
        current visit.
      </label>
      <label locale="nl_NL">
        Het aantal keer dat de website bezoeker een webpagina binnen het universum heeft bezocht binnen
        het huidige bezoek dat hij brengt.
      </label>
    </description>
    <filterType>RANGE</filterType>
    <id>visitclicks</id>
    <indexed>false</indexed>
    <name>
      <label locale="nl_NL">Pagina impressies (huidig bezoek)</label>
      <label locale="en_US">Page Views (current visit)</label>
    </name>
    <unit>
      <id>views</id>
      <name>
        <label locale="nl_NL">Impressies</label>
        <label locale="en_US">Views</label>
      </name>
    </unit>
    <category>
      <id>statistics</id>
      <name>
        <label locale="nl_NL">Statistieken</label>
        <label locale="en_US">Statistics</label>
      </name>
      <links>
        <link>
          <href>
            https://yourserver.blueconic.net/rest/profilePropertyCategories/statistics?alt=application/xml
          </href>
          <rel>self</rel>
          <type>application/xml</type>
        </link>
      </links>
    </category>
    <links>
      <link>
        <href>
          https://yourserver.blueconic.net/rest/profileProperties/visitclicks?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </profileProperty>
</profileProperties>

Get one profile property

Synopsis GET https://yourserver.blueconic.net/rest/profileProperties/[id]
Description Retrieves a single profile property.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path id Yes String None any id The ID of the profile property.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Authentication Yes
Responses
  • 200 - Returns the profile property.
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified profile property doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/profileProperties/clickcount
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileProperty>
  <description>
    <label locale="en_US">
        The total number of times a website visitor has viewed a web page in your universe during all visits
        (metered over time).
    </label>
    <label locale="nl_NL">
        Het aantal keer dat de website bezoeker een webpagina binnen het universum heeft bezocht
        (gemeten over alle bezoeken).
    </label>
  </description>
  <filterType>RANGE</filterType>
  <id>clickcount</id>
  <indexed>false</indexed>
  <name>
    <label locale="en_US">Page Views (all visits)</label>
    <label locale="nl_NL">Pagina impressies (alle bezoeken)</label>
  </name>
  <unit>
    <id>views</id>
    <name>
      <label locale="nl_NL">Impressies</label>
      <label locale="en_US">Views</label>
    </name>
  </unit>
  <category>
    <id>statistics</id>
    <name>
      <label locale="en_US">Statistics</label>
      <label locale="nl_NL">Statistieken</label>
    </name>
    <links>
      <link>
        <href>
          https://yourserver.blueconic.net/rest/profilePropertyCategories/statistics?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </category>
  <links>
    <link>
     <href>
       https://yourserver.blueconic.net/rest/profileProperties/clickcount?alt=application/json
     </href>
     <rel>alt</rel>
     <type>application/json</type>
   </link>
  </links>
</profileProperty>

Create/update profile property

Synopsis PUT https://yourserver.blueconic.net/rest/profileProperties/[id]
Description Creates or updates a profile property.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path id Yes String None any id The ID of the profile property to create or update. A valid id may consist of letters, numbers, hyphens (-), and underscores (_) and is at least one character long
Form filterType No String None "SELECT", "RANGE", "DATETIME" The filtertype of the profile property.
Form indexed No Boolean False a Boolean Whether the profile property is indexed (unique).
Form 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 https://yourserver.blueconic.net/rest/profileProperties/myProperty
XML Response 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileProperty>
  <filterType>RANGE</filterType>
  <id>myProperty</id>
  <indexed>false</indexed>
  <unit>
    <id>existingUnit</id>
    <name>
      <label locale="nl_NL">Existing Unit</label>
      <label locale="en_US">Bestaande eenheid</label>
    </name>
  </unit>
  <category>
    <id>existingCategory</id>
    <name>
      <label locale="en_US">Existing Category</label>
      <label locale="nl_NL">Bestaande categorie</label>
    </name>
    <links>
      <link>
        <href>
          https://yourserver.blueconic.net/rest/profilePropertyCategories/myCategory?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </category>
  <links>
    <link>
     <href>
       https://yourserver.blueconic.net/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 https://yourserver.blueconic.net/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 https://yourserver.blueconic.net/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 https://yourserver.blueconic.net/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 https://yourserver.blueconic.net/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 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>
  <category>
    <id>existingCategory</id>
    <name>
      <label locale="en_US">Existing Category</label>
      <label locale="nl_NL">Bestaande categorie</label>
    </name>
    <links>
      <link>
        <href>
          https://yourserver.blueconic.net/rest/profilePropertyCategories/myCategory?alt=application/xml
        </href>
        <rel>self</rel>
        <type>application/xml</type>
      </link>
    </links>
  </category>
  <links>
    <link>
     <href>
       https://yourserver.blueconic.net/rest/profileProperties/myProperty?alt=application/json
     </href>
     <rel>alt</rel>
     <type>application/json</type>
   </link>
  </links>
</profileProperty>

Segment methods

The following methods allow you to retrieve properties from segments.

Get all segments

Synopsis GET https://yourserver.blueconic.net/rest/segments
Description Retrieves the id and name of segments.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Querystring startIndex No String 0 any number Specifies the index of the first item to include in the result.
Querystring count No String 20 any number Specifies the number of results to return.
Authentication Yes
Responses
  • 200 - Returns the segments.
  • 401 - Authentication failed (unauthorized).
  • 503 - The server is too busy to handle the request.
Example Request 
 GET https://yourserver.blueconic.net/rest/segments

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<segments>
  <itemsPerPage>20</itemsPerPage>
  <startIndex>0</startIndex>
  <totalPages>1</totalPages>
  <totalResults>2</totalResults>
  <segment>
    <id>aac8d07f-030e-4ce3-b269-13e56d8e8181</id>
    <name>Example segment</name>
  </segment>
  <segment>
    <id>0cabb4ed-a5e8-4e6a-82e0-f7f409266697</id>
    <name>Example segment2</name>
  </segment>
</segments>

Get segment profiles

Synopsis GET https://yourserver.blueconic.net/rest/segments/[id]/profiles
Description Retrieves the profiles of the segment.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path id Yes String None any id The ID of the segment.
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Querystring startIndex No String 0 any number Specifies the index of the first item to include in the result.
Querystring count No String 20 smaller than or equal to 1.000.000 Specifies the number of results to return.
Querystring properties No String null One or more profile property ids, separated by a comma. Specifies for which profile properties values will be returned for each profile. If not specified, the values of all profile properties will be returned, which may result in a large result set.
Querystring expand No String null One of:
  • "profiles.profile.permissions"
  • "profiles.profile.replace"
  • "profiles.profile.segments"
 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 multiple "expand" querystring parameters to return combinations.
Authentication Yes
Responses
  • 200 - Returns the segment export.
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified segment doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
GET https://yourserver.blueconic.net/rest/segments/0bcd8a66-7462-423f-8178-02b4ddf59294/profiles?alt=xml&startIndex=2&count=2

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profiles>
  <itemsPerPage>2</itemsPerPage>
  <startIndex>2</startIndex>
  <totalPages>1</totalPages>
  <totalResults>2</totalResults>
  <links>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
          /profiles?alt=xml&startIndex=0&count=2
      </href>
      <rel>first</rel>
      <type>xml</type>
    </link>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
          /profiles?alt=xml&startIndex=0&count=2
      </href>
      <rel>previous</rel>
      <type>xml</type>
      </link>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
          /profiles?alt=xml&startIndex=4&count=2
      </href>
      <rel>next</rel>
      <type>xml</type>
    </link>
    <link>
      <href>
        https://yourserver.blueconic.net/rest/segments/aac8d07f-030e-4ce3-b269-13e56d8e8181
          /profiles?alt=xml&startIndex=10&count=2
      </href>
      <rel>last</rel>
      <type>xml</type>
    </link>
  </links>
  <profile>
    <id>45e2a650-ca17-4e03-8e8d-12d00ed4d9b3</id>
    <properties>
      <property>
        <id>email</id>
        <values>
          <value>info@test.com</value>
        </values>
      </property>
      <property>
        <id>hobby</id>
        <values>
          <value>soccer</value>
          <value>tennis</value>
        </values>
      </property>
    </properties>
  </profile>
  <profile>
    <id>9efb8a28-bfdf-4a10-b4f4-c0fb3a9a8dcc</id>
    <properties />
  </profile>
</profiles>

 

Objectives methods

The following methods allow you to control the consented and refused objectives of a profile

Update the privacy legislation of a profile

Synopsis PUT https://yourserver.blueconic.net/rest/profiles/[profile]/legislation
Description Updates the privacy legislation of an existing BlueConic profile.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path profile Yes String null any UUID The ID of the profile
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
Form privacyLegislation Yes String null "GDPR", "NONE" The new privacy legislation of the profile, either “GDPR” or “NONE”.
Authentication Yes
Responses
  • 200 - Returns the updated profile.
  • 400 - Bad request (invalid privacy legislation)
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified profile doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
PUT https://yourserver.blueconic.net/rest/profiles/f17e2071-4a00-4bfc-b16a-d78458801aa1/legislation?alt=xml&privacyLegislation=NONE

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
  <id> f17e2071-4a00-4bfc-b16a-d78458801aa1</id>
  <privacyLegislation>NONE</privacyLegislation>
  <replaceBy />
  <properties />
  <segments />
</profile>

 

Add consented objectives to a profile

Synopsis POST https://yourserver.blueconic.net/rest/profiles/[profile]/consentedObjectives
Description Updates the consented objectives of an existing BlueConic profile.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path profile Yes String null any UUID The ID of the profile
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
JSON Body   Yes Array of strings null List of objective UUID’s. The body of the request should contain the objective UUID’s that should be added to the list of existing consented objectives.
Authentication Yes
Responses
  • 200 - Returns the updated profile.
  • 400 - Bad request (empty body)
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified profile doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
POST https://yourserver.blueconic.net/rest/profiles/f17e2071-4a00-4bfc-b16a-d78458801aa1/consentedObjectives?alt=xml

JSON Body

["objective_id_1","objective_id_2"]

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
  <id> f17e2071-4a00-4bfc-b16a-d78458801aa1</id>
  <privacyLegislation>GDPR</privacyLegislation>
  <consentedObjectives>
    <objective>
      <id>objective_id_1</id>
    </objective>
    <objective>
      <id>objective_id_2</id>
    </objective>
  </consentedObjectives>
  <refusedObjectives/>
  <replaceBy />
  <properties />
  <segments />
</profile>

 

Set consented objectives of a profile

Synopsis PUT https://yourserver.blueconic.net/rest/profiles/[profile]/consentedObjectives
Description Set the consented objectives of an existing BlueConic profile.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path profile Yes String null any UUID The ID of the profile
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
JSON Body   Yes Array of strings null List of objective UUID’s. The body of the request should contain the objective UUID’s that should overwrite the list of existing consented objectives.
Authentication Yes
Responses
  • 200 - Returns the updated profile.
  • 400 - Bad request (empty body)
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified profile doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
PUT https://yourserver.blueconic.net/rest/profiles/f17e2071-4a00-4bfc-b16a-d78458801aa1/consentedObjectives?alt=xml

 

JSON Body

["objective_id_2"]

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
  <id> f17e2071-4a00-4bfc-b16a-d78458801aa1</id>
  <privacyLegislation>GDPR</privacyLegislation>
  <consentedObjectives>
    <objective>
      <id>objective_id_2</id>
    </objective>
  </consentedObjectives>
  <refusedObjectives />
  <replaceBy />
  <properties />
  <segments />
</profile>

 

Add refused objectives to a profile

Synopsis POST https://yourserver.blueconic.net/rest/profiles/[profile]/refusedObjectives
Description Updates the refused objectives of an existing BlueConic profile.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path profile Yes String null any UUID The ID of the profile
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
JSON Body   Yes Array of strings null List of objective UUID’s. The body of the request should contain the objective UUID’s that should be added to the list of existing refused objectives.
Authentication Yes
Responses
  • 200 - Returns the updated profile.
  • 400 - Bad request (empty body)
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified profile doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
POST https://yourserver.blueconic.net/rest/profiles/f17e2071-4a00-4bfc-b16a-d78458801aa1/refusedObjectives?alt=xml

 

JSON Body

["objective_id_1","objective_id_2"]

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
  <id> f17e2071-4a00-4bfc-b16a-d78458801aa1</id>
  <privacyLegislation>GDPR</privacyLegislation>
  <consentedObjectives />
  <refusedObjectives>
    <objective>
      <id>objective_id_1</id>
    </objective>
    <objective>
      <id>objective_id_2</id>
    </objective>
  <replaceBy />
  <properties />
  <segments />
</profile>

 

Set refused objectives of a profile

Synopsis PUT https://yourserver.blueconic.net/rest/profiles/[profile]/refusedObjectives
Description Set the refused objectives of an existing BlueConic profile.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Path profile Yes String null any UUID The ID of the profile
Querystring alt No String "xml" "xml", "json" Specifies the format in which to return the result.
JSON Body   Yes Array of strings null List of objective UUID’s. The body of the request should contain the objective UUID’s that should overwrite the list of existing refused objectives.
Authentication Yes
Responses
  • 200 - Returns the updated profile.
  • 400 - Bad request (empty body)
  • 401 - Authentication failed (unauthorized).
  • 404 - The specified profile doesn't exist.
  • 503 - The server is too busy to handle the request.
Example Request 
PUT https://yourserver.blueconic.net/rest/profiles/f17e2071-4a00-4bfc-b16a-d78458801aa1/refusedObjectives?alt=xml

 

JSON Body

["objective_id_2"]

 XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile>
  <id> f17e2071-4a00-4bfc-b16a-d78458801aa1</id>
  <privacyLegislation>GDPR</privacyLegislation>
  <refusedObjectives>
    <objective>
      <id>objective_id_2</id>
    </objective>
  </refusedObjectives>
  <consentedObjectives />
  <replaceBy />
  <properties />
  <segments />
</profile>

 

Generate recommendations

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

Synopsis POST https://yourserver.blueconic.net/rest/recommendations
Description Generate BlueConic recommendations for a specific profile based on the provided parameters.
Parameter(s)
Parameter Type Name Required Data Type Default Value(s) Description
Querystring profileId No String null Any UUID The ID of the BlueConic profile.
Querystring storeId Yes String null Any UUID The ID of the content store to get the items from.
Querystring itemId No String null Any string Optional ID of the current item being shown. Some algorithms are based on this information. It also excludes this item from being returned in the result.
Querystring frequencyCap No Int Null Any number The number of times an item can be recommended to a profile before being hidden from future recommendations.
Querystring imageWidth No Int Null Any number Width of the images to return.
Querystring imageHeight No Int Null Any number Height of the images to return.
Querystring manualViewCounting No Boolean false true, false Prevent updating recommendation statistics for the recommended items. Can be used to generate offline recommendation items without influencing the profile.

The body of a recommendations request consists of a JSON array that holds one or more sets of recommendation definition objects. Each recommendation definition object contains a combination of algorithms and filters and a number of items that should be returned. This allows you to return items based on different mixes of algorithms. You can also define a default to fall back to when not enough matching recommendations can be found.

Name Required Data Type Default Value(s) Description
id Yes String null “first”, “second” or “default” The order of execution of the definition objects: “first” will be executed first, “second” will be executed next. If the total count has not been reached, the remainder items will be from the “default” definition.
boosts Yes Object[] [] [{"value": "1.5", "algorithm": "RECENCY"}] The algorithms that will be executed to determine the recommendations with their boost value and parameters.

value: Boost value can be a whole or half number: 1, 1.5, 2, 2.5, …, 9.5, 10.

algorithm: Available boosting algorithms:

  • COLLABORATIVE_FILTERING
  • INTEREST
  • LOOK_ALIKE
  • RECENCY
  • RECENT_CTR
  • RECENT_ENTRYPAGE
  • RECENT_VIEW
  • RECENTLY_BOUGHT
  • RECENTLY_SHOPPINGCART
  • RECENTLY_VIEWED
  • SAME_CATEGORY

rampUp:  Ramp up value for algorithms that use it:

  • INSTANT
  • VERY_SLOW
  • SLOW
  • NORMAL
  • FAST
count No Int null Any number The maximum number of items that should be returned for this definition.
filters No String[] [] ["category:news", "viewed"] Item filters, see below.

The following boosting algorithms are supported:

Name Description Example
Breaking news Items most viewed by all visitors in the time frame defined in the collector. "boosts": [{"value": 1, "algorithm": "RECENT_VIEW"}]
Viral news Items most used as a landing page by all visitors in the time frame defined in the collector. "boosts": [{"value": 1, "algorithm": "RECENT_ENTRYPAGE"}]
Recency Items most recently added items based on the publication date property. "boosts": [{"value": 1, "algorithm": "RECENCY"}]
Recent high CTRs Items most clicked-through from BlueConic recommendations by all visitors in the time frame defined in the collector. "boosts": [{"value": 1, "algorithm": "RECENT_CTR"}]
Recently bought items Items recently bought by the provided profileId. "boosts": [{"value": 1, "algorithm": "RECENTLY_BOUGHT"}]
Recently carted items Items recently put in the shopping cart by the provided profileId. "boosts": [{"value": 1, "algorithm": "RECENTLY_SHOPPINGCART"}]
Same category Items of the same category as the item with the provided itemId. "boosts": [{"value": 1, "algorithm": "SAME_CATEGORY" }]
Look-alike-articles Items that have similar content to the item with the provided itemId. "boosts": [{"value": 1, "algorithm": " LOOK_ALIKE" }]
Seen articles Items the provided profileId recently viewed. "boosts": [{"value": 1, "algorithm": " RECENTLY_VIEWED" }]
Same interest Items that look similar to the items already viewed by the provided profileId. "boosts": [{"value": 1, "algorithm": "INTEREST", "rampUp": "FAST"}]
Collaborative filtering Items popular with other profiles who viewed the same items as the provided profileId. "boosts": [{"value": 1, "algorithm": "COLLABORATIVE_FILTERING", "rampUp": "FAST"}]

Recommendation definition objects may contain filters that restrict the items that may be returned:

Example Description
"filters": ["VIEWED"] Exclude the items already viewed by the provided profileId.
"filters": ["SHOPPINGCART"] Exclude the items in the shopping of the provided profileId.
"filters": ["BOUGHT"] Exclude the items already bought by the provided profileId.
"filters": ["VIEWED_ONLY"] Include only items that were viewed by the provided profileId.
"filters": ["SHOPPINGCART_ONLY"] Include only items that were in the shoppingcart of the provided profileId.
"filters": ["BOUGHT_ONLY"] Include only items that were bought by the provided profileId.
"filters": ["SAME_CATEGORY"] Include only items that have the same category as the provided itemId.
"filters": ["IN_STOCK"] Include only items that are in stock.
"filters": ["publicationDate>2018-06-01T00:00+02:00"] Include only items with a publication date after June 1st 2018. The format of publicationDate is “2018-01-01T00:00Z” or with a timezone offset
“2018-01-01T00:00+05:00”
"filters": ["publicationDate<=2018-06-01T00:00+02:00"] Include only items with a publication date before June 1st 2018. The format of publicationDate is “2018-01-01T00:00Z” or with a timezone offset
“2018-01-01T00:00+05:00”
"filters": ["category:politics"] Include only items that have a specific value for a specific property, e.g. “politics” for property “category”.
"filters": ["!category:politics"] Exclude items that do not have a specific value, e.g. “politics” for property “category”.
"filters": ["category:politics","category:sports"] Include only items that have all specific values, e.g. “politics” and “sports” for property “category”.
"filters": ["category:politics,sports"] Include only items that have any of the specified values, e.g. “politics” or “sports” for property “category”.
"filters": ["!category:politics","!category:sports"] Include only items that do not have any of the specified values, e.g. “politics” or “sports” for property “category”.
"filters": ["!category:politics,sports"] Include only items that do not have all of the specified values, e.g. “politics” and “sports” for property “category”.
"filters": ["hasproperty:image"] Include only items that have an image.
Authentication Yes
Responses
  • 200 – Returns recommendations.
  • 400 – The specified body is not valid.
  • 503 – The server is too busy to handle the request.
Example

Request

POST https://yourserver.blueconic.net/rest/recommendations?profileId=5a68374b-2311-aad2-1ba2-f32f7ccd1131&storeId=b6827f3-a3c1-2112-f522-aa2ccd113124&itemId=http%3A%2F%2Fwww.example.com%2Fnews%2Fkitten-saved-from-tree&imageWidth=150&imageHeight=150&manualViewCounting=true

JSON body

[
  {
    "id": "first",
    "boosts": [
      {"value": "1", "algorithm": "RECENCY"},
      {"value": "2", "algorithm": "COLLABORATIVE_FILTERING", "rampUp": "FAST"},
      {"value": "1", "algorithm": "RECENT_VIEW"},
      {"value": "1", "algorithm": "RECENT_CTR"}
    ],
    "filters":   [
      "category:politics",
      "viewed"
    ],
    "count": 3
  },
  {
    "id": "second",
    "boosts": [
      {"value": "2","algorithm": " COLLABORATIVE_FILTERING ", "rampup": "SLOW"},
      {"value": "1","algorithm": " RECENT_CTR"}
    ],
    "filters": [
      "category:politics",
      "!category:economie",
      "VIEWED"
    ],
    "count": 3
  },
  {
    "id": "default",
    "filters": [
      "publicationDate>2018-06-17T14:30+0200",
      "!category:economie",
      "VIEWED"
    ],
    "boosts": [
      {"value": "1","algorithm": "RECENT_CTR"}
    ]
  }
]

 

Response

{
  "recommendationBlock":
  [
    {
      "id": "first",
      "recommendations": [
        {
          "score": 0.12063565363854145,
          "trackingUrl": "http://taylor-news.com/1"
          "id": "www.taylor-news.com/news/1111",
          "url": "https://www.taylor-news.com/news/1111",
          "name": "Name 1",
          "description": "Description 1.",
          "category": ["sport", "baseball"],
          "image": "https://img.taylor-news.com/img1.jpg",
          "customProperties": {
            "pubdate": ["tuesday 12 juni 2018, 09:45"],
            "story": []
          }
        },
        {
          "score": 0.001113261296046081,
          "trackingUrl": "http://taylor-news.com/2"
          "id": "www.taylor-news.com/news/2222",
          "url": "https://www.taylor-news.com/news/2222",
          "name": "Name 2",
          "description": "Description 2.",
          "category": ["news", "politics"],
          "image": "https://img.taylor-news.com/img2.jpg",
          "customProperties": {
            "pubdate": ["wednesday 13 juni 2018, 09:45"],
            "story": []
          }
        }
      ]
    },
    {
      "id": "second",
      "recommendations": [
        {
          "score": 1.0,
          "trackingUrl": "http://taylor-news.com/3"
          "id": "www.taylor-news.com/news/3333",
          "url": "https://www.taylor-news.com/news/2317578",
          "name": "Name 3",
          "description": "Description 3.",
          "category": ["sport", "basketball"],
          "image": "https://img.taylor-news.com/img3.jpg",
          "customProperties": {
            "pubdate": ["tuesday 12 juni 2018, 09:45"],
            "story": []
          }
        },
        {
          "score": 1.0,
          "trackingUrl": "http://taylor-news.com/4"
          "id": "www.taylor-news.com/news/4444",
          "url": "https://www.taylor-news.com/news/2317578",
          "name": "Name 4",
          "description": "Description 4.",
          "category": [],
          "image": "https://img.taylor-news.com/img4.jpg",
          "customProperties": {
            "pubdate": ["tuesday 12 juni 2018, 09:45"],
            "story": []
          }
        }
      ]
    }
  ],
  "recommendationId": "97258279-baf7-45de-aab3-457dc42904be",
  "trackingPixel": "http://track.com"
}

REST API example

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

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

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

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

For example:

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

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

Retrieve the visitor profile

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

GET https://yourserver.blueconic.net/rest/profiles/99db747f-2061-43d3-a508-76a977a18ba4

Returns:

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

Retrieve the BlueConic profile ID(s) with the matching email address

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

GET https://yourserver.blueconic.net/rest/profiles?alt=xml&property=email&value=jsmith@blueconic.com

Returns:

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

Retrieve the profile that matches the property

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

GET https://yourserver.blueconic.net/rest/profile/1af1a5ac-0fbb-40eb-91ff-f9909b3fb2d6

Returns:

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

Merge profiles

Now that know that the two profiles belong to the same visitor, we can merge the profiles. To do so, the values from one profile are added to the other in a merge operation. In addition to merging the values, you must also indicate which profile is the 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 https://yourserver.blueconic.net/rest/profiles/ method, you can individually write all the desired properties present in "Profile B" to "Profile A" using name/value pairs.

The result:

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

Replace "Profile B" with "Profile A"

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

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

Returns:

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