Study object

The study object represents the survey of which the advertiser requests from the provider via the platform UI.

NOTE: This object is returned only in the response of the relevant brand lift endpoints.

Study object format

The following is a JSON example of the study object properties.

{
  "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"
}

Study object properties

The following table lists the study object properties.

Property	Data Type	Description
`providerId`	String	The ID of the provider who owns the study.
`templateKey`	String	The template key or template name that the advertiser used to create the study.
`studyId`	UUID	Globally unique identification of the brand lift study.
`studyName`	String	The name of the study that distinguishes it from other surveys.
`studyStatus`	String (Enum)	The status of the study. For details, see Status enum values.
`country`	String	The country code of where the study is conducted.
`language`	String	The ISO 639-1 code of the language used in the study.
`industry`	String	The industry of the brand to research. The benchmark will be statistics by industry.
`advertiserId`	String	The ID of the advertiser that requested the study.
`campaignIds`	String array	The list of campaign IDs associated with the study.
`startTime`	String (date-time)	The UTC time of when the study should start.
`endTime`	String (date-time)	The UTC time of when the study should end.
`lastUpdateTime`	String (date-time)	The UTC time of when the study was last updated.
`version`	Integer (int64)	The unix timestamp in seconds of when the study was last updated. Here's what you need to know about this property: This value changes every time a study is updated by the advertiser or the provider. Use this number to help avoid and troubleshoot errors during concurrent editing of multiple parties. NOTE: This value is required to update a study with the PATCH /api/v1/study/{studyId}/{version} endpoint.
`estimatedNextReportUpdateUtc`	String (date-time)	The estimated UTC time of when the advertiser can expect the report of the study to be updated.
`errorMessage`	String	A detailed explanation of why the study resulted in the `error` status.
`targeting`	Object	The custom list of audience or geo targeting fields that you configured during the initial setup process. Here's what you need to know: Depending on your implementation, you may have more than one custom field. This field name may vary depending on what you configured.
`targetBrand`	String	The brand that is the subject of the survey.
`competitors`	String	The brands that are competitors of the target brand.
`questions`	Object Array	The list of questions in the study.
`SEGMENT_ID_PLACEHOLDER`	String	The path parameter in the tracking tag URL. Here's what you need to know: Depending on your implementation, you may have more than one segment ID field. This field name may vary depending on what you configured during the initial setup process.
`CUSTOM_FIELD_PLACEHOLDER`	String	The optional custom field that you configured during the initial setup process. Here's what you need to know: Depending on your implementation, you may have more than one custom field. This field name may vary depending on what you configured.

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.

Question object properties

The following table lists the properties of the objects in the questions object array. Each object represents the questions to be asked in the survey, their order, format, answers, and so on.

Property	Data Type	Description
`questionKey`	String	The survey question type that the advertiser selects in the platform.
`questionText`	String	The full text of the survey question.
`questionType`	String enum	Indicates if respondents can choose single, multiple, or a range of answers for the question. For details, see Question type enum values.
`questionOrder`	Integer (int32)	The order in which the survey question appears in the survey.
`attachmentId`	String	The ID of the attachment to the survey question. See the Get Attachment endpoint for information about how to use this ID. TIP: To retrieve the attached file, use the GET /api/v1/study/{studyId}/attachment/{attachmentId} endpoint.
`isAnswerRandomOrdered`	Boolean	If set to `true`, indicates that the answers to the survey question should be displayed in a random order, except for the anchored answer (if there is one) which is always displayed last.
`answers`	Object Array	The list of answers to the survey question.

Question type enum values

The following table lists the questionType enum values that indicate how respondents can answer survey questions.

Property	Data Type	Description
`SingleSelect`	String	The respondents can select only one answer.
`MultipleSelect`	String	The respondents can choose more than one answer.
`SingleSelectInRange`	String	The respondents can answer the survey question with a range of answers usually indicated by a slider.

Answer object properties

The following table lists the properties of the objects in the answers object array. Each object represents an answer option for a question in the survey.

Property	Data Type	Description
`answerText`	String	The full text of the answer to the survey question.
`answerOrder`	Integer (int32)	The order in which that you want to return the answers for the question.
`isInTarget`	Boolean	If set to `true`, indicates that this is the in-target (desired) answer to the question.
`isAnchored`	Boolean	If set to `true`, indicates that the answer is anchored at the bottom of the multiple choice list. For example, `None of the above`.