Salesforce DMP API

1.  Introduction

The Salesforce Data Management Platform (DMP) allows publishers and marketers to collect and organize all of their consumer web data in one central "big-data" warehouse. Using Salesforce DMP, organizations can consolidate and reconcile their first party "web-behavior" data that is generated by consumers as they engage with media and/or content with data from various third party data providers. Organizations can also integrate data from their user registration and subscription databases into Salesforce DMP and join that data with web behavior and third party data.

The Salesforce DMP “Konsole” web application is the primary medium through which users interact with Salesforce DMP. Users can view reports and insights, build audience segments, manage events, and perform administrative actions through the Konsole. In addition to the Konsole web application, developers can use the Salesforce DMP API to access certain components of Salesforce DMP.

This document describes the functionality supported by the Salesforce DMP API. Salesforce DMP provides a RESTful API to access and manage the following components: 

  • Sites
  • Audience Segments
  • Audience Segment Distributions
  • Events
  • Event Summary
  • Event Demographics

The rest of the document is organized as follows: section 2 provides details on the Authentication and Authorization components of the API, and sections 3, 4, and 5 describe the Site, Audience Segments, and Event APIs respectively.

All examples presented in the document use the “curl” command line tool (http://curl.haxx.se/). Note that for all statements including <username>:<password>, and <API KEY VALUE> you will need to replace with your Konsole or API username and password or API Key respectively.

2.  Authentication and Authorization

The Salesforce DMP API uses HTTP Basic Authentication and an API Key for user authentication and authorization. A typical organization account in Salesforce DMP has many users and each user is assigned a unique username/password combination that they use to access the Data Console web application. The same username/password credentials can be used to access the Salesforce DMP API as well. In addition to the Konsole username and password, a unique API Key is assigned to each organization in Salesforce DMP. Your Salesforce DMP Solutions Representative will provide you with access to this API Key.

Developers in an organization may use the credentials of any Konsole user account in that organization for HTTP Basic Authentication. The API respects all access permissions that are in effect for corresponding user in the Konsole web application. Salesforce DMP recommends that administrators should create a dedicated Konsole user account for API access with the appropriate access permissions in order to consolidate all the API access information in one central place.

We now provide some sample API calls to illustrate the authentication and authorization components of the Salesforce DMP API. The examples listed below use the Site API. The Site API is described in detail in Section 3 below.

curl --user <userid>:<passwd> --dump-header - -H "Content-Type: application/json" https://console.krux.com/api/v1/sites/?api_key=<API KEY VALUE>

The Data Console server returns the following HTTP headers:

HTTP/1.1 200 OK
Cache-Control: no-cache
Cache-Control: max-age=0
Content-Type: application/json
Date: Thu, 19 May 2016 18:43:28 GMT
Expires: Thu, 19 May 2016 18:43:28 GMT
Server: Apache
Set-Cookie: ServedBy=console-b003; path=/; domain=.krxd.net; expires=Wed, 16-Nov-2016 08:03:28 GMT
Vary: Accept,Cookie,Accept-Encoding
X-Frame-Options: deny
X-Request-Time: D=133172 t=1463683408038104
X-Served-By: console-b003.krxd.net
X-UA-Compatible: IE=Edge,chrome=1
X-XSS-Protection: 1; mode=block
transfer-encoding: chunked
Connection: keep-alive 

The Site API responds with a list of all the Sites that the user is allowed to access (this is described in detail in Section 3): 

[
{"id": 698453, "name": "site Name 1"},
{"id": 339188, "name": "example2.com"},
{"id": 339189, "name": "Off Site Marketing"}]

An invalid username/password combination will result in an HTTP 401 response as shown below:

curl --user : --dump-header - -H "Content-Type: application/json" https://console.krux.com/api/v1/sites/?api_key=<API KEY VALUE>
HTTP/1.1 401 UNAUTHORIZED
Cache-Control: max-age=0
Content-Type: text/html; charset=utf-8
Date: Thu, 19 May 2016 18:45:36 GMT
Expires: Thu, 19 May 2016 18:45:36 GMT
Server: Apache
Set-Cookie: ServedBy=console-b002; path=/; domain=.krxd.net; expires=Wed, 16-Nov-2016 08:05:36 GMT
Vary: Cookie
WWW-Authenticate: Basic Realm="django-tastypie"
X-Frame-Options: deny
X-Request-Time: D=124585 t=1463683536596638
X-Served-By: console-b002.krxd.net
X-UA-Compatible: IE=Edge,chrome=1
X-XSS-Protection: 1; mode=block
Content-Length: 0
Connection: keep-alive

3.  Sites

Salesforce DMP allows web operators (publishers, marketers, etc.) to organize their online digital (web) content into logical groupings called sites. Each logical grouping corresponds to an actual physical entity in the web operator’s content hierarchy. For example, an online portal may choose to organize its content into the following sites:

  • News
  • Sports
  • Finance
  • Entertainment
  • Lifestyle

On the other hand, an online electronics retailer will probably organize its e-commerce portal using the following sites:

  • TVs and Displays
  • Peripherals
  • Audio
  • Computers

Since Salesforce DMP supports a 3‐level site hierarchy, sites may further be broken

down into sections and sub-sections.

Endpoint:

https://console.krux.com/api/v1/sites/

3.1 Get Sites List

The only operation provided by the Site API is a GET operation to list all the sites under an account. This is accomplished by sending a GET request using the following:

Parameters:

api_key: API key for this client (see section 2 for details)

Example Call:

CLICK TO SCROLL and view entire tag

curl --user <userid>:<passwd> --dump-header - -H "Content-Type: application/json" https://console.krux.com/api/v1/sites/?api_key=<API KEY VALUE>

Example JSON Response:

[
{"id": 698453, "name": "site Name 1"},
{"id": 339188, "name": "example2.com"},
{"id": 339189, "name": "Off Site Marketing"}]

4. Audience Segments

The Audience Segment component of the ADM (Audience Data Management) module of Salesforce DMP provides a powerful and flexible framework for defining audience segments. Audience Segments are managed through the Salesforce DMP Konsole web application. In addition to the functionality available through Konsole, users can also access Audience Segment listings via a REST API. This section describes all the "get" operations supported by the Audience Segment API and provides examples that demonstrate their intended usage.

4.1 Get Audience Segments

List: This API call gets a full list of segments for the organization.

Endpoint:

https://console.krux.com/api/v1/audience/

Params: api_key: API key for this client (see section 2 for details)

Example Call: 

CLICK TO SCROLL and view entire tag

curl --user <userid>:<passwd> --dump-header - -H "Content-Type: application/json" https://console.krux.com/api/v1/audience/?api_key=<API KEY VALUE>

Example JSON Response:

[ {
"category": "",
"description": "",
"id": 180839,
"is_active": false,
"last_compute_time": "2016-04-12T15:44:02",
"name": "exampleClient-Krux Matched Users",
"page_views": 589225,
"population": 246796,
"segment_uuid": "Kbl7IiaU",
"segment_uuid_long": "qjppkadj6",
"sub_category": "",
"type": ""
}, {
"category": "",
"description": "",
"id": 180770,
"is_active": false,
"last_compute_time": "2016-05-18T05:52:21",
"name": "K_1st time Moms",
"page_views": 4699890,
"population": 977303,
"segment_uuid": "KblFB8Oa",
"segment_uuid_long": "qjpaju8ks",
"sub_category": "",
"type": "Krux Standard Segment"
},
]

4.2 Get Audience Distribution

This returns the unique user counts representing the overlap of users in the audience segment who have also generated at least one page view on a given site. The number of rows in this report is less than or equal to the number of sites in the account.

Endpoint:

https://console.krux.com/api/v1/audience/audience_distribution/

Params:

api_key: API key for this client (see section 2 for details)

segment_id: Database id for the event. Returned in the "Get Audience Segments List" call (see Section 4.1 for details)

start_date: YYYY-MM-DD start date

end_date: YYYY-MM-DD start date

Example Call:

CLICK TO SCROLL and view entire tag

curl --user <user>:<password> --dump-header - -H "Content-Type: application/json" "https://console.krux.com/api/v1/audience/audience_distribution/?api_key=<API KEY VALUE>&segment_id=163541&start_date=2010-01-01&end_date=2016-05-01"

Example JSON Response:

{
"objects": [{
"index": 100.0,
"name": "example.com",
"uniques": 13578808
}]
}

5.  Events

The Event framework in Salesforce DMP provides a convenient and flexible way for users to track user actions like clicks and conversions on the websites as well as actions like page views on external sites (where the Salesforce DMP Control Tag is not deployed) to enable features like Retargeting. Users can then build Audience Segments based on just the Event data (e.g., Shopping Cart Abandoners) or by combining with page level first party data (e.g., Shopping Cart Abandoners with at least 5 page views in the last 7 days on any Product Reviews page). In this section we describe all the operations supported by the Event API along with examples that demonstrate the intended usage.

5.1 Get All Events

Gets a list of all events for an organization.

Endpoint:

https://console.krux.com/api/v1/event/

Params:

api_key: API key for this client (see section 2 for details)

Example Call:

CLICK TO SCROLL and view entire tag

 curl --user <user>:<password> --dump-header - -H "Content-Type: application/json" https://console.krux.com/api/v1/event/?api_key=<API KEY VALUE>

Example Response:

[{
"attributes": [{
"display_name": "Test Key 1",
"name": "testKey1"
}],
"created_at": "2016-05-18T21:01:09",
"event_type": {
"code": "pageview",
"name": "Page View"
},
"event_uid": "KiomvQnq",
"is_active": true,
"name": "Test Event 1"
}]

5.2 Get Event Summary

Event summary report provides the total number of users and requests that were reached by the event pixel. If the event has attributes, this call can also provide uniques and requests for each attribute value.

Endpoint:

https://console.krux.com/api/v1/event/summary/

Params:

api_key: API key for this client (see section 2 for details)

event_id: database id for the event

start_date: YYYY-MM-DD start date

end_date: YYYY-MM-DD start date

attribute (optional): name of attribute to get counts on

Example Call No Attribute:

CLICK TO SCROLL and view entire tag

curl --user <user>:<password> --dump-header - -H "Content-Type: application/json" "https://console.krux.com/api/v1/event/summary/?api_key=<API KEY VALUE>&event_id=11986&start_date=2016-01-01&end_date=2016-05-01"

Example Response:


"event_name": "2 second in-view impression",
"objects": [{
"day": "2016-05-16",
"requests": 1434183,
"uniques": 382376
}, {
"day": "2016-05-17",
"requests": 1473687,
"uniques": 354922
}, {
"day": "2016-05-18",
"requests": 1339783,
"uniques": 330717
}]
}

Example Call With Attribute:

CLICK TO SCROLL and view entire tag

curl --user <user>:<password> --dump-header - -H "Content-Type: application/json" "https://console.krux.com/api/v1/event/summary/?api_key=<API KEY VALUE>&event_id=11986&start_date=2016-01-01&end_date=2016-05-01&attribute=test_attribute"

Example Response:

{
"event_name": "Test Event 1",
"objects":[
{
"attribute_name": "test_attribute",
"day": "2016-01-01",
"values":[{"uniques": 8, "value": "Test Value 1" }, {"uniques": 9, "value": "Test Value 2"}]
},
{
"attribute_name": "test_attribute",
"day": "2016-01-02",
"values":[{"uniques": 2, "value": "test value too" }]
}
}]

}

5.3 Get Event Demographics

The Event Attribute Demographics report provides demographic information for the event. Demographic information can be fetched for an event and for all the unique attribute signatures for that event. The Demographic information is not enabled by default; if you would like to be able to access the Demographic data via the API, please contact your Salesforce DMP Services Representative.

Endpoint:

https://console.krux.com/api/v1/event/demographics/

Params:

api_key: API key for this client (see section 2 for details)

event_id: database id for the event

start_date: YYYY-MM-DD start date

end_date: YYYY-MM-DD start date

Example Call:

CLICK TO SCROLL and view entire tag

curl --user <user>:<password> --dump-header - -H "Content-Type: application/json" "https://console.krux.com/api/v1/event/demographics/?api_key=<API KEY VALUE>&event_id=11986&start_date=2016-01-01&end_date=2016-05-01"

Example Response:

{

"objects": {"browsers": [],
"demographics": {"age": [{"name": "18-25",
"value": 0.0},
{"name": "26-35",
"value": 0.0},
{"name": "36-45",
"value": 0.0},
{"name": "46-55",
"value": 0.0},
{"name": "56-65",
"value": 0.0},
{"name": "66+",
"value": 0.0}],
"gender": {"female": 0.0,
"male": 0.0},
"income": [{"name": "0-30k",
"value": 0.0},
{"name": "30k-60k",
"value": 0.0},
{"name": "60k-100k",
"value": 0.0},
{"name": "100k-250k",
"value": 0.0},
{"name": "250k+",
"value": 0.0}]},
"devices": [],
"geo": [],
"top_segments": []}
Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk