Description: This document lists and describes the API calls used to obtain uplift metric data (Enterprise customers only) for the measurement and optimization of TV campaigns.
The Innovid API requires you to authenticate with InnovidXP so that you can access your client and brand data. You will need to set up and use basic authentication to access the available Innovid Attribution API endpoints. This requires a Basic HTTP Authorization header to be sent with each request.
For more information on the HTTP Authorization header, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization.
Making calls to the API
The API uses basic authentication over an https connection. To authenticate, you must send an HTTP Authorization header with every API call, containing a hash of the username and password specified previously for use with the Attribution API.
- To authenticate with the Attribution API using the curl command, use the following command line, substituting the username and password of the API user:
curl --user <api_username>:<api_password> https://apixx.tvsquared.com
- Alternatively, you can use a separate 3rd-party command line tool, or your preferred programming language, to generate the authentication header.
The base URL is appended with uplift so that the base URL for the uplift endpoint becomes:
All URLs in this section start with this base URL.
The Innovid Uplift Metric API is a standard RESTful HTTP API based on GET, POST, and DELETE requests with JSON formatted responses.
The API exclusively uses the HTTPS protocol for encryption and data security - plain HTTP requests are blocked and will not be successful.
All API endpoints share the same base URL, accessed at the partner level:
where <partnerdomain> is a unique identifier for the API in the format api-xx. Use your <partnerdomain> for the base URL for all API endpoints.
Performing a GET request at the following endpoint returns uplift metric information for the specified client, action, medium, date from, and date to.
The <y1>, and <y2> parameters represent the start and end dates of the date range you want to view uplift metrics for.
All date and time parameters are formatted in the ISO standard as follows unless otherwise stated:
- Date: YYYY-MM-DD
- Datetime: YYYY-MM-DDThh:mm:ss
Client ID and brand ID are used in several API endpoints, identified by <clientid> and <brandid>, respectively.
These are unique identifiers for the required client and brand and can be derived from the InnovidXP portal.
|A list of the media types, for example, web, app, phone, sms.
|A list of available response actions, for example, all response, signup, subscription.
Example response format
The API will return these uplift values:
|The date range requested in the API call.
|The date range before the selectedperiod, calculated from the dateto minus the number of days in the date range from selectedperiod.
|The percentage difference in uplift between the selectedperiod and the previousperiod.
|The value as a percentage.