Ad Lift Tests

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.

Introduction

The Ad Lift Test API enables advertisers to create, modify and report lift tests at scale via API. This reduces the operational lift required to activate portfolios of lift tests on LinkedIn.

Tip

Review the Getting Started Guide first to understand Lift Test concepts.

Permissions

Permission	Description
rw_ads	Manage and read an authenticated member's lift tests. 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 tests. 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.

AdLiftTest Schema

Field Name	Type	Description	Read only, create only
id	long	The ID uniquely identifying the Ad Lift Test. This field is read only and generated at Ad Lift Test creation time. Caller provides this field as -1 when trying to validate the entity fields using the validation endpoint.	Read Only
liftEntity	union[ account: SponsoredAccountUrn, campaignGroup: SponsoredCampaignGroupUrn ] (e.g. "liftEntity": { account": "urn:li:sponsoredAccount:123"}, "liftEntity": { campaignGroup": "urn:li:sponsoredCampaignGroup:124"})	Union representing the possible entities a lift test can operate on. The choice of lift test entity determines which campaigns to operate on. E.g. account indicates the lift test operates on all campaigns in an account, whereas campaignGroup means to only use the campaigns within a given campaign group.
account	SponsoredAccountUrn (e.g. urn:li:sponsoredAccount:123)	Required Advertising account that owns the Ad Lift test and its results.	Create Only
name	string (e.g. "Brand1 Lift Oct 2021")	Required The name of this Ad Lift Test set by the advertiser. Not visible to members.
brandName	string (e.g. "My New Brand")	Required Brand names to be used when surveying users. The brand name will be reviewed and must align with the Advertising Guidelines and LinkedIn Ads Agreement. Be sure to provide the preferred internationalized brand name for the test’s chosen language. (Many advertisers use a different name in different languages)
brandNameLocale.language	string (e.g. "en")	Required Language we expect the brand name to be provided in. We only allow one language per lift test; the brand name and all campaigns within the lift test must have content created on this language. A lowercase two-letter language code as defined by ISO-639. The country and language combination must match one of the supported locales
brandNameLocale.country	string (e.g. "US")	Required An uppercase two-letter country code as defined by ISO-3166. The country and language combination must match one of the supported locales
description	string (e.g. "Brand 22 Lift Test from May 2034")	A memo describing this Lift Test. This is used by advertisers to store information about the test for their later reference. Not visible to members.
schedule.start	long	Required Lift test start time as configured by user (in UTC Epoch Milliseconds). Start time should always be UTC 00:00 to pass validation.	Read Only after test start
schedule.end	long	Required Lift test end time as suggested by user (in UTC Epoch Milliseconds). End time is suggested to be at least 2 weeks after the start time. The Lift Test cannot cannot be set to run more than 90 days, i.e. end time - start time <= 90 days, and may be terminated earlier due to errors or issues with the campaign group or account. Example - if the advertiser's account is canceled we also would cancel the lift test. End time should always be UTC 23:45 to pass validation.
endedAt	long	Lift test actual end time (when executionState set to ENDED). System may terminate the Lift Test before the scheduled end time. Lift tests that have not ended will not have this field populated.	Read Only
userState	Enum of DRAFT READY CANCELED	Required State used by the advertiser to control the Ad Lift Test. For example, if userState is READY, then the advertiser is ready to launch the test as scheduled. This field is used to help determine the Execution State, which represents the actual behavior the Ad Lift Test is currently in. See User State Schema for details
executionState	Enum of CREATED SCHEDULED STARTED ENDED_RESUMABLE ENDED	Overall Ad Lift Test execution state describing its behavior. This field is read only and is derived from the user state and the internal state of the LinkedIn platform. E.g. if userState is READY but the system is waiting to run the experiment because the user scheduled it to begin in a week (using the schedule field), the executionState would be CREATED. See Execution State Schema and Lift Test Workflows for details	Read Only
endReason	Enum of USER_CANCELED END_DATE_REACHED CAMPAIGN_GROUP_NOT_RECOVERABLE ACCOUNT_NOT_RECOVERABLE	A message explaining the reason that caused the end of the Ad Lift Test. This is an enum explaining erroneous conditions, or termination/stopping of the Ad Lift Test. For example, if the account that owns the Lift Test was deleted or archived mid-Lift Test, then the overall Lift Test would be terminated. Similarly, if the lift test successfully ran to completion, we would mark that here instead. See Test End Reason Schema for details	Read only
contentReviewVersion	optional long	A long value represents the content version that was reviewed in accordance to LinedIn content policies. This long should be used as versionTag to fetch review status using Ads Review API	Read only

User State Schema

Symbol	Description
DRAFT	User is still drafting an Ad Lift Test.
READY	User would like to launch the ad lift test as per schedule. This state sends Lift Test for review and activates it on schedule.start date.
CANCELED	User would like to cancel the Ad Lift Test. This state is not reversible. All fields of test become immutable.

Execution State Schema

Symbol	Description
CREATED	Corresponds to AdLiftTestUserState Draft state. The advertiser has just created an Ad Lift Test, and we have not validated it at all. Therefore, it can contain anything. When the advertiser transitions to READY state, we apply validations.
SCHEDULED	Ad Lift Test will start in the future; i.e., user has marked the Ad Lift Test READY, but the start date is set to future. It indicates that there were no issues with the setup of the Ad Lift Test when we moved state from CREATED to SCHEDULED.
STARTED	Ad Lift Test is currently running
ENDED_RESUMABLE	Ad Lift Test has stopped due to reaching the user-defined end date. However, this is not a final/immutable state. For example, the advertiser can extend her test after reaching her end date, as long as it’s still under the 90-day maximum.
ENDED	Ad Lift Test has ended. It becomes immutable (read only). This does not indicate successful or erroneous termination. For that, look at the endReason field.

Test End Reason Schema

Symbol	Description
USER_CANCELED	User canceled the Ad Lift Test.
END_DATE_REACHED	The Ad Lift Test successfully reached the 90 day window and the Ad Lift Test was completed.
CAMPAIGN_GROUP_NOT_RECOVERABLE	The Ad Lift Test has terminated because the campaign group became not recoverable. (E.g., this could happen if the campaign group was permanently canceled.)
ACCOUNT_NOT_RECOVERABLE	Ad Lift Test has terminated since the account became not recoverable. (E.g., this could happen if the account was permanently canceled.)

Create Ad Lift Tests

New Ad Lift Tests can be created by issuing a POST call to:

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

Before making a call, ensure that:

1. All required fields are populated correctly.
2. Set schedule.start to UTC 00:00 and schedule.end to UTC 23:45. schedule can only be created or updated to "future".
3. You have validated and verified that there are no validation errors.
   - Carefully observe and address any warnings. They will help you to uncover any setup related issues that may impact the validity of your result.
4. Followed the Linkedin Ads guidelines when creating ads.

Sample Request

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

{
    "liftEntity": {
        "account": "urn:li:sponsoredAccount:123"
   },
   "account": "urn:li:sponsoredAccount:123",
   "name": "Lift test on my brand",
   "brandName": "My Signature Brand",
   "brandNameLocale": {
      "language": "en",
      "country": "US"
    },
    "description": "Lift test on My Signature Brand",
    "schedule": {
        "start": 1611014400000,
        "end": 1614556800000
    },
    "userState": "DRAFT"
}

Sample Response

{
    "brandName": "My Signature Brand",
    "executionState": "CREATED",
    "description": "Lift test on My Signature Brand",
    "schedule": {
        "start": 1611014400000,
        "end": 1614556800000
    },
    "liftEntity": {
        "account": "urn:li:sponsoredAccount:123"
    },
    "userState": "DRAFT",
    "name": "Lift test on my brand",
    "id": 123,
    "$URN": "urn:li:adLiftTest:123",
    "brandNameLocale": {
        "country": "US",
        "language": "en"
    },
    "account": "urn:li:sponsoredAccount:123"
}

with response header

 Location: /adLiftTests/<lift_test_id>
 x-restli-id: <lift_test_id>

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
SCHEMA_MISMATCH	422	null	Invalid schema provided.
IMMUTABLE_FIELD	422	AdLiftTestValidationDetail	Attempting to update an immutable field.
BRAND_NAME_INCORRECT_LENGTH	422	AdLiftTestValidationDetail	Brand name length should be between 1 and 200 characters.
TEST_NAME_INCORRECT_LENGTH	422	AdLiftTestValidationDetail	Test name length should be between 1 and 200 characters.
DESCRIPTION_INCORRECT_LENGTH	422	AdLiftTestValidationDetail	Description length should be between 0 and 1000 characters.
DURATION_TOO_SHORT	422	AdLiftTestValidationDetail	Attempting to schedule a lift test for less than 3 days. Lift tests must run for at least 3 days.
DURATION_TOO_LONG	422	AdLiftTestValidationDetail	Attempting to schedule a lift test for more than 90 days. Lift tests must run for 90 days or less.
INVALID_START_TIME	422	AdLiftTestValidationDetail	Attempting to schedule a lift test to invalid start time. It either starts in the past or is at least 180 days in the future, or is at a time other than exact midnight UTC. Lift tests must be scheduled to start in the future, within 180 days from now, and at midnight UTC.
INVALID_END_TIME	422	AdLiftTestValidationDetail	Attempting to schedule a lift test to end in the past, at least 180 days in the future, and/or at a time other than fifteen minutes before midnight UTC. Lift tests must be scheduled to end in the future, within 180 days from now, and fifteen minutes before midnight UTC.
ACCOUNT_ALREADY_RUNNING_TEST	422	AdLiftTestValidationDetail	Account provided already has at least one lift test running. This can limit test delivery and bias results.
ACCOUNT_ALREADY_RUNNING_AB_TEST	422	AdLiftTestValidationDetail	Account provided has an A/B test with overlapping schedule. Brand lift test cannot run concurrently with an A/B test.
ACCOUNT_NOT_FOUND	422	AdLiftTestValidationDetail	Account provided doesn't exist or is not eligible for this test. When running an account-level lift test, the account that you test must [1] exist and [2] be the same as the account in which you run the test.
ACCOUNT_NOT_SERVABLE	422	AdLiftTestValidationDetail	Account provided is not eligible to run. Please choose another account.
FORBIDDEN	422	AdLiftTestValidationDetail	Accessing the resource is forbidden.
MULTIPLE_VALIDATIONS_FAILED	422	BadRequest	Multiple errors occurred during the input validation. Please see errorDetails for more information.

An example of AdLiftTestValidationDetail is

{
      "code": "INVALID_START_TIME",
      "errorDetailType": "com.linkedin.ads.AdLiftTestValidationDetail",
      "errorDetails": {
        "pathErrors": [
          {
            "input": {
              "value": {
                "stringValue": "{start=1615507200000, end=1616802300000}"
              },
              "inputPath": {
                "fieldPath": "/schedule"
              }
            }
          }
        ]
      },
      "message": "Attempting to schedule a lift test to start in the past, at least 180 days in the future, and/or at a time other than midnight UTC. Lift tests must be scheduled to start in the future, within 180 days from now, and at midnight UTC."
}

An example of BadRequest due to MULTIPLE_VALIDATIONS_FAILED is

{
   "code":"MULTIPLE_VALIDATIONS_FAILED",
   "errorDetailType":"com.linkedin.common.error.BadRequest",
   "message":"com.linkedin.ads.experiment.common.exceptions.LiftTestEntityValidationException: Lift test has validation errors. entityUrn: urn:li:adLiftTest:-1",
   "errorDetails":{
      "inputErrors":[
         {
            "description":"Attempting to schedule a lift test to start in the past, at least 180 days in the future, and/or at a time other than midnight UTC. Lift tests must be scheduled to start in the future, within 180 days from now, and at midnight UTC.",
            "input":{
               "value":{
                  "stringValue":"{start=1624500046000, end=1624800046000}"
               },
               "inputPath":{
                  "fieldPath":"/schedule"
               }
            },
            "code":"INVALID_START_TIME"
         },
         {
            "description":"Attempting to schedule a lift test to end in the past, at least 180 days in the future, and/or at a time other than fifteen minutes before midnight UTC. Lift tests must be scheduled to end in the future, within 180 days from now, and fifteen minutes before midnight UTC.",
            "input":{
               "value":{
                  "stringValue":"{start=1624500046000, end=1624800046000}"
               },
               "inputPath":{
                  "fieldPath":"/schedule"
               }
            },
            "code":"INVALID_END_TIME"
         }
      ]
   },
   "status":422
}

Once Ad Lift Test is created, you can create the survey subresources according to Create Survey Question guide.

Activate Ad Lift Test

All survey questions need to be created before activating the lift test. When ready, you can activate the lift test as following.

POST https://api.linkedin.com/rest/adLiftTests/{AdLiftTestId}

Sample Request

POST https://api.linkedin.com/rest/adLiftTests/123

{
    "patch" :
    {
        "$set" : {
            "userState": "READY"
        }
    }
}

with response

  HTTP/1.1 204 No Content

Get Lift Tests

Ad Lift Tests can be fetched individually. Use the endpoint below to fetch a single Ad LiftTest.

GET https://api.linkedin.com/rest/adLiftTests/{AdLiftTestId}

Unauthorized requests, including insufficient ad account permissions, will be rejected with HTTP response code 403. Nonexistent AdLiftTestId will be rejected with HTTP response code 404.

Sample Request

GET https://api.linkedin.com/rest/adLiftTests/1234

Sample Response

{
    "brandName": "Your brand name",
    "executionState": "ENDED",
    "description": "Get our product here",
    "schedule": {
        "start": 1595548800000,
        "end": 1598227200000
    },
    "liftEntity": {
        "account": "urn:li:sponsoredAccount:123"
    },
    "userState": "READY",
    "name": "Brand Test",
    "id": 1234,
    "$URN": "urn:li:adLiftTest:1234",
    "brandNameLocale": {
        "country": "US",
        "language": "en"
    },
    "account": "urn:li:sponsoredAccount:123",
    "contentReviewVersion": 1595548800000
}

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

Update Lift Tests

Ad Lift Tests can be updated before and after the lift test starts.

POST https://api.linkedin.com/rest/adLiftTests/{AdLiftTestId}

Before the lift test starts, nearly all fields can be updated. They only exception is account which can never be modified.

After the lift test starts and execution state is STARTED only the following fields can be updated:

• name
• description
• schedule
• userState

While schedule.end can be updated after the lift test has already started, it cannot be extended so far that the scheduled end date is more than 90 days from the scheduled start date.

All fields not included in the above list are immutable once the lift test starts.

Once the lift test is ended, all fields are immutable.

The endpoint for updating a single Ad LiftTest is below. The request must include this header: X-RestLi-Method: partial_update

The patch content in the request body must contain the entire top level field being updated. This is especially important if the field is a complex object. For example, to change the schedule of an Ad Lift Test, the request must contain the entire body of the schedule field, rather than just end.

Sample Request

POST https://api.linkedin.com/rest/adLiftTests/1234

Sample Response

HTTP/1.1 204 No Content

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
SCHEMA_MISMATCH	422	null	Invalid schema provided.
IMMUTABLE_FIELD	422	AdLiftTestValidationDetail	Attempting to update an immutable field.
BRAND_NAME_INCORRECT_LENGTH	422	AdLiftTestValidationDetail	Brand name length should be between 1 and 200 characters.
TEST_NAME_INCORRECT_LENGTH	422	AdLiftTestValidationDetail	Test name length should be between 1 and 200 characters.
DESCRIPTION_INCORRECT_LENGTH	422	AdLiftTestValidationDetail	Description length should be between 0 and 1000 characters.
DURATION_TOO_SHORT	422	AdLiftTestValidationDetail	Attempting to schedule a lift test for less than 3 days. Lift tests must run for at least 3 days.
DURATION_TOO_LONG	422	AdLiftTestValidationDetail	Attempting to schedule a lift test for more than 90 days. Lift tests must run for 90 days or less.
INVALID_START_TIME	422	AdLiftTestValidationDetail	Attempting to schedule a lift test to invalid start time. It either starts in the past or is at least 180 days in the future, or is at a time other than exact midnight UTC. Lift tests must be scheduled to start in the future, within 180 days from now, and at midnight UTC.
INVALID_END_TIME	422	AdLiftTestValidationDetail	Attempting to schedule a lift test to end in the past, at least 180 days in the future, and/or at a time other than fifteen minutes before midnight UTC. Lift tests must be scheduled to end in the future, within 180 days from now, and fifteen minutes before midnight UTC.
ACCOUNT_ALREADY_RUNNING_TEST	422	AdLiftTestValidationDetail	Account provided already has at least one lift test running. This can limit test delivery and bias results.
ACCOUNT_ALREADY_RUNNING_AB_TEST	422	AdLiftTestValidationDetail	Account provided has an A/B test with overlapping schedule. Brand lift test cannot run concurrently with an A/B test.
ACCOUNT_NOT_FOUND	422	AdLiftTestValidationDetail	Account provided doesn't exist or is not eligible for this test. When running an account-level lift test, the account that you test must [1] exist and [2] be the same as the account in which you run the test.
ACCOUNT_NOT_SERVABLE	422	AdLiftTestValidationDetail	Account provided is not eligible to run. Please choose another account.
FORBIDDEN	422	AdLiftTestValidationDetail	Accessing the resource is forbidden.
EXPERIMENT_NOT_FOUND	404	null	AdLift Test referenced in the request doesn't exist
ENDED_TEST_NOT_EDITABLE	422	AdLiftTestValidationDetail	Attempting to update an ENDED test.
TOO_MANY_QUESTIONS	422	AdLiftTestValidationDetail	Brand lift tests can have no more than six questions.
NOT_ENOUGH_QUESTIONS	422	AdLiftTestValidationDetail	Brand lift tests need at least one question.
ACCOUNT_BUDGET_THRESHOLD_TOO_LOW	422	AdLiftTestValidationDetail	Based on the chosen number of questions and test start/end dates, active campaigns in the account don't have enough budget to run a brand lift test.
INVALID_STATE_TRANSITION	422	AdLiftTestValidationDetail	Attempting to conduct an invalid state transition (AdLiftTestValidationResultCode.SCHEMA_MISMATCH, e.g., from ACTIVE to DRAFT).
CONFLICT	422	AdLiftTestValidationDetail	Request could not be processed because of conflict in the current state of the resource.
MULTIPLE_VALIDATIONS_FAILED	422	BadRequest	Multiple errors occurred during the input validation. Please see errorDetails for more information.

Delete Ad Lift Tests

An Ad Lift Test can be deleted by issuing a DELETE call to the URL below. Ad Lift Tests can be deleted individually.

DELETE https://api.linkedin.com/rest/adLiftTests/{AdLiftTestId}

To delete a lift test, its executionState must be PENDING. If it’s not, then the request will be rejected with HTTP response code 405. Unauthorized requests, including insufficient ad account permissions, will be rejected with HTTP response code 403. Nonexistent AdLiftTestId will be rejected with HTTP response code 404. Otherwise, successful requests will return and empty response with HTTP response code 204.

Sample Request

DELETE https://api.linkedin.com/rest/adLiftTests/1234

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
EXPERIMENT_NOT_FOUND	404	null	AdLift Test referenced in the request doesn't exist
FORBIDDEN	403	AdLiftTestValidationDetail	Accessing the resource is forbidden.
DELETE_NOT_ALLOWED	422	null	A scheduled lift test is not allowed be deleted

Find Ad Lift Tests

You can search for an ad lift test using a number of criteria. Supported search parameters:

Parameter	Type	Description
account	optional SponsoredAccountUrn	The advertiser account that created the Ad Lift Test
adLiftTestEntity	optional AdLiftTestLiftEntity	Criteria used to filter lift tests based on the specific account or campaign group being operated on
executionState	optional AdLiftTestExecutionState	Filter Ad Lift Test based on its respective Ad Lift Test Execution State

The request must include a header for Restli Protocol 2.0.0 as X-Restli-Protocol-Version: 2.0.0. Restli 2.0 requires URNs in query params to be URL encoded. For example, urn:li:adLiftTest:1245678 would become urn%3Ali%3AadLiftTest%3A1245678.

Sample Request

GET https://api.linkedin.com/rest/?q=criteria&account=urn%3Ali%3AsponsoredAccount%3A123&adLiftTestEntity=(account:urn%3Ali%3AsponsoredAccount%3A123)&executionState=CREATED

Sample Response

{
    "elements": [
        {
            "brandName": "Sample Brand",
            "executionState": "CREATED",
            "description": "Sample Description",
            "schedule": {
                "start": 1595462400000,
                "end": 1596066300000
            },
            "liftEntity": {
                "account": "urn:li:sponsoredAccount:123"
            },
            "userState": "DRAFT",
            "name": "23JUL2020 Test",
            "id": 11,
            "$URN": "urn:li:adLiftTest:11",
            "brandNameLocale": {
                "country": "US",
                "language": "en"
            },
            "account": "urn:li:sponsoredAccount:123"
        }
    ],
    "paging": {
        "count": 10,
        "start": 0,
        "total": 1,
        "links": []
    }
}

Validate Lift Test Setup

You can validate Ad Lift Test configuration settings using this endpoint before creating the actual test. This endpoint returns list of Errors/Warnings in your current Lift Test configuration.

POST https://api.linkedin.com/rest/adLiftTests?action=validateAdLiftTest

Validation Request Schema

The payload schema of validation request is identical to the the one used for creation request, except for that value of the id. This helps ensuring the same model that is being created is also able to be validated. This schema only contains fields that can be created by the API user.

AdLiftTest Schema for Validation Request

Field Name	Type	Description	Read-Only/Create-Only
id	long	This should be -1 when using this model to validate the entity fields with the validation end point
liftEntity	union[ account: SponsoredAccountUrn, campaignGroup: SponsoredCampaignGroupUrn ] (e.g. "liftEntity": { account": "urn:li:sponsoredAccount:123"})	Union representing the possible entities a lift test can operate on. The choice of lift test entity determines which campaigns to operate on. E.g. account indicates the lift test operates on all campaigns in an account, whereas campaignGroup means to only use the campaigns within a given campaign group.
account	SponsoredAccountUrn (e.g. urn:li:sponsoredAccount:123)	Required Advertising account that owns the Ad Lift test and its results.	Create Only
name	string (e.g. "Brand1 Lift Oct 2021")	Required The name of this Ad Lift Test set by the advertiser. Not visible to members.
brandName	string (e.g. "My New Brand")	Required Brand names to be used when surveying users. The brand name will be reviewed and must align with the Advertising Guidelines and LinkedIn Ads Agreement. Be sure to provide the preferred internationalized brand name for the test’s chosen language. (Many advertisers use a different name in different languages)
brandNameLocale.language	string (e.g. "en")	Required Language we expect the brand name to be provided in. We only allow one language per lift test; the brand name and all campaigns within the lift test must have content created on this language. A lowercase two-letter language code as defined by ISO-639. The country and language combination must match one of the supported locales
brandNameLocale.country	string (e.g. "US")	Required An uppercase two-letter country code as defined by ISO-3166. The country and language combination must match one of the supported locales
description	string (e.g. "Brand 22 Lift Test from May 2034")	A memo describing this Lift Test. This is used by advertisers to store information about the test for their later reference. Not visible to members.
schedule.start	long	Required Lift test start time as configured by user (in UTC Epoch Milliseconds). Start time should always be UTC 00:00 to pass validation.	Read Only after test start
schedule.end	long	Required Lift test end time as suggested by user (in UTC Epoch Milliseconds). End time is suggested to be at least 2 weeks after the start time. The Lift Test cannot cannot be set to run more than 90 days, i.e. end time - start time <= 90 days, and may be terminated earlier due to errors or issues with the campaign group or account. Example - if the advertiser's account is canceled we also would cancel the lift test. End time should always be UTC 23:45 to pass validation.
userState	Enum of DRAFT READY CANCELED	Required State used by the advertiser to control the Ad Lift Test. For example, if userState is READY, then the advertiser is ready to launch the test as scheduled. This field is used to help determine the Execution State, which represents the actual behavior the Ad Lift Test is currently in. See User State Schema for details

Validation Response Schema

Field Name	Type	Description
adLiftTestId	long	Id for the adLiftTest. If the id is -1, it indicates the ad lift test has not yet been created so only a potential lift test was validated. This is in comparison to a non-zero value which would indicate an existing ad lift test model was validated.
validatedAt	long	Time indicating when the validation was run.
items	Array of AdLiftTestValidationResultItem	An array containing all the validation result items. An empty array indicates that no validation issues exist.

AdLiftTestValidationResultItem Schema

Field Name	Type	Description
code	Enum of AdLiftTestValidationResultCode	The error code of the validation result item.
detail.associatedEntity	optional urn of entity that caused issue (e.g. account)	Additional data associated with a single validation error of ad experiment.
detail.pathErrors	optional array of json path	Path reference in Ads Lift Test json object that caused issue.
level	Enum Of WARNING ERROR	The level of the validation result item. The validations with Error level would throw an exception during creation call
message	string	The message of the validation result item.

Sample Request

POST https://api.linkedin.com/rest/adLiftTests?action=validateAdLiftTest

{
    "liftEntity": {
        "account": "urn:li:sponsoredAccount:123"
   },
   "account": "urn:li:sponsoredAccount:123",
   "name": "Lift test on my brand",
   "brandName": "My Signature Brand",
   "brandNameLocale": {
      "language": "en",
      "country": "US"
    },
    "description": "Lift test on My Signature Brand",
    "schedule": {
        "start": 1615489509470,
        "end": 1615499609470
    },
    "userState": "DRAFT"
}

Sample Response

{
    "value": {
        "adLiftTestId": -1,
        "items": [
            {
                "code": "INVALID_START_TIME",
                "message": "Attempting to schedule a lift test to start in the past, at least 180 days in the future, and/or at a time other than midnight UTC. Lift tests must be scheduled to start in the future, within 180 days from now, and at midnight UTC.",
                "level": "ERROR"
            }
        ],
        "validatedAt": 1615489509470
    }
}

Validation Errors

Symbol	Description
SCHEMA_MISMATCH	Input does not match the expected data schema for this endpoint.
INVALID_LOCALE	User has provided invalid locale.
DURATION_TOO_SHORT	User is attempting schedule a lift test for a duration less than 14 days. Lift tests must run for at least 14 days.
DURATION_BELOW_RECOMMENDATION	Lift test scheduled for less than 14 days. To improve the likelihood of conclusive results, we recommend running lift tests for at least 14 days.
DURATION_TOO_LONG	Attempting to schedule a lift test for more than 90 days. Lift tests must run for 90 days or less.
ACCOUNT_NOT_FOUND	Account provided doesn't exist, or caller does not have permission to create lift tests for referenced account.
INVALID_START_TIME	Lift tests must be scheduled to start in the future, within 180 days from now, and at midnight UTC.
INVALID_END_TIME	Lift tests must be scheduled to end in the future, within 180 days from now, and fifteen minutes before midnight UTC.
CAMPAIGN_GROUP_NOT_FOUND	Campaign Group provided doesn't exist, or the caller doesn't have permissions to create lift tests for referenced campaign group.
INSUFFICIENT_PERMISSIONS	Attempting to create or modify a lift test with read-only permissions. You need write permissions to do this.
NOT_ENOUGH_QUESTIONS	Brand lift tests need at least one question.
TOO_MANY_QUESTIONS	Brand lift tests has too many questions.
CAMPAIGN_GROUP_FROM_DIFFERENT_ACCOUNT	The campaign group that was provided is not in the account that was provided.
MULTIPLE_CAMPAIGN_LANGUAGES_NOT_SUPPORTED	Attempting to create a lift test with campaigns that use different languages. All campaigns within the lift test should use the same language.
CAMPAIGN_GROUP_ENDS_BEFORE_TEST	Campaign group provided has an end date before the lift test's end date. This can reduce your measured brand lift.
ACCOUNT_NOT_SERVABLE	Account provided is not eligible to run. Please choose another account.
CAMPAIGN_GROUP_NOT_SERVABLE	Campaign Group provided is not eligible to run. Please choose another Campaign Group.
ENDED_TEST_NOT_EDITABLE	Attempting to update an ENDED test.
IMMUTABLE_FIELD	Attempting to update an immutable field (e.g. lift test start time after lift test has already started).
INVALID_STATE_TRANSITION	Attempting to conduct an invalid state transition (e.g., from ACTIVE to DRAFT).
ACCOUNT_BUDGET_ENDS_TOO_EARLY	Account budget ends before the lift test ends, so brand surveys may stop serving before the test's end date.
CAMPAIGN_GROUP_BUDGET_ENDS_TOO_EARLY	Campaign group budget ends before the lift test ends, so brand surveys may stop serving before the test's end date.
ACCOUNT_ALREADY_RUNNING_TEST	Failed to create a lift test on the specified account because the provided account already has at least one lift test running. This can limit test delivery and bias results.
ACCOUNT_ALREADY_RUNNING_AB_TEST	Account provided has an A/B test with overlapping schedule. Brand lift test cannot run concurrently with an A/B test.
CAMPAIGN_GROUP_ALREADY_RUNNING_TEST	Failed to create a lift test on the specified campaign group because the provided campaign group already has at least one lift test running. This can limit test delivery and bias results.
ACCOUNT_CONTAINS_CAMPAIGN_GROUP_ALREADY_RUNNING_TEST	Failed to create a lift test on the specified account because the provided account contains a campaign group which is part of at least one running lift test. This can limit test delivery and bias results.
CAMPAIGN_GROUP_INSIDE_ACCOUNT_ALREADY_RUNNING_TEST	Failed to create a lift test on the specified campaign group because the provided campaign group is in an account which is part of at least one running lift test. This can limit test delivery and bias results.
ACCOUNT_BUDGET_THRESHOLD_TOO_LOW	Based on the chosen number of questions and test start/end dates, the account doesn't have enough budget to run a brand lift test

Budget Requirements Validation

Advertisers can run lift tests for 1 to 6 key metrics. Depending on how many metrics the advertiser is testing, there are budget threshold requirements on the advertiser's account to set the stage for statistically significant results. This endpoint helps determine the budget requirements given the number of metrics and the schedule.

Use the the action below to get budget requirements. Budget requirements can be used to build User Interface with UI-side predefined validations.

POST https://api.linkedin.com/rest/adLiftTests?action=requiredLiftTestBudgetForKeyMetrics

Action Request Schema

Field Name	Type	Description	Read-Only/Create-Only
account	SponsoredAccountUrn (e.g. urn:li:sponsoredAccount:123)	Required Advertising account that owns the Ad Lift test and its results.	Create Only
schedule.start	long	Required Lift test start time as configured by user (in UTC Epoch Milliseconds). Start time should always be UTC 00:00 to pass validation.	Read Only after test start
schedule.end	long	Required Lift test end time as suggested by user (in UTC Epoch Milliseconds). End time is suggested to be at least 2 weeks after the start time. The Lift Test cannot cannot be set to run more than 90 days, i.e. end time - start time <= 90 days, and may be terminated earlier due to errors or issues with the campaign group or account. Example - if the advertiser's account is canceled we also would cancel the lift test. End time should always be UTC 23:45 to pass validation.

Action Response Schema

Field	Type	Description
liftTestBudget.amount	string representing BigDecimal (e.g. "100")	The budget available in account or campaign group for the duration of the lift test
liftTestBudget.currencyCode	string (e.g. "USD")	An ISO currency code
budgetRequiredForKeyMetrics	Array of AdLiftTestBudgetRequiredForKeyMetrics	An array containing all supported numbers of key metrics and lift test budget required to run a lift test with that amount of key metrics.

AdLiftTestBudgetRequiredForKeyMetrics Schema

Field	Type	Description
numKeyMetrics	int	Number of key metrics that could be used in a lift test
requiredLiftTestBudget.amount	string representing BigDecimal (e.g. "100")	The budget required to run lift test with numKeyMetrics amount of key metrics
requiredLiftTestBudget.currencyCode	string (e.g. "USD")	An ISO currency code

Sample Request

POST https://api.linkedin.com/rest/adLiftTests?action=requiredLiftTestBudgetForKeyMetrics

{
  "account": "urn:li:sponsoredAccount:123",
  "schedule": {
      "start": 1622851200000,
      "end": 1624664700000
  }
}

Sample Response

{
   "value":{
      "liftTestBudget":{
         "currencyCode":"USD",
         "amount":"1500"
      },
      "budgetRequiredForKeyMetrics":[
         {
            "requiredLiftTestBudget":{
               "currencyCode":"USD",
               "amount":"90000.00"
            },
            "numKeyMetrics":2
         },
         {
            "requiredLiftTestBudget":{
               "currencyCode":"USD",
               "amount":"135000.00"
            },
            "numKeyMetrics":3
         },
         {
            "requiredLiftTestBudget":{
               "currencyCode":"USD",
               "amount":"180000.00"
            },
            "numKeyMetrics":4
         },
         {
            "requiredLiftTestBudget":{
               "currencyCode":"USD",
               "amount":"225000.00"
            },
            "numKeyMetrics":5
         },
         {
            "requiredLiftTestBudget":{
               "currencyCode":"USD",
               "amount":"270000.00"
            },
            "numKeyMetrics":6
         }
      ]
   }
}

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
ACCOUNT_NOT_FOUND	422	AdLiftTestValidationDetail	Account provided doesn't exist or is not eligible for this test. When running an account-level lift test, the account that you test must [1] exist and [2] be the same as the account in which you run the test.
FORBIDDEN	403	AdLiftTestValidationDetail	Accessing the resource is forbidden.
DURATION_TOO_SHORT	422	AdLiftTestValidationDetail	Attempting to schedule a lift test for less than 3 days. Lift tests must run for at least 3 days.
DURATION_TOO_LONG	422	AdLiftTestValidationDetail	Attempting to schedule a lift test for more than 90 days. Lift tests must run for 90 days or less.