Panel targeting quotas

Panel targeting quotas let you reserve part or all of a panel launch for specific answers to eligible single-select targeting attributes. You can use them with either:

POST /api/public/v1/studies/{study_id}/launch-panel
POST /api/public/v1/studies/create-and-launch-panel

Find attribute and option IDs

Call GET /api/public/v1/targeting-attributes/ before building the launch request. Use each catalog row’s qualification_id and the option_id values from its options array. For an existing study, the targeted qualification must already be configured in the study’s targeting_attributes. With create-and-launch-panel, configure the qualification in study.targeting_attributes and put its launch quotas in panel.targeting_attributes.

Playground format

In the API playground, add one option_targets item for every fixed target. option_id is the targeting catalog option ID, and target is the fixed interview count.

curl --request POST \
  --url https://api.userintuition.ai/api/public/v1/studies/{study_id}/launch-panel \
  --header 'Authorization: Bearer <your_api_key_or_jwt_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "target": 20,
    "incident_rate": 25,
    "country_code": "US",
    "targeting_attributes": [
      {
        "qualification_id": 2,
        "option_targets": [
          {
            "option_id": 1,
            "target": 8
          }
        ]
      }
    ]
  }'

This reserves 8 interviews for option 1. Every other qualifying option remains Open and shares the remaining 12 interviews.

Object map format

Direct API clients can continue to send option_targets as an object map. Its keys are option IDs and its values are fixed interview counts:

{
  "qualification_id": 2,
  "option_targets": {
    "1": 8
  }
}

Both formats have identical behavior and validation. The array form exists because the documentation playground cannot preserve numeric object keys.

Create a study and launch its panel

{
  "study": {
    "name": "US customer study",
    "recruiting_method": "panel",
    "targeting_attributes": [
      {
        "qualification_id": 2,
        "allowed_options": [1, 2],
        "disallowed_options": []
      }
    ]
  },
  "panel": {
    "target": 20,
    "incident_rate": 25,
    "country_code": "US",
    "targeting_attributes": [
      {
        "qualification_id": 2,
        "option_targets": [
          {
            "option_id": 1,
            "target": 8
          }
        ]
      }
    ]
  }
}

Validation rules

Only eligible single-select attributes and the panel age attribute can have launch targets.
The attribute must have at least two qualifying options.
Every option target must be a positive whole number.
Targets for one attribute cannot add up to more than the panel’s target.
If the configured targets add up to less than the panel target, at least one qualifying option must be omitted from option_targets and left Open.
The array format cannot contain the same option_id more than once.
A fully specified distribution is valid when its option targets add up exactly to the panel target.
Unknown or disqualifying option IDs are rejected.
Each qualification_id can appear only once in a launch request.

A dry run validates targeting quotas with the same rules as a real launch, without creating a study or panel.

Overview

Studies

Interviews

Participants

Reports

Targeting

Panels

Feasibility

Study Management

Webhooks

Find attribute and option IDs

Playground format

Object map format

Create a study and launch its panel

Validation rules

​Find attribute and option IDs

​Playground format

​Object map format

​Create a study and launch its panel

​Validation rules

Find attribute and option IDs

Playground format

Object map format

Create a study and launch its panel

Validation rules