Connecting to LiveIntent's Reporting API

September 14, 2023 15:31

What is the LiveIntent Reporting API?

The reporting API provides simple access and easier connections when pulling reports from LiveIntent.

💡 Please Note:

If you're experiencing connection issues, please refresh or change your Authentication Token.
Old field names and metrics are not supported by the new API. Please refer to the Valid Splits, Valid Metrics, and Valid Filter dimensions fields below.
A specific request's volume can impact data finalization. For example, a single previous day's worth of data can take around 48 hours to be finalized.

Why use the Reporting API?

Here’s a snapshot of what you can expect from the LiveIntent Reporting API:

Easier connection: just request an Access Token from the authorization server, then attach the token as an HTTP header when making API requests
Increased ways to pull data with new splits: Dive further into understanding your RTB activity with new splits like ‘Bidder ID’, ‘Bidder Seat’ and ‘Deal ID’, plus track how many ad requests are fulfilled with ‘Fill Rate’
Faster reporting: Summarized, packaged data and reduction in API traffic allows for faster reporting turnaround — from minutes to seconds

Check out set-up instructions below.

Authentication

LiveIntent uses OAuth2 for authentication.

The idea is simple - request an Access Token from the Authorization Server, then attach the obtained Access Token as an HTTP header when making requests to the API.

All requests to the API must include an Authorization HTTP header, with its value containing the retrieved Access Token.

In order to retrieve an Access Token, please submit your Client Credentials – a LiveIntent username + password pair – to the token-endpoint, and in exchange receive an Access Token.
This scheme is only appropriate when a confidential app performs server-to-server communication.

1.1 Prerequisites

Before your app can send requests to the Authorization Server, you must obtain your username and password from your LiveIntent account manager. Without those valid credentials you won't be able to receive Access Tokens from the Authorization server.

💡 Please Note: The LiveIntent username/password must be added to any request made at the Authorization Server, so it can know which 3rd-party is making this request.

1.2 Client Credentials

The Client Credentials scheme involves the client-app sending a LiveIntent username and password in order to obtain an appropriate Access Token.

1.2.1 Request Structure

POST /auth/login/
Host: https://connect.liveintent.com
Content-Type: application/json
Accept: application/json

BODY (raw) – JSON (application/json)
{
          'username': 'LiveIntent username',
          'password': 'LiveIntent password'
}

1.2.2 Example Request and Response

 {
          'username': 'mary.lou@liveintent.com',
          'password': 'P@$$word100'
}

{
          'token': 'abcdefghijklmnopqrstuvwxyz-1234567890.zyxwvutsrqponmlkjihgfedcba',
          'username': 'mary.lou@liveintent.com',
          'userID': 'ajiwg02tkt4jlshxit20et2nkjlx',
          'refreshToken': '03xektjekwlvcjlbhd235266skdjfksj'
}

1.3 Execute Query

With your Access Token, you can now execute valid queries via the LiveIntent Reporting API.

1.3.1 Request Structure

POST /reporting/api/executeQuery
Host: https://connect.liveintent.com

*Please note that executeQuery is case sensitive.

Headers
Authorization: 'Bearer {token}'
Content-Type: application/json

Body (raw)
{
          'type': {String},
          'interval': {Object},
          'granularity': {String},
          'splits': ['String1', 'String2', 'String3'],
          'metrics': ['String1', 'String2', 'String3'],
          'filters': [{
               'dimension': 'StringA',
               'operator': 'OperatorB',
               'values': ['StringC']
          },
{
          'dimension': 'StringX',
          'operator': 'OperatorY',
          'values': ['IntegerZ']
          }]
}

1.3.2 Example Response

{
    'type': 'publisher',
    "interval": {
            'type': 'dynamic',
            'value': 'YTD'
     },
    'granularity': 'all',
    'splits': ['Demand Type', 'Mail Type'],
    'metrics': ['NetECPM', 'First Impressions', 'CTR', 'CCR'],
    'filters': [{
    	'dimension': 'Publisher ID',
    	'operator': 'equals',
    	'values': [10000]
    },
    {
    	'dimension': 'Section ID',
    	'operator': 'equals',
    	'values': [12345, 67890]
    }]
}

[
  {
    'version': 'v1',
    'timestamp': '2017-01-01T00:00:00.000Z',
    'event': {
      'CTR': 0,
      'Impressions': 200000,
      'CCR': 0,
      'Demand Type': 'default',
      'Conversions': 0,
      'First Impressions': 188995,
      'Publisher Revenue': 590.09886199980974197,
      'NetECPM': 2.95049431139847639,
      'Clicks': 0,
      'Mail Type': "marquee"
    }
  },
  {
    'version': 'v1',
    'timestamp': '2017-01-01T00:00:00.000Z',
    'event': {
      'CTR': 0.20833333333333333,
      'Impressions': 12000,
      'CCR': 0,
      'Demand Type': 'default',
      'Conversions': 0,
      'First Impressions': 11580,
      'Publisher Revenue': 111.11303799599409103,
      'NetECPM': 9.25941983373263375,
      'Clicks': 2500,
      'Mail Type': 'newsletter'
    }
  }
]

⚠️ Please Note: Once generated, an Access Token has a 12-hour expiry period. After 12 hours the Access Token is revoked, you will need to request another one, either by submitting a Refresh Token or by initiating a new authentication flow.

💡 Please Note: The Access Token should be attached to any request made at the API. An API call which is missing the Authorization header will result in a 401 Unauthorized error response.

💡 Please Note: If a request to the API contains an invalid or expired Access Token, the request will result in a 401 Unauthorized error response.

Valid Request Entries

Valid Types: 'publisher', 'advertiser'

Valid Granularity Values: 'day', 'week', 'month', 'all'

Valid Absolute Intervals:

{

'type': 'absolute',

'start': '2017-01-10',

'end': '2017-01-20'

}

Note: For 'type':'absolute', 'start' and 'end' must be different dates. You cannot have '2018-03-01' for both 'start' and 'end'.

Valid Dynamic Intervals:

{

'type': 'dynamic',

'value': 'WTD'

}

Valid Value (Meaning)

• 'WTD' (Week to Date),

• 'MTD' (Month to Date),

• 'QTD' (Quarter to Date),

• 'YTD' (Year to Date),

• '1' (Yesterday),

• '7' (Last 7 days),

• '30' (Last 30 days),

• '90' (Last 90 days),

• 'LM' (Last Month)

Valid Splits

Advertiser

Publisher

Exact splits

Advertiser ID
Advertiser Label
Advertiser Name
Budget Type
Campaign Bid Amount
Campaign Budget
Campaign End Date
Campaign ID
Campaign Label
Campaign Name
Campaign Start Date
ClickThrough URL
Creative ID
Creative Label
Creative Name
Creative Size
Creative URL
Demand Type
Device Type
Guaranteed
Intermediate PVC UPA
Line Item Bid Amount
Line Item Budget
Line Item End Date
Line Item ID
Line Item Label
Line Item Name
Line Item Start Date
Pacing
Publisher ID
PVC Delay Bucket
Section ID
Status
Template ID

Exact splits

Advertiser ID
Advertiser Label
Advertiser Name
Budget Type
Bidder Campaign ID
Bidder ID
Bidder Seat
Bidder Type
Blueprint ID
Campaign Bid Amount
Campaign Budget
Campaign End Date
Campaign ID
Campaign Label
Campaign Name
Campaign Start Date
ClickThrough URL
Creative ID
Creative Label
Creative Name
Creative Size
Creative Type
Creative URL
Deal ID
Demand Type
Device Type
Guaranteed
Is NCP
Line Item Bid Amount
Line Item Budget
Line Item End Date
Line Item ID
Line Item Label
Line Item Name
Line Item Start Date
Mail Type
Pacing
Publisher ID
Publisher Label
Publisher Name
Section ID
Section Label
Section Name
Status
Template ID
Template Label
Template Name

Inexact splits (estimated values based on sampled data)

Age
Browser
Country
Gender
Metro (DMA)
OS
Region

Inexact splits (estimated values based on sampled data)

Advertiser Domain
Age
Browser
Country
Device Maker
Email Domain
Gender
ISP
List
Metro
OS
Placement ID
Region

Valid Metrics

Advertiser	Publisher
Advertiser Spent CCR Clicks Conversion Rate Conversions CTR eCPA eCPA (PCC) GrossECPA GrossECPC GrossECPM Impressions Intermediate eCPA Intermediate PCC Intermediate PVC Intermediate ROAS Intermediate UPA PVC For Post-view Conversions ROAS Total Conversions Total Intermediate UPA Total ROAS Total UPA UPA UPA PVC Final	CTR(a) Impressions(a) NetECPM(a) Booked CPM CCR Clicks Conversions CTR Fill Rate First Impressions Impressions NetECPM NoAds Publisher Revenue PVC For Post-view Conversions Reopens UPA

Valid Filters:

{

“dimension”: String,

“operator”: String,

“values”: Array of String/Number

}

Valid operator: [“equals”, “not equals”]

Valid Filter dimensions & values

DSP		SSP
Dimension	Values	Dimension	Values
Demand Type	“default”, “direct”, “house”	Demand Type	“default”, “direct”, “house”
Advertiser ID	numeric value. Ex: 12345	Section ID	numeric value. Ex: 12345
Campaign ID	numeric value. Ex: 12345	Advertiser ID	numeric value. Ex: 12345
Line Item ID	numeric value. Ex: 12345	Creative ID	numeric value. Ex: 12345
Creative ID	numeric value. Ex: 12345	Publisher ID	numeric value. Ex: 12345
Publisher ID	numeric value. Ex: 12345	Template ID	numeric value. Ex: 12345
Age	“”, “18-20”, “21-24”, “25-34”, “35-44”, “45-54”, “55-64”, “65+”	Mail Type	“content”, “dedicated”, “marquee”, “native”, “newsletter”, “skin”
Gender	“”, “male”, “female”	List	List id <String>
Device Type	“”, “PC”, “Phone”, “Tablet”, “GoogleProxy”, “MediaCenter”	Email Domain	Ex: Yahoo.com, gmail.com
Metro	numeric value between 500 - 881	Publisher Name	“XYZ Media”
Advertiser Name	“ABC Apparel”	Template Name	“Monday Newsletter”
Insertion Order Name	“Insertion Order for 2017”	Section Name	“Afternoon Edition Marquee”
Campaign Name	“Winter 2017 Promotion”	Age	“”, “18-20”, “21-24”, “25-34”, “35-44”, “45-54”, “55-64”, “65+”
Line Item Name	“NYC Winter 2017 Promo”	Gender	“”, “male”, “female”
Creative Name	“NYC_Winter 2017 Promo_300x250”	Device Type	“”, “PC”, “Phone”, “Tablet”, “GoogleProxy”, “MediaCenter”
Creative Size	“300x250” “970x250” “728x90” “970x550” “[custom width]x[custom height]”	Device Maker	‘Alcatel’ ‘Acer’ ‘Amazon’ ‘Apple’ ‘Asus’ ‘Beeline’ ‘BlackBerry’ ‘Fly’ ‘Fujitsu’ ‘GoogleProxy’ ‘HTC’ ‘Huawei’ ‘Kyocera’ ‘LG’ ‘Lenovo’ ‘MTS’ ‘Medion’ ‘Meizu’ ‘Motorola’ ‘NEC’ ‘Nokia’ ‘ODYS’ ‘Panasonic’ ‘Pantech’ ‘Phillips’ ‘Prestigio’ ‘Samsung’ ‘Sharp’ ‘Sony’ ‘Wexler’ ‘ZTE’
Browser	“AOL” “Android” “Android_App” “BlackBerry” “BrowserNG” “Chrome” “Dalvik” “Dolfin” “Edge” “Eudora” “Evolution” “Firefox” “GoogleProxy” “GoogleSearchApp” “MSIE” “MSOE” “MacMail” “NetNewsWire” “NintendoBrowser” “Opera” “OperaMini” “OperaMobi” “OtherBrowsers” “Outlook” “Ovi” “Safari” “SamsungBrowser” “Sparrow” “Spotify” “Thunderbird” “UCBrowser” “YandexBrowser” “iOS_App”	Metro	numeric value between 500 - 881
OS	‘Android’ ‘BlackBerry’ ‘BlackBerryTablet’ ‘ChromeOS’ ‘GoogleProxy’ ‘Linux’ ‘OSX’ ‘Symbian’ ‘Windows’ ‘WindowsPhone’ ‘iOS’	Browser	“AOL” “Android” “Android_App” “BlackBerry” “BrowserNG” “Chrome” “Dalvik” “Dolfin” “Edge” “Eudora” “Evolution” “Firefox” “GoogleProxy” “GoogleSearchApp” “MSIE” “MSOE” “MacMail” “NetNewsWire” “NintendoBrowser” “Opera” “OperaMini” “OperaMobi” “OtherBrowsers” “Outlook” “Ovi” “Safari” “SamsungBrowser” “Sparrow” “Spotify” “Thunderbird” “UCBrowser” “YandexBrowser” “iOS_App”
		OS	‘Android’ ‘BlackBerry’ ‘BlackBerryTablet’ ‘ChromeOS’ ‘GoogleProxy’ ‘Linux’ ‘OSX’ ‘Symbian’ ‘Windows’ ‘WindowsPhone’ ‘iOS’
		Bidder ID	numeric value. Ex: 12345
		Bidder Seat	string value. Ex: ‘1234_56’
		Bidder Campaign ID	string value. Ex: 12345
		Deal ID	string value. Ex: ‘ABC_DE’
		Insertion Order Name (or ID)	“Direct Sold Insertion Order for 2017”
		Campaign Name (or ID)	“Winter 2017 Direct Sold”
		Line Item Name (or ID)	“NYC Winter 2017 Direct Sold”