Manage brand lift studies

IMPORTANT: To integrate with the Brand Lift Study API, you must complete the initial setup to provide question templates, report slices, and retrieve your provider ID.

After you have completed your initial setup, you can now retrieve and conduct the studies that advertisers create in the platform using the brand lift study template that you provided. During this process, you will retrieve the brand lift study with the fields and questions that the advertiser selected and, as you conduct the survey of the study, you will update the status of the survey and send reports of the results.

Here's what you need to know about the brand lift study integration process:

• When the advertiser creates the study in the platform UI, they set the start and end date of the study.
• You can conduct the study before, after, or on the start date.
• Depending on how you set up your mid-flight update rules during the initial setup, the advertiser can extend the end date or turn off a study before the end date.
• You can send reports in real-time, as needed, or on the end date of the study.

Base URL and authentication

The Brand Lift API uses sandbox and production environments to manage testing and production processes. Here's what you need to know about authenticating to the Brand Lift API:

• The Brand Lift Study API uses the token authentication with only standard tokens from The Trade Desk.
• You must set up your integration using the sandbox environment before you can use the production environment.
• To use the product environment, you must first receive approval from your Technical Account Manager.

To specify which environment to make calls to, use the base URL, as shown in the following table.

Workflow diagram

The following diagram illustrates the process outlined in the next section, which also includes links to the respective step-by-step instructions and provides additional guidance on the decisions you might need to make along the way.

Workflow

The following table outlines the process step by step, while the diagram in the preceding section illustrates the decision-making workflow.

TIP: At any time during the process, you can create and use test studies to test your integration. For details, see Create and manage test studies.

Update the status of a study

To update the status of a study, in a PATCH /api/v1/study/{studyId}/{version} call, include the status value and any custom fields that you provided during the initial setup process. Here's what you need to know:

• The Trade Desk recommends including the estimatedNextReportUpdateUtc value to provide an estimated date and time of when the advertiser can expect to receive a report of the study.
• To enable the pixel to start triggering the creation of the control group, include the segment IDs you specified in the path parameters of your pixel template during the initial setup.
• If needed you can enable the pixel without updating the status of the study. To do this, in a PATCH /api/v1/study/{studyId}/{version} call, include only the segment ID.

The following is an example of a PATCH /api/v1/study/{studyId}/{version} call to change the status to ready.

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

After you update the status of the study and include the required segment ID, the pixel will begin triggering the creation of the control group.

Statuses

The following table lists the possible status values for a study and what each status means for both you (the provider) and the advertiser.

NOTE: If you want to prevent advertiser from making changes during any of these statuses, contact your Technical Account Manager.

Create an aggregated report of the study

An aggregated report enables the advertiser to view the results of the survey directly in the platform. The following table lists the different groups in which aggregated reports are organized.

To create and send an aggregated report of a study, in a POST /api/v1/study/{studyId}/report call, complete the following steps:

1. In the reportForQuestions object array, include a list of all the survey question names as object arrays. For example, ad-recall.
2. In each question object array, include a list of objects that have the following items:
   The name of the report slice associated with the bucket. For example, Gender.
   The name of the bucket. For example, Female.
   The required result metrics in the bucket.
   

Here's a POST /api/v1/study/{studyId}/report request example with two questions (ad-recall and market-awareness) that are organized into Male and Female buckets from the Gender report slice of the results.

{
  "impressionNumber": 652357,
  "reportForQuestions": {
    "ad-recall": [
      {
        "reportSliceName": "Gender",
        "bucketName": "Female",
        "bucketOrder": 1,
        "exposedCount": 500,
        "inTargetExposedCount": 350,
        "exposedPercentage": 0.75,
        "controlCount": 500,
        "inTargetControlCount": 300,
        "controlPercentage": 0.6,
        "totalCount": 1000,
        "liftPercentage": 0.15,
        "confidenceLevel": 0.95,
        "marginOfError": 0.05,
        "isStatisticallySignificant": true,
        "isSufficientSampleSize": true
      },
      {
        "reportSliceName": "Gender",
        "bucketName": "Male",
        "bucketOrder": 1,
        "exposedCount": 500,
        "inTargetExposedCount": 350,
        "exposedPercentage": 0.75,
        "controlCount": 500,
        "inTargetControlCount": 300,
        "controlPercentage": 0.6,
        "totalCount": 1000,
        "liftPercentage": 0.15,
        "confidenceLevel": 0.95,
        "marginOfError": 0.05,
        "isStatisticallySignificant": true,
        "isSufficientSampleSize": true
      }
    ],
    "market-awareness": [
      {
        "reportSliceName": "Gender",
        "bucketName": "Female",
        "bucketOrder": 1,
        "exposedCount": 700,
        "inTargetExposedCount": 250,
        "exposedPercentage": 0.75,
        "controlCount": 500,
        "inTargetControlCount": 300,
        "controlPercentage": 0.6,
        "totalCount": 1000,
        "liftPercentage": 0.15,
        "confidenceLevel": 0.95,
        "marginOfError": 0.05,
        "isStatisticallySignificant": true,
        "isSufficientSampleSize": true
      },
      {
        "reportSliceName": "Gender",
        "bucketName": "Male",
        "bucketOrder": 1,
        "exposedCount": 500,
        "inTargetExposedCount": 350,
        "exposedPercentage": 0.75,
        "controlCount": 500,
        "inTargetControlCount": 300,
        "controlPercentage": 0.6,
        "totalCount": 1000,
        "liftPercentage": 0.15,
        "confidenceLevel": 0.95,
        "marginOfError": 0.05,
        "isStatisticallySignificant": true,
        "isSufficientSampleSize": true
      }
    ]
  }
}

Retrieving reports and attachments

The following table lists the endpoints for retrieving brand lift reports and attachments.

Create and manage test studies

Before you use the production environment, you can set up and test your integration in the sandbox environment. During this process, you will create a test study with randomly generated field values and, to simulate the completion of the survey, you will update the status of the study and send reports of what would be the results.

The following table lists the endpoints that you can use to create and manage test studies.

IMPORTANT: You can create and update test studies only in the sandbox environment.

After completing your testing, contact your Technical Account Manager who will transfer your workflow from the sandbox environment to the product environment where you can retrieve, conduct, and update the status of studies that advertisers create in the platform.

FAQs

When can the advertiser turn off the study?

Any time during the statuses you specify in your mid-flight rules during the initial setup.

Can I send reports in real-time?

Yes. You can send reports in real-time or at the end of the study time frame. For details, see step 5 of the workflow.

Can the advertiser extend the end date of a study?

During the initial setup, you decide if you want the advertiser to extend the end date of the study.