{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"bbdde92f-6383-4267-968d-77f42ff5eb97","name":"Impact Measurement API (Beta)","description":"This document will help guide you through how to use Impact Measurement API.\n\nImpact 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 create both a brand lift study and retrieve brand performance metrics for a campaign.\n\nSurvey data and lift calculation are refreshed on a daily basis, so please keep that in mind when considering frequency of API calls.\n\n## Nuts and bolts\n\n### HTTPS\n\nAll API calls have to be made over HTTPS. Calls made over plain HTTP will redirect to HTTPS.\n\n### Plain JSON\n\nThe 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).\n\n### Trailing /\n\nTrailing slash is optional for all API endpoints, feel free to use it or not.\n\n### Date/Time format\n\nDate and Datetime are always presented in ISO 8601 format.\n\n### Caching\n\nThe API doesn't include any additional caching features, besides what is implied by the protocol layer.\n\n### Rate limiting\n\nWe 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.\n\n## Pagination\n\nSome endpoints, like `/api/impact-measurement/v1/campaigns/`, employ pagination with the use of the `page_size` and `page` parameters. Each paginated  \nendpoint response has these fields:\n\n*   `page` - current page number\n*   `page_size` - number of items included in the current page\n*   `total_items` - total number of items\n    \n\nWe recommend you always explicitly set the `page_size` parameter to ensure you know how many results, per page, you'll get.  \nIf you omit `page_size`, the page will contain 10 items, at most.\n\n### Setting the page_size parameter\n\nLet’s say you need to request all your campaigns, but only want 5 results at a time. Your `GET` would look  \nsomething like this:\n\n```\n$ curl -H 'Authorization: Bearer ' -X GET 'https://audience.lucidhq.com/api/impact-measurement/v1/campaigns/?page_size=5'\n\n```\n\nNote the `page_size` parameter in this call is set to 5, so the response shows items 0 through 4.\n\n### GET the next page of results\n\nNext, let’s say you want to make a call to return the next page from the previous example. As you’ll see below, the  \n`page` parameter in the following sample link is 2, so the next page of results will show items 5 through 9:\n\n```\n$ curl -H 'Authorization: Bearer ' -X GET 'https://audience.lucidhq.com/api/impact-measurement/v1/campaigns/?page_size=5&page=2'\n\n```\n\n# Quick Start\n\nHere is a quick overview of how to get started with [Lucid's Impact Measurement](https://luc.id/audience/impactmeasurement/) API.\n\nFollowing these steps will allow you to easily create campaigns and retrieve brand lift metrics from the Impact Measurement API:\n\n1.  Obtain OAuth2 access token with client credentials\n2.  Create and launch campaign measurement\n3.  Retrieve lift results\n    \n\n### Step 1: Obtain Access Token\n\nAPI requests must include a valid access token in order to pass [authentication](#section/Authentication/OAuth2). Access tokens are retrieved from Lucid's authentication service by using your Lucid-provided client credentials (client_id, client_secret) in the following request:\n\n```\n$ 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\": \"app:imt\"}'\n\n```\n\nYour 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.\n\n**See Authentication section for information around configuring the Postman pre-request script**\n\n### Obtaining your OAuth2 Client ID and Client Secret\n\nTo obtain credentials for using OAuth2 please reach out to [support](https://support.lucidhq.com).\n\n### Step 2: Create Impact Measurement campaigns\n\nThe first request in the campaign creation process is [Create Campaign Draft](#operation/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](#operation/List Industries) and [List Country Languages](#operation/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.\n\nUpon submitting [Create Campaign Draft](#operation/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.\n\nIf any changes need to be made after draft creation, the [Update Campaign Draft](#operation/Update Campaign Draft) request should be used with the `campaign_id`.\n\nAfter the campaign and survey question details have been finalized, use the [Launch Campaign](#operation/Launch Campaign) request to activate your campaign. Please note that no changes can be made to the campaign's survey after launch. **Note** Campaigns launched will be logged in the system with the submission time in UTC.\n\n### Step 3: Retrieve lift metrics\n\nOnce 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.\n\nUse 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](#operation/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.\n\nTo dive deeper into a specific question, first obtain the question IDs with [List Questions for a Specific Campaign](#operation/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](#operation/Calculate Question Lift Breakdown by Site), [placement](#operation/Calculate Question Lift Breakdown by Placement), [creative](/Calculate Question Lift Breakdown by Creative), and [ad channel](#operation/Calculate Question Lift Breakdown by Ad Channel).\n\nLucid 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.\n\n# Authentication\n\nFor OAuth2 we currently support the client_credentials Grant Type. In order to request your Access Token (that must be sent in all API calls through Authorization: Bearer header) you need to make a request to our Authentication & Authorization service, like the following example:\n\n```\n$ 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\": \"app:imt\"}'\n\n```\n\nWhat you need to change in the example above is:\n\n\\-client_id\n\n\\-client_secret\n\n## Postman pre-request script\n\nOnce you have obtained your credentials, you can then set an environment variable for your credentials, audience, and token url. This will allow a seamless authorization process when using the Impact Measurement collection. Head to the Pre-request Script tab under the Impact Measurement parent collection to learn more!\n\nEnvironment Variables for Authentication (OAuth2):  \n\\-`clientId` (your client ID)  \n\\-`clientSecret` (your client secret)  \n\\-`currentAccessToken` (token variable that will be created automatically after successful retrieval. Will be set under 'Authorization: Bearer' header for each request)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"27271744","collectionId":"bbdde92f-6383-4267-968d-77f42ff5eb97","publishedId":"2s93z87NWq","public":true,"publicUrl":"https://im-developer.lucidhq.com","privateUrl":"https://go.postman.co/documentation/27271744-bbdde92f-6383-4267-968d-77f42ff5eb97","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2023-06-26T15:50:33.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/b3f3754c0b46ed19186d8c0117dd3b6a488f336f91b402e0575da253d4d26264","favicon":"https://lucidhq.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://im-developer.lucidhq.com/view/metadata/2s93z87NWq"}