NAV
Code Examples

Introduction

While LiveIntent provides a reporting interface within its application, many clients use an in-house or third party data management platform to centralize reporting and analytics across the many other ad tech services they use. With LiveIntent’s reporting API, clients can access their LiveIntent data in an automated fashion in order to more easily export it to their tool of choice.

Overview

LiveIntent’s reporting API allows users to receive specific data on demand to better understand their performance on LiveIntent’s platform. When calling the API, only a few key pieces of information must be specified:

  1. id, seed, hash – Authentication information so only data relevant to you is returned.
  2. type – Whether you want data in terms of how your inventory is performing or how your advertisers are performing.
  3. splits – How you want to break out your data into records or rows.
    • For example, you can separate out the data by inventory like publisher ID, template ID, or ad slot ID.
    • You can also break out the data by advertiser ID, insertion order ID, campaign ID, strategy ID, and creative ID for your direct sold advertisers.
    • Additionally, you can split the data by demographic information like the age or gender of users viewing ads or by the date or time that ads were viewed.
  4. columns – The information you want to see for each record or row. • You can choose to view metrics like impressions, clicks, and conversions as well as attributes. For example, if you chose publisher ID for splits, you can view attributes like publisher name and publisher domain.
  5. startDate, endDate – The date range for which you want to pull the information.

The API described in this document powers the reporting interface in the LiveIntent application. While some of the capabilities in the UI are not available via direct access to the API and vice versa, the reporting interface remains a useful introduction to the API.

Guidelines

Authentication

Authentication for LiveIntent’s reporting API is token-based. As part of onboarding to the API, LiveIntent will assign a user ID and a private token, which must be used to populate specific parameters in every request.

See section 5.5 for required parameters.

Request Limits

Usage of the API is limited to 1 request per second for each user.

Request Information

Endpoint

The endpoint for the reporting API is https://api.liveintent.com/api.

Requests must be made using the POST method and HTTPS protocol.

Headers

Header Description Value
Content-Type Identifies the request format to ensure the query is parsed correctly. If not specified, the API will try to autodetect the format. One of the following: 1. application/json 2. text/xml 3. application/xml
Accept Specifies the response format.If not specified, the response will be returned in the same format as the request. One of the following: application/json, application/xml, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/html

Request Format

Requests can be formatted as JSON or XML. Request parameters include scalars (single value such as an integer or string), objects (comma-separated list of key-value pairs), and arrays of scalars or objects.

JSON Format

    {
"scalar": "value",
"object": {
"key1": "value1",
"key2": "value2"
},
"array":
[
"element1",
"element2"
],
}

XML Format

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <scalar>value</scalar>
  <object>
    <key1>value1</key1>
    <key2>value2</key2>
  </object>
<array>element1</array>
  <array>element2</array>
</data>

Request Body

Parameter Required Data Type Description
id required string User ID provided by LiveIntent when onboarding to the API.
seed required integer UNIX timestamp. Must be unique for every request and be within 5 minutes of the time the request is actually sent.
hash required string SHA1 hash of the concatenation of the private token (provided by LiveIntent when onboarding to the API) and seed in that order.
function optional string Indicates the operation to perform. At this time, only “data” is allowed. If not specified, the default value is “data”.
type required string Specifies the overall scope of the data. Use “publisher” when you want to know how your inventory is performing or what’s running on your inventory. The data returned will be oriented around your inventory. Use “advertiser” when you want to see how advertisers associated with your media group are performing. The data returned will be oriented around your advertisers.
startDate required string The start date of the date range for which data is requested. The value for startDate cannot be today’s date or later, and the difference between the startDate and endDate cannot be more than one year.,Can be specified in the following ways:,·,A specific date formatted as “YYYY-MM-DD”,·,A specific or relative date using any format described in http://php.net/manual/en/datetime.formats.php,A relative date matching the pattern “[first
endDate required string The end date of the date range for which data is requested. The value for endDate cannot be todayŐs date or later, and the difference between the startDate and endDate cannot be more than one year.
splits required array of strings Determines how the data is grouped into records. At this time, the maximum supported array size is one. See section 5.4.1 for allowed elements.
columns required array of strings Specifies which attributes and metrics to return for each record. Columns are returned in the same order in which they are requested. See section 5.4.2 for allowed elements.
filters optional array of objects Applies additional restrictions to the data so that only certain rows and data that meet the filter criteria are returned. See section 5.4.3 for more details.
sort optional object Determines the order in which records are returned. If not specified, records will be returned in descending order for numeric values (except IDs, age, zip, date, and time values) and ascending order otherwise based on the values for the splits parameter. See section 5.4.4 for more details.
format optional object Specifies whether to include column names and totals. If not specified, column names are returned as the first record and column totals are returned as the last record for Excel and HTML response formats; they are not returned for all other cases. See section 5.4.5 for more details.

Splits

Using the splits parameter, you can specify how to group the data into records. The value you specify for the type parameter dictates which elements can be used for the splits parameter. The API will return an error if the split requested is unsupported for the specified type.

Note that depending on the split you use, the metric data returned may be inexact. Because of the large amount of data that has to be processed, the data for certain splits is compressed, resulting in a margin of error in the reported data.

Splits Element Supported Type Exact Data
publisher_id · publisher exact
· advertiser
publisher_domain · publisher exact
· advertiser
template_id · publisher exact
· advertiser
ad_slot_id · publisher exact
· advertiser
placement_id publisher inexact
list_id publisher inexact
segmented_keys publisher inexact
segmented_values publisher inexact
advertiser_id · publisher exact
· advertiser
advertiser_domain · publisher inexact
· advertiser
insertion_order_id · publisher exact
· advertiser
campaign_id · publisher exact
· advertiser
campaign_type · publisher exact
· advertiser
demand_type · publisher exact
· advertiser
strategy_id · publisher exact
· advertiser
creative_id · publisher exact
· advertiser
size · publisher exact
· advertiser
year · publisher exact
· advertiser
month · publisher exact
· advertiser
year_month · publisher exact
· advertiser
day · publisher exact
· advertiser
day_hour · publisher inexact
· advertiser
hour · publisher inexact
· advertiser
age · publisher inexact
· advertiser
gender · publisher inexact
· advertiser
country · publisher inexact
· advertiser
region · publisher inexact
· advertiser
metro · publisher inexact
· advertiser
zip · publisher inexact
· advertiser
device_maker · publisher inexact
· advertiser
device_model · publisher inexact
· advertiser
device_type · publisher inexact
· advertiser
os · publisher inexact
· advertiser
browser · publisher inexact
· advertiser
email_domain · publisher inexact

Columns

The columns parameter specifies which metrics and attributes to return for each record.

The metrics allowed is dependent on the type parameter. If the column requested is unsupported for the specified type, the column will not be returned in the response.

Attributes correspond to the element chosen for the splits parameter. If the specified column is unrelated to the split, “null” will be returned for the column value.

Column Type Column Element Supported Type Supported Splits
metric impressions · publisher -
· advertiser
unique_impressions · publisher -
· advertiser
reopens · publisher -
· advertiser
clicks · publisher -
· advertiser
conversions · publisher -
· advertiser
post_view_conversions · publisher -
· advertiser
revenue publisher -
net_cpm publisher -
net_cpc publisher -
net_cpa publisher -
spend advertiser -
gross_cpm advertiser -
gross_cpc advertiser -
gross_cpa advertiser -
ctr · publisher -
· advertiser
ccr · publisher -
· advertiser
attribute publisher_id - · publisher_id
· publisher_domain
· template_id
· ad_slot_id
publisher_name - · publisher_id
· publisher_domain
· template_id
· ad_slot_id
publisher_domain - · publisher_id
· publisher_domain
· template_id
· ad_slot_id
template_id - · template_id
· ad_slot_id
template_name - · template_id
· ad_slot_id
ad_slot_name - ad_slot_id
advertiser_id - · advertiser_id
· insertion_order_id
· campaign_id
· strategy_id
advertiser_name - · advertiser_id
· insertion_order_id
· campaign_id
· strategy_id
advertiser_domain - · advertiser_id
· insertion_order_id
· campaign_id
· strategy_id
insertion_order_id - · insertion_order_id
· campaign_id
· strategy_id
insertion_order_name - · insertion_order_id
· campaign_id
· strategy_id
campaign_id - · campaign_id
· strategy_id
campaign_name - · campaign_id
· strategy_id
campaign_type - · campaign_id
· strategy_id
demand_type - · campaign_id
· strategy_id
strategy_name - strategy_id
creative_name - creative_id

Filters

The filters parameter allows you to apply additional restrictions to the data so that only certain rows and data that meet the filter criteria are returned.

Each criterion is a separate object comprised of the below parameters. If multiple filters are included, “AND” Boolean logic is applied, meaning that only data that meets all filter criteria will be returned.

Parameter Required Data Type Description
dimension required string One of the allowed elements for the splits parameter.
Note that any split can be chosen for the filter regardless of the type parameter.
operator required string Specifies the relationship between the dimension and values.
At this time only “equals” and “not equals” are supported.
values required array An array of values corresponding to the specified dimension.

Sort

The sort parameter determines the order in which records are returned.

Each sorting rule is a key-value pair in the sort object. Multiple sorting rules can be specified as a comma-separated list of key-value pairs in the sort object, in which case the sorting rules are applied in the order specified in the object.

Parameter Required Data Type Description
Can be any of the elements included in the request’s splits or columns parameter. required string Determines how to order the values of the sort key.
Allowed values are “asc” for ascending order and “desc” for descending order.
If unspecified, “desc” will be used for numeric values (except IDs, age, zip, date, and time values); other “asc” will be used.

Format

The format parameter specifies whether and where to include column names and totals.

The format is an object with the below parameters. At least one parameter must be specified when using the format object.

Parameter Required Data Type Description
columnNames optional string Determines whether to include column names as a record.
Allowed values are “top” to return them as the first record or “off” to not include them.
If not specified, the default value is “top” for Excel and HTML response formats and “off” for all other cases.
columnTotals optional string Determines whether to include column totals as a record.
Allowed values are “top” to return them as the first record, “bottom” to return them as the last record, or “off” to not include them.
If not specified, the default value is “bottom” for Excel and HTML response formats and “off” for all other cases.

Code Examples

JSON

{  
   "id":"12345",
   "seed":1403751336,
   "hash":"abcdefghijklmnopqrstuvwxyz0123456789",
   "function":"data",
   "type":"publisher",
   "startDate":"2015-01-01",
   "endDate":"2015-02-01",
   "splits":[  
      "publisher_id"
   ],
   "columns":[  
      "impressions",
      "clicks",
      "conversions",
      "revenue"
   ],
   "filters":[  
      {  
         "dimension":"country",
         "operator":"equals",
         "values":[  
            "US"
         ]
      }
   ],
   "sort":{  
      "impressions":"desc",
      "publisher_id":"asc"
   },
   "format":{  
      "columnNames":"top",
      "columnTotals":"bottom"
   }
}

XML

<?xml version="1.0" encoding="UTF-8"?> 
<data>     
<id>b50d36460dd211e4930c12313d1fcdce</id>     
<seed>1426485574</seed>     <hash>983f9c6c4aef3e4b7ae307f24ab778c24b48524e</hash>     
<function>data</function>     
<type>publisher</type>     
<startDate>2015-01-01</startDate>     
<endDate>2015-02-01</endDate>     
<splits>publisher_id</splits>     
<columns>impressions</columns>     
<columns>clicks</columns>     
<columns>conversions</columns>     
<columns>revenue</columns>     
<filters>           
<dimension>country</dimension>           
<operator>equals</operator>           
<values>US</values>     
</filters>     
<sort>           
<impressions>desc</impressions>           
<publisher_id>asc</publisher_id>     
</sort>     
<format>           
<columnNames>top</columnNames>           
<columnTotals>bottom</columnTotals>     
</format> 
</data>

Response Information

Response Format

Data can be returned as JSON, XML, HTML, or an Excel spreadsheet. You can specify the response format you would like returned in the request header (see section 5.3).

Response Body

The reponse body only includes requested fields as specified in the splits and columns parameters.

The below table summarizes all possible response fields.

Field Data Type Description
publisher_id string Unique identifier assigned to each publisher by LiveIntent.
publisher_name string Name assigned to each publisher.
publisher_domain string The publisher’s primary domain.
template_id string Unique identifier assigned to each template by LiveIntent.
template_name string Name assigned to each template.
ad_slot_id string Unique identifier assigned to each ad slot by LiveIntent.
ad_slot_name string Name assiged to each ad slot.
placement_id string Identifier assigned to each email drop and passed in each LiveTag.
Note that data returned for placement IDs is inexact.
list_id string Optional identifier assigned to each mailing list and passed in LiveTags.
Note that data returned for list IDs is inexact.
segmented_keys string Optional key used for key-value targeting and passed in LiveTags.
Note that data returned for custom keys is inexact.
segmented_values string Values passed in LiveTags that correspond to the keys used for key-value targeting.
Note that data returned for custom values is inexact.
advertiser_id string Unique identifier assigned to each advertiser by LiveIntent.
advertiser_name string Name assigned to each advertiser.
advertiser_domain string The advertiser’s primary domain.
Note that data returned for advertiser domains is inexact.
insertion_order_id string Unique identifier assigned to each insertion order by LiveIntent.
insertion_order_name string Name assigned to each insertion order.
campaign_id string Unique identifier assigned to each campaign by LiveIntent.
campaign_name string Name assigned to each campaign.
campaign_type string The type of campaign; limited one of the following values:
· newsletter
· roadblock
· takeover
· dedicated
· display
demand_type string The demand source; limited to one of the following values:
· direct
· house
· exchange
· fallback_ads
strategy_id string Unique identifier assigned to each strategy by LiveIntent.
strategy_name string Name assigned to each strategy.
creative_id string Unique identifier assigned to each creative by LiveIntent.
creative_name string Name assigned to each creative.
size string Sizes of ads that are viewed in the format “wxh”
year integer Year that ads are viewed in the format “YYYY”
month integer Month that ads are viewed in the format “MM”
year_month date The year and month that ads are viewed in the format “YYYY MM”
day date The date that ads are viewed in the format “YYYY-MM-DD”
day_hour datetime The date and time that ads are viewed in the format “YYYY-MM-DD HH”
Note that data returned for day and hour is inexact.
hour time The hour that ads are viewed from 0 through 24.
Note that data returned for hours is inexact.
age string Age group to which the user viewing ads belongs; limited to one of the following values:
· 18-20
· 21-24
· 25-34
· 35-44
· 45-54
· 55-64
· 65+
Note that data returned for ages is inexact.
gender string Perceived gender of the user viewing the ads; limited to one of the following values:
· male
· female
Note that data returned for genders is inexact.
country string Country in which the ads are viewed.
Note that data returned for countries is inexact.
region string Regional area such as state or province in which the ads are viewed.
Note that data returned for regions is inexact.
metro string Designated Market Area (DMA) in which the ads are viewed; only DMA codes are returned.
Note that data returned for metros is inexact.
zip string Zip code in which the ads are viewed.
Note that data returned for zip codes is inexact.
device_maker string Brand of device used to view ads.
Note that data returned for device brands is inexact.
device_model string Specific model of phone or tablet used to view ads.
Note that data returned for device models is inexact.
device_type string The type of device used to view ads; limited to one of the following values:
· PC
· Phone
· Tablet
· GoogleProxy (using the Gmail web client)
· Windows Media Center
Note that data returned for device types is inexact.
os string Operating system on which ads are viewed.
Note that data returned for operating systems is inexact.
browser string Browser or email client used to view ads.
Note that data returned for browsers is inexact.
email_domain string Email domain of the recipient viewing ads.
Note that data returned for email domains is inexact.
impressions integer Total ad impressions and views (sum of unique impressions and shares and reopens).
unique_impressions integer Number of times an ad is viewed for the first time (does not include re-opens and shares).
reopens integer Number of subsequent ad views after an email has been opened the first time (includes shares and email forwards).
clicks integer Number of clicks an ad received.
conversions integer Number of conversions logged after an ad is clicked.
post_view_conversions integer Number of conversions logged after is viewed, but not clicked.
revenue decimal Total net revenue.
net_cpm decimal Net cost per thousand impressions.
net_cpc decimal Net cost per click.
net_cpa decimal Net cost per acquisition.
spend decimal Total spend of an ad campaign.
gross_cpm decimal Gross cost per thousand impressions.
gross_cpc decimal Gross cost per click.
gross_cpa decimal Gross cost per acquisition.
ctr decimal Clickthrough rate, i.e. percentage of impressions that received clicks.
ccr decimal Click-to-conversion ratio, i.e. percentage of clicks that converted.

Code Example

JSON

[  
   {  
      "publisher_id":"publisher_id",
      "impressions":"impressions",
      "clicks":"clicks",
      "conversions":"conversions",
      "revenue":"revenue"
   },
   {  
      "publisher_id":"2",
      "impressions":24715,
      "clicks":20,
      "conversions":1,
      "revenue":33.130296
   },
   {  
      "publisher_id":"1",
      "impressions":16800,
      "clicks":131,
      "conversions":0,
      "revenue":122.823748
   },
   {  
      "publisher_id":"(totals)",
      "impressions":41515,
      "clicks":151,
      "conversions":1,
      "revenue":155.954044
   }
]

XML

<?xml version="1.0" encoding="UTF-8"?> 
<root>    
<publisher_id>publisher_id</publisher_id>       
<impressions>impressions</impressions>     
<clicks>clicks</clicks>     
<conversions>conversions</conversions>    
 <revenue>revenue</revenue>    
<publisher_id>2</publisher_id>     
<impressions>24715</impressions>     
<clicks>20</clicks>     
<conversions>1</conversions>     
<revenue>33.130296</revenue>    
<publisher_id>1</publisher_id>    
<impressions>16800</impressions>     
<clicks>131</clicks>     
<conversions>0</conversions>      
<revenue>122.823748</revenue>    
<publisher_id>(totals)</publisher_id>     
<impressions>41515</impressions>     
<clicks>151</clicks>     
<conversions>1</conversions>    
  <revenue>155.954044</revenue> 
</root>

Response Codes

Code HTTP Status Description
10, 11 401 Authentication failed
20 401 Authentication failed – invalid seed
21 401 Seed too low
22 401 Seed timestamp failed – seed not within 5 minutes of UNIX timestamp
30 401 Authentication failed – token not found
31 401 Authentication failed – invalid hash
40-44, 900 403 Permission denied
51 429 Query limit exceeded
52 401 Authentication failed – invalid id
53, 102-109, 701-702, 1002-1004, 1006 500 Internal error
(except for 701-702)
200 - OK – request succeeded
201 - No data returned
300 - Dimensions removed
901 403 Required parameter missing
902 403 Incorrect type
903 403 Invalid input
1000 400 Invalid content-type
1001 404 Invalid function
1005 403 Invalid dimension