Ad Lift Tests Surveys

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to be sunset soon. 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?"
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. ACCOUNT_BILLING_ADMIN ACCOUNT_MANAGER CAMPAIGN_MANAGER
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. ACCOUNT_BILLING_ADMIN ACCOUNT_MANAGER CAMPAIGN_MANAGER CREATIVE_MANAGER VIEWER

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: AWARENESS RECALL FAMILIARITY FAVORABILITY RECOMMENDATION CONSIDERATION EMPLOYER_FAMILIARITY EMPLOYER_FAVORABILITY EMPLOYER_RECOMMENDATION EMPLOYER_CONSIDERATION	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"

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

Sample Request

POST https://api.linkedin.com/rest/adLiftTests/15715/adLiftTestSurveys

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.

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

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)"

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)

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