POST /api/v1/test/study/create-random-test-study

Create a new test study. For details, see Brand lift study integration guide.

IMPORTANT: You can use this endpoint only in the sandbox environment. For details, see Brand Lift Study API reference.

Request example

The following is a POST /api/v1/test/study/create-random-test-study request example.

{
  "studyName": "Test Study Name",
  "startTime": "2024-12-09T00:00:00.000Z",
  "endTime": "2025-02-09T00:00:00.000Z",
  "templateSetKey": "TEMPLATE_SET_KEY_PLACEHOLDER",
  "studyStatus": "Ready",
  "country": "US"
}

Request object properties

The following table lists the POST /api/v1/test/study/create-random-test-study request properties.

Property	Required?	Data Type	Description
`studyName`	Required	String	The name of the test study you want to create.	N/A
`startTime`	Optional	String (date-time)	The UTC time of when the test study should start.
`endTime`	Optional	String (date-time)	The UTC time of when the study should end.
`templateSetKey`	Optional	String	The template key or template name that the advertiser used to create the study.
`studyStatus`	Required	String (Enum)	The status of the study. For details, see Status enum values.
`country`	Optional	String	The country code of where the study is conducted.

Status enum values

The following table lists the possible enum values for the status object. For details, see Brand lift integration guide.

Status	Description
`Ready`	The advertiser created the study in the platform UI. NOTE: During this status and on the start date of the study, the pixel from the template you provided during the initial setup phase will start to trigger the generation of the control group.
`Launching`	The provider retrieved the study and added it to their system.
`Live`	The provider started conducting the study and collecting the results. During this status and depending on the mid-flight update rules from your initial setup, the advertiser can extend the end date or turn off the study.
`TurnedOff`	The advertiser turned off the study. TIP: When this status is received, the provider should initiate a completing or complete status.
`Completing`	The provider has completed the study, but still has report data to deliver.
`Complete`	The study is complete, with all data accounted for.
`Error`	The provider encountered an error with the study. The advertiser must recreate the study.

Response example

A successful response returns a Study object with randomly generated values.

{
  "providerId": "thetradedesk",
  "templateKey": "bls-awareness",
  "studyId": "00000000-0000-0000-0000-000000000001",
  "studyName": "The name of the brand lift study",
  "studyStatus": "Ready",
  "country": "US",
  "language": "en",
  "industry": "Retail",
  "advertiserId": "ADVERTISER_ID_PLACEHOLDER",
  "campaignIds": [
    "CAMPAIGN_ID_PLACEHOLDER_01", 
    "CAMPAIGN_ID_PLACEHOLDER_02"
  ],
  "startTime": "2024-03-01T00:00:00.000Z",
  "endTime": "2024-04-01T00:00:00.000Z",
  "lastUpdateTime": "2024-02-01T10:01:30.359Z",
  "version": 1675245690,
  "estimatedNextReportUpdateUtc": "2024-12-19T04:37:45.493Z",
  "errorMessage": null,
  "targeting": {
    "age": ["18+", "65+"],
    "gender": ["non-binary"],
    "city": ["CITY_NAME_PLACEHOLDER"],
    "region": ["REGION_NAME_PLACEHOLDER"],
    "CUSTOM_TARGETING_FIELD_PLACEHOLDER": [
      "TARGETING_VALUE_PLACEHOLDER_01",
      "TARGETING_VALUE_PLACEHOLDER_02"
    ]
  },
  "targetBrand": "AdvertiserBrand",
  "competitors": ["CompetingBrandA", "CompetingBrandB"],
  "questions": [
    {
      "questionKey": "brand-preference",
      "questionText": "Which of the following brands do you most prefer?",
      "questionType": "SingleSelect",
      "questionOrder": 1,
      "attachmentId": "97e28a16-b0c0-4d49-811d-843aec85acc1",
      "isAnswerRandomOrdered": true,
      "answers": [
        {
          "answerText": "AdvertiserBrand",
          "answerOrder": 1,
          "isInTarget": true,
          "isAnchored": false
        },
        {
          "answerText": "CompetingBrandA",
          "answerOrder": 2,
          "isInTarget": false,
          "isAnchored": false
        },
        {
          "answerText": "CompetingBrandB",
          "answerOrder": 3,
          "isInTarget": false,
          "isAnchored": false
        },
        {
          "answerText": "None of the above",
          "answerOrder": 3,
          "isInTarget": false,
          "isAnchored": true
        }
      ]
    }
  ],
  "SEGMENT_ID_PLACEHOLDER": "a1b2c3",
  "CUSTOM_FIELD_01_PLACEHOLDER": "VALUE_PLACEHOLDER_01",
  "CUSTOM_FIELD_02_PLACEHOLDER": "VALUE_PLACEHOLDER_02"
}