POST /api/v1/study/{studyId}/report

Send an aggregated report of the brand lift study that ad advertiser can view directly in the platform UI. 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 from which you want to create the report.

Request example

The following is a POST /api/v1/study/{studyId}/report request example.

{
  "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
      }
    ],
    "market-awareness": [
      {
        "reportSliceName": "Age",
        "bucketName": "29 to 39",
        "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
      }
    ]
  }
}

A successful response returns an empty object which indicates the report was added successfully.

Request properties

The following table lists the POST /api/v1/study/{studyId}/report request properties.

Property	Required?	Data Type	Description
`impressionNumber`	Optional	Integer (int64)	The number of impressions that you received. Advertisers in the platform UI will not see this value. TIP: The Trade Desk recommends including this property for troubleshooting purposes.
`reportForQuestions`	Required	Object Array	The list of report objects for each question by name and the aggregated report data associated with them. For property descriptions in each item of the array, see Report object.

Report object

The following table lists the object properties for each report object in the reportForQuestions array.

Property	Required?	Data Type	Description
`reportSliceName`	Required	String(256)	The name of the slice or group of responses in a report that you set up during the initial setup process. For example: `Overall`, `Frequency`, `Gender`, `Age`, `Site`, `Creative`, and so on.
`bucketName`	Required	String(64)	The name of the bucket or a group of responses within the report slice that are organized by a dimension specified by the provider. The following lists some examples of a bucket: In a Gender report slice, common `bucketName` values include `Male` and `Female`. In an Age report slice, common the `bucketName` values include age groups such as `20 to 39`. TIP: This value appears in the report on the platform as is with no modifications. Be sure to create a readable bucket name.
`bucketOrder`	Required	Integer (int32)	The order in which the bucket name will be presented in the report or chart.
`exposedCount`	Optional	Integer (int32)	The number of responses from the exposed group of the survey. In other words, the group of respondents who were exposed to the campaign. TIP: To create a better user experience, The Trade Desk recommends that you include this value whenever possible. A `null` value results in this field being hidden or appearing as `N/A` in the platform UI or exported spreadsheet files.
`inTargetExposedCount`	Optional	Integer (int32)	The number of responses from the exposed group that chose the in-target answer. TIP: To create a better user experience, The Trade Desk recommends that you include this value whenever possible. A `null` value results in this field being hidden or appearing as `N/A` in the platform UI or exported spreadsheet files.
`exposedPercentage`	Optional	Decimal	The percentage of responses in the exposed group (the people in the study who were exposed to the campaign) who chose the in-target answer. The provider determines how this percentage is calculated. TIP: To create a better user experience, The Trade Desk recommends that you include this value whenever possible. A `null` value results in this field being hidden or appearing as `N/A` in the platform UI or exported spreadsheet files.
`controlCount`	Optional	Integer (int32)	The number of responses in the control group of the survey. In other words, the number of responses who were not exposed to the campaign. TIP: To create a better user experience, The Trade Desk recommends that you include this value whenever possible. A `null` value results in this field being hidden or appearing as `N/A` in the platform UI or exported spreadsheet files.
`inTargetControlCount`	Optional	Integer (int32)	The number of responses that chose the in-target answer in the control group of the bucket. TIP: To create a better user experience, The Trade Desk recommends that you include this value whenever possible. A `null` value results in this field being hidden or appearing as `N/A` in the platform UI or exported spreadsheet files.
`controlPercentage`	Optional	Decimal	The percentage, calculated by the provider, of the in-target responses in the control group of the results in the bucket. TIP: To create a better user experience, The Trade Desk recommends that you include this value whenever possible. A `null` value results in this field being hidden or appearing as `N/A` in the platform UI or exported spreadsheet files.
`totalCount`	Optional	Integer (int32)	The total number of responses within the bucket or group. TIP: To create a better user experience, The Trade Desk recommends that you include this value whenever possible. A `null` value results in this field being hidden or appearing as `N/A` in the platform UI or exported spreadsheet files.
`liftPercentage`	Required	Decimal	The percentage of brand lift calculated by the provider.
`confidenceLevel`	Optional	Decimal	The percentage that measures the level of confidence the provider has in the calculated lift percentage. TIP: To create a better user experience, The Trade Desk recommends that you include this value whenever possible. A `null` value results in this field being hidden or appearing as `N/A` in the platform UI or exported spreadsheet files.
`marginOfError`	Optional	Decimal	The margin of error (MOE) percentage that measures the level of accuracy of the survey question results. This percentage is typically calculated by comparing the number of people who took the survey to the population in which the survey took place. TIP: To create a better user experience, The Trade Desk recommends that you include this value whenever possible. A `null` value results in this field being hidden or appearing as `N/A` in the platform UI or exported spreadsheet files.
`isStatisticallySignificant`	Required	Boolean	If set to `true`, indicates the results of this question have statistical significance. If set to `false`, indicates the results have practical significance which means the lift percentage is large enough to have an impact on business outcomes.
`isSufficientSampleSize`	Required	Boolean	If set to `true`, indicates that enough responses have been received to generate a meaningful result. If set to `false`, indicates that this question received insufficient responses. All results in this report slice are hidden to advertiser.

Error codes and messages

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

HTTP Code	Status	Description
400	Bad Request	The data provided is invalid.
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.
422	Bad Request	Validation failed.