Impact Measurement uses the scale and speed of Lucid’s Marketplace to provide unmatched insight into the effectiveness of digital ad campaigns. The Impact Measurement API provides a simple way to both create a brand lift study and retrieve brand performance metrics for a campaign.

Survey data and lift calculation are refreshed on a daily basis, so please keep that in mind when considering frequency of API calls.

This document will help guide you through how to use Impact Measurement API.

HTTPS

All API calls have to be made over HTTPS. Calls made over plain HTTP will redirect to HTTPS.

Plain JSON

The API runs over HTTP/1.1 and communicates using plain application/json (Except specific raw data export endpoints, but these are detailed in this documentation).

Trailing /

Trailing slash is optional for all API endpoints, feel free to use it or not.

Date/Time format

Date and Datetime are always presented in ISO 8601 format.

Caching

The API doesn't include any additional caching features, besides what is implied by the protocol layer.

Rate limiting

We want to encourage innovation with minimal limits. We ask that you please be practical and considerate when determining call frequencies. We rate limit when needed to protect the system and ensure the highest level of service to all of our clients.

Some endpoints, like /api/impact-measurement/v1/campaigns/, employ pagination with the use of the page_size and page parameters. Each paginated endpoint response has these fields:

• page - current page number
• page_size - number of items included in the current page
• total_items - total number of items

We recommend you always explicitly set the page_size parameter to ensure you know how many results, per page, you'll get. If you omit page_size, the page will contain 10 items, at most.

Setting the page_size parameter

Let’s say you need to request all your campaigns, but only want 5 results at a time. Your GET would look something like this:

$ curl -H 'Authorization: Bearer ' -X GET 'https://audience.lucidhq.com/api/impact-measurement/v1/campaigns/?page_size=5'

Note the page_size parameter in this call is set to 5, so the response shows items 0 through 4.

GET the next page of results

Next, let’s say you want to make a call to return the next page from the previous example. As you’ll see below, the page parameter in the following sample link is 2, so the next page of results will show items 5 through 9:

$ curl -H 'Authorization: Bearer ' -X GET 'https://audience.lucidhq.com/api/impact-measurement/v1/campaigns/?page_size=5&page=2'

Here is a quick overview of how to get started with Lucid's Impact Measurement API.

Following these steps will allow you to easily create campaigns and retrieve brand lift metrics from the Impact Measurement API:

1. Obtain OAuth2 access token with client credentials
2. Create and launch campaign measurement
3. Retrieve lift results

Step 1: Obtain Access Token

API requests must include a valid access token in order to pass authentication. Access tokens are retrieved from Lucid's authentication service by using your Lucid-provided client credentials (client_id, client_secret) in the following request:

$ curl -X POST 'https://auth.lucidhq.com/oauth/token' -H 'Content-type: application/json' -d '{"grant_type": "client_credentials", "client_id": "YOUR-CLIENT-ID", "client_secret": "YOUR-CLIENT-SECRET", "audience": "https://api.luc.id", "lucid_scopes": "short app:imt"}'

Your access token is valid for 10 hours; upon expiration, a new access token will need to be generated with the aforementioned process in order to submit API requests.

Step 2: Create Impact Measurement campaigns

The first request in the campaign creation process is Create Campaign Draft. This will allow you to communicate key details to Lucid such as the campaign flight dates, expected impressions and brand study questions. You may continue to update the Campaign Draft until you have completed all setup requirements. Among the required campaign details are industry_id and country_language_id - the mapping values to populate these two fields can be retrieved with List Industries and List Country Languages. The survey questions for the campaign should be inserted in the draft_settings field - example templates for each brand lift survey question and KPI type can be found here.

Upon submitting Create Campaign Draft, the response will include the campaign_id. This campaign ID should be inserted into the Lucid tracking tag for implementation on the campaign's creatives.

If any changes need to be made after draft creation, the Update Campaign Draft request should be used with the campaign_id.

After the campaign and survey question details have been finalized, use the Launch Campaign request to activate your campaign. Please note that no changes can be made to the campaign's survey after launch.

Step 3: Retrieve lift metrics

Once a launched campaign reaches its start date, Lucid will automatically begin recruiting respondents into the survey. You can monitor how the survey is pacing by checking the total_count. In order to ensure accuracy, certain metrics such as Lift will only be available once the total_count is greater than 50.

Use the campaign_id to retrieve the lift results for all of the campaign's brand lift KPI questions with the Calculate Lift for All Questions request. This will return all calculated metrics and sampling statistics for the survey based on the in-target answers indicated.

To dive deeper into a specific question, first obtain the question IDs with List Questions for a Specific Campaign and once you've identified the question of interest, you can use the Lift endpoints to generate a breakdown by site, placement, creative, frequency, and ad channel.

Lucid calculates Lift daily until the campaign has reached its stated end date. To extend the length of a campaign, you must update the end date and the total impression count prior to completion.