PATCH /api/v1/study/{studyId}/{version}

Update the status of a study. For details, see Brand lift study integration guide.

Path parameters

The following table lists the path parameters that you need to provide to make a request.

Parameter	Required?	Data Type	Description
`studyId`	Required	String	The ID of the study of which you want to update the status.
`version`	Required	Integer	The version of the study of which you want to update the status. 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. To retrieve the version number of a study, use the `GET /api/v1/study/{studyId}`.

Request example

The following is a PUT /api/v1/study/{studyId}/{version} request example.

{
  "status": "Ready",
  "estimatedNextReportUpdateUtc": "2024-11-01T17:45:13.624Z",
  "SEGMENT_ID_PLACEHOLDER": "a1b2c3"
}

Request object properties

The following table lists the PUT /api/v1/study/{studyId}/{version} request object properties.

Property	Required?	Value Type	Description
`status`	Required	String (Enum)	The status you want to set for the study. For details about the possible values, see Status enum values.
`errorMessage`	Required, if `status` is set to `Error`	String	A detailed explanation of why the study resulted in the `error` status.
`estimatedNextReportUpdateUtc`	Optional	String (date-time)	The estimated date and time of when the advertiser can expect to receive a report of the study.
`SEGMENT_ID_PLACEHOLDER`	Required	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 field. This field name may vary depending on what you set during the initial setup process.

Status enum values

The following table lists the enum values for the status property in the request object.

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 the details of a study. For property descriptions, see Study object.

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

Error codes and messages

The following table provides a list of common errors and their respective HTTP error codes.

HTTP Code	Status	Description
404	Bad Request	The study was not found or the provider was mismatched.
409	Bad Request	The version was mismatched or the new status is not supported. The status must be one of the supported status values.