Share via

Ad Lift Tests

  • Article

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.

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

    POST https://api.linkedin.com/v2/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

    POST https://api.linkedin.com/v2/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}

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

    Sample Request

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

    POST https://api.linkedin.com/v2/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}

    GET https://api.linkedin.com/v2/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

    GET https://api.linkedin.com/v2/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}

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

    Lift Test Execution State Editable Fields

    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

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

    {
   "patch":{
      "$set":{
        "userState":"READY",
        "schedule": {
            "start": 1595548800000,
            "end": 1598227200000
        }
      }
   }
}

    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}

    DELETE https://api.linkedin.com/v2/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

    DELETE https://api.linkedin.com/v2/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

    GET https://api.linkedin.com/v2/?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

    POST https://api.linkedin.com/v2/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

    POST https://api.linkedin.com/v2/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

    POST https://api.linkedin.com/v2/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

    POST https://api.linkedin.com/v2/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.