Ad Lift Tests Surveys
Warning
Deprecation Notice
The Marketing Version 202401 (Marketing January 2024) has been sunset. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
The Ad Lift Test Survey API enables advertisers to create, and delete the survey questions (Ad Lift Test Key Metrics) that are asked as part of an Ad Lift Test via API. Users may test for the metrics listed in Available Key Metrics.
Tip
Review the Getting Started Guide first to understand Lift Test concepts.
Each Survey should contain at least one metric.
Available Key Metrics
Symbol | Description |
---|---|
AWARENESS | Ask the user: "Have you heard of brand ?" |
RECALL | Ask the user: "Do you recall seeing an ad for brand/product online or on a mobile device in the last 7 days?"We do not specify "seen on LinkedIn" intentionally as these can also be seen on LAN. |
FAMILIARITY | Ask the user: "How familiar are you with brand ?" |
FAVORABILITY | Ask the user: "How favorably do you view brand/product ?" |
RECOMMENDATION | Ask the user: "How likely are you to recommend brand/product to someone else?" |
CONSIDERATION | Ask the user: "How likely are you to consider brand/product for your next purchase?" |
EMPLOYER_FAMILIARITY | Ask the user: "How familiar are you with brand as an employer?" |
EMPLOYER_FAVORABILITY | Ask the user: "How favorably do you view brand as an employer?" |
EMPLOYER_RECOMMENDATION | Ask the user: "How likely would you recommend brand as employer to your friend or colleague?" |
EMPLOYER_CONSIDERATION | Ask the user: "If you were looking for a job, how likely would you be to consider brand ?" |
Symbol | Description |
---|---|
AWARENESS | Ask the user: "Have you heard of brand ?" |
RECALL | Ask the user: "Do you recall seeing an ad for brand/product online or on a mobile device in the last 7 days?"We do not specify "seen on LinkedIn" intentionally as these can also be seen on LAN. |
FAMILIARITY | Ask the user: "How familiar are you with brand ?" |
FAVORABILITY | Ask the user: "How favorably do you view brand/product ?" |
RECOMMENDATION | Ask the user: "How likely are you to recommend brand/product to someone else?" |
CONSIDERATION | Ask the user: "How likely are you to consider brand/product for your next purchase?" |
EMPLOYER_FAMILIARITY | Ask the user: "How familiar are you with brand as an employer?" |
EMPLOYER_FAVORABILITY | Ask the user: "How favorably do you view brand as an employer?" |
EMPLOYER_RECOMMENDATION | Ask the user: "How likely would you recommend brand as employer to your friend or colleague?" |
EMPLOYER_CONSIDERATION | Ask the user: "If you were looking for a job, how likely would you be to consider brand ?" |
TOP_OF_MIND | Ask the user: "What [a] _____ comes to mind, when you [b] _____________ ?" where a and b are defined by the user. Sample [a] is "brand" and sample [b] is "think of cloud computing." |
Permissions
Permission | Description |
---|---|
rw_ads | Manage and read an authenticated member's lift test surveys. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
|
r_ads | Read an authenticated member's lift test surveys. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
|
See Account Access Controls for more information on ad account roles.
AdLiftTestSurvey Schema
Field Name | Type | Description | Read only, create only |
---|---|---|---|
id | enum AdLiftKeyMetric Available Options:
|
Required The lift key metric we are measuring using these surveys. E.g. we send a survey to the control/test splits that asks "Have you heard of [brand]?" to measure recall. This is used as the key for the subresource. |
Create Only |
adLiftTest | AdLiftTestUrn (e.g. urn:li:adLiftTest:1) | Ad Lift Test that this survey belongs to. | Read Only |
liftTestAccount | SponsoredAccountUrn (e.g urn:li:sponsoredAccount:123) | Advertising account that owns the Ad Lift test that this survey is associated with. (the account that owns the advertising campaigns and the account that serves surveys have to be different for security and survey fairness reasons). Lift Test is owned by the advertiser but we make a special account for serving surveys from LinkedIn on behalf of the advertiser (e.g. "LinkedIn Surveys") and serve from there. This is the advertiser account that "owns" the surveys and whom is interested in the results of the survey. | Read Only |
localizedQuestionText | string (e.g. "Do you recall seeing an ad for your brand?") | Localized question text for this AdLiftKeyMetric. This will be in the same locale as brandNameLocale defined in the associated lift test Ad Lift Test. Ad lift tests only target a single locale, so this string is only available in that single locale. Can be used to generate survey preview. | |
answers | Array of AdLiftTestSurveyAnswerMetadata | The localized answer text (like "Yes" or "Somewhat Familiar") for this answer. This will be in the same locale as brandNameLocale defined in the lift test Ad Lift Test that this survey is for. |
AdLiftTestSurveyAnswerMetadata Schema
AdLiftTestSurveyAnswerMetadata data schema below should be used to build User experience preview in Brand Lift Test provided language.
Field Name | Type | Description | Read only, create only |
---|---|---|---|
adLiftSurveyAnswer | AdLiftSurveyAnswer enum | Unique identifier for this answer (e.g. YES, NO, SOMEWHAT_FAMILIAR). | Read Only |
desired | boolean | Whether or not this answer is desired from the perspective of the survey creator. A desired answer indicates that based on the intent of the survey, the survey creator would prefer the survey taker to pick this answer over other answers where desired is false. For example Somewhat Familiar would be desirable, but Not Familiar would not. | Read Only |
localizedAnswerText | string (e.g. "Yes") | The localized answer text (like "Yes" or "Somewhat Familiar") for this answer. This will be in the same locale as brandNameLocale defined in the lift test Ad Lift Test that this survey is for | Read Only |
Possible Survey Answers
Answer Metadata uses AdLiftSurveyAnswer
Enum to define possible answer string. The enum contains the following values:
Symbol | Description |
---|---|
NEUTRAL | Represents the answer "Neutral" |
NO | Represents the answer "No" |
NOT_AT_ALL_FAMILIAR | Represents the answer "Not at all familiar" |
NOT_SURE | Represents the answer "Not sure" |
ONLY_HEARD_THE_NAME | Represents the answer "I've only heard the name" |
SOMEWHAT_FAMILIAR | Represents the answer "Somewhat familiar" |
SOMEWHAT_FAVORABLE | Represents the answer "Somewhat favorable" |
SOMEWHAT_LIKELY | Represents the answer "Somewhat likely" |
SOMEWHAT_UNFAVORABLE | Represents the answer "Somewhat unfavorable" |
SOMEWHAT_UNLIKELY | Represents the answer "Somewhat unlikely" |
VERY_FAMILIAR | Represents the answer "Very Familiar" |
VERY_FAVORABLE | Represents the answer "Very favorable" |
VERY_LIKELY | Represents the answer "Very likely" |
VERY_UNFAVORABLE | Represents the answer "Very unfavorable" |
VERY_UNLIKELY | Represents the answer "Very unlikely" |
YES | Represents the answer "Yes" |
CUSTOM | Represents a survey answer defined by the advertiser |
NONE_OF_THE_ABOVE | Represents the answer "None of the above" |
Symbol | Description |
---|---|
NEUTRAL | Represents the answer "Neutral" |
NO | Represents the answer "No" |
NOT_AT_ALL_FAMILIAR | Represents the answer "Not at all familiar" |
NOT_SURE | Represents the answer "Not sure" |
ONLY_HEARD_THE_NAME | Represents the answer "I've only heard the name" |
SOMEWHAT_FAMILIAR | Represents the answer "Somewhat familiar" |
SOMEWHAT_FAVORABLE | Represents the answer "Somewhat favorable" |
SOMEWHAT_LIKELY | Represents the answer "Somewhat likely" |
SOMEWHAT_UNFAVORABLE | Represents the answer "Somewhat unfavorable" |
SOMEWHAT_UNLIKELY | Represents the answer "Somewhat unlikely" |
VERY_FAMILIAR | Represents the answer "Very Familiar" |
VERY_FAVORABLE | Represents the answer "Very favorable" |
VERY_LIKELY | Represents the answer "Very likely" |
VERY_UNFAVORABLE | Represents the answer "Very unfavorable" |
VERY_UNLIKELY | Represents the answer "Very unlikely" |
YES | Represents the answer "Yes" |
All available questions and corresponding answers with translations to supported languages can be found an Appendix.
Create Ad Lift Test Survey Questions
New Ad Lift Tests Survey question can be created by issuing a POST to the below URL.
POST https://api.linkedin.com/rest/adLiftTests/{id}/adLiftTestSurveys
POST https://api.linkedin.com/v2/adLiftTests/{id}/adLiftTestSurveys
Sample Request
POST https://api.linkedin.com/rest/adLiftTests/15715/adLiftTestSurveys
POST https://api.linkedin.com/v2/adLiftTests/15715/adLiftTestSurveys
Request Body
{
"elements": [
{
"id": "FAVORABILITY",
"localizedQuestionText" : "",
"answers" : []
},
{
"id": "RECALL",
"localizedQuestionText" : "",
"answers" : []
}
]
}
Sample Response
{
"elements": [
{
"id": "FAVORABILITY",
"status": 201
},
{
"id": "RECALL",
"status": 201
}
]
}
Service Error Code
This section documents different Service Error code you may encounter during create. Each Service error code represents a unique condition where input can be invalid
Service Error Code | Http Status | Additional Detail | Description |
---|---|---|---|
FORBIDDEN | 403 | AdLiftTestValidationDetail | Accessing the resource is forbidden. |
EXPERIMENT_NOT_FOUND | 404 | null | AdLift Test referenced in the request doesn't exist |
SCHEMA_MISMATCH | 422 | null | Invalid schema provided. |
NOT_ENOUGH_QUESTIONS | 422 | AdLiftTestValidationDetail | Brand lift tests need at least one question. |
TOO_MANY_QUESTIONS | 422 | AdLiftTestValidationDetail | Brand lift tests can have no more than six questions. |
ACCOUNT_BUDGET_THRESHOLD_TOO_LOW | 422 | AdLiftTestValidationDetail | Based on the chosen number of questions and test start/end dates, account doesn't have enough budget to run a brand lift test. |
MULTIPLE_VALIDATIONS_FAILED | 422 | BadRequest | Multiple errors occurred during the input validation. Please see errorDetails for more information. |
QUESTION_TEXT_NOT_EDITABLE | 422 | BadRequest | The question text is not editable. |
ANSWER_TEXT_NOT_EDITABLE | 422 | BadRequest | The answer text is not editable. |
CUSTOM_QUESTION_TEXT_INCORRECT_LENGTH | 422 | BadRequest | Brand lift test custom question text has incorrect length. |
CUSTOM_QUESTION_RESPONSE_TEXT_INCORRECT_LENGTH | 422 | BadRequest | Brand lift test custom question response text has incorrect length. |
CUSTOM_QUESTION_NOT_ENOUGH_DESIRED_RESPONSES | 422 | BadRequest | Brand lift test custom question does not have enough desired responses. |
CUSTOM_QUESTION_NOT_ENOUGH_UNDESIRED_RESPONSES | 422 | BadRequest | Brand Lift test custom question does not have enough undesired responses. |
CUSTOM_QUESTION_TOO_MANY_RESPONSES | 422 | BadRequest | Brand Lift test custom question has too many responses. |
Service Error Code | Http Status | Additional Detail | Description |
---|---|---|---|
FORBIDDEN | 403 | AdLiftTestValidationDetail | Accessing the resource is forbidden. |
EXPERIMENT_NOT_FOUND | 404 | null | AdLift Test referenced in the request doesn't exist |
SCHEMA_MISMATCH | 422 | null | Invalid schema provided. |
NOT_ENOUGH_QUESTIONS | 422 | AdLiftTestValidationDetail | Brand lift tests need at least one question. |
TOO_MANY_QUESTIONS | 422 | AdLiftTestValidationDetail | Brand lift tests can have no more than six questions. |
ACCOUNT_BUDGET_THRESHOLD_TOO_LOW | 422 | AdLiftTestValidationDetail | Based on the chosen number of questions and test start/end dates, account doesn't have enough budget to run a brand lift test. |
MULTIPLE_VALIDATIONS_FAILED | 422 | BadRequest | Multiple errors occurred during the input validation. Please see errorDetails for more information. |
Get Ad Lift Test Survey Question List
Ad Lift Test Surveys are fetched in batches. Use the endpoint below to fetch all surveys under an Ad LiftTest.
GET https://api.linkedin.com/rest/adLiftTests/{AdLiftTestId}/adLiftTestSurveys
GET https://api.linkedin.com/v2/adLiftTests/{AdLiftTestId}/adLiftTestSurveys
Sample Response
{
"elements": [
{
"liftTestAccount": "urn:li:sponsoredAccount:123",
"answers": [
{
"desired": true,
"localizedAnswerText": "Yes",
"adLiftSurveyAnswer": "YES"
},
{
"desired": false,
"localizedAnswerText": "No",
"adLiftSurveyAnswer": "NO"
},
{
"desired": false,
"localizedAnswerText": "Not sure",
"adLiftSurveyAnswer": "NOT_SURE"
}
],
"localizedQuestionText": "Have you heard of the Brand Lift Test on LinkedIn?",
"id": "AWARENESS",
"adLiftTest": "urn:li:adLiftTest:456",
},
{
"liftTestAccount": "urn:li:sponsoredAccount:123",
"answers": [
{
"desired": true,
"localizedAnswerText": "Yes",
"adLiftSurveyAnswer": "YES"
},
{
"desired": false,
"localizedAnswerText": "No",
"adLiftSurveyAnswer": "NO"
},
{
"desired": false,
"localizedAnswerText": "Not sure",
"adLiftSurveyAnswer": "NOT_SURE"
}
],
"localizedQuestionText": "Do you recall seeing an ad for Brand Lift Test on LinkedIn online or on a mobile device in the last 7 days?",
"id": "RECALL",
"adLiftTest": "urn:li:adLiftTest:456",
}
],
"paging": {
"count": 10,
"start": 0,
"links": []
}
}
Service Error Code
This section documents different Service Error code you may encounter during GET. Each Service error code represents a unique condition where input can be invalid
Service Error Code | Http Status | Additional Detail | Description |
---|---|---|---|
FORBIDDEN | 403 | AdLiftTestValidationDetail | Accessing the resource is forbidden. |
Delete Ad Lift Test Survey Questions
An Ad Lift Test Survey questions can be deleted by issuing a DELETE call to the URL below. Ad Lift Test Survey questions are deleted in batches. Provide a list of questions to delete to the method below. Questions to delete are specified as a List
for ids
parameter. See sample request below. If an id parameter from the above Available Key Metrics table is not specified, an error will be thrown.
DELETE https://api.linkedin.com/rest/adLiftTests/{AdLiftTestId}/adLiftTestSurveys?ids=List(RECALL)"
DELETE https://api.linkedin.com/v2/adLiftTests/{AdLiftTestId}/adLiftTestSurveys?ids=List(RECALL)"
To delete an Ad Lift Test Survey questions, the ad lift test executionState must be PENDING
. If it’s not, then the request will be rejected with HTTP response code 400.
Sample Request
DELETE https://api.linkedin.com/rest/adLiftTests/11406/adLiftTestSurveys?ids=List(RECALL)
DELETE https://api.linkedin.com/v2/adLiftTests/11406/adLiftTestSurveys?ids=List(RECALL)
Service Error Code
This section documents different Service Error code you may encounter during DELETE. Each Service error code represents a unique condition where input can be invalid
Service Error Code | Http Status | Additional Detail | Description |
---|---|---|---|
FORBIDDEN | 403 | AdLiftTestValidationDetail | Accessing the resource is forbidden. |
EXPERIMENT_NOT_FOUND | 404 | null | AdLift Test referenced in the request doesn't exist |
DELETE_NOT_ALLOWED | 422 | null | A scheduled lift test is not allowed be deleted |