Customize Study Plan

POST

api

public

studies

{study_id}

customize-plan

curl --request POST \
  --url https://api.userintuition.ai/api/public/v1/studies/{study_id}/customize-plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "We want to understand how households choose a blender or microwave. Ask about one recent purchase, what triggered it, the closest alternative, and how they weighed price against reliability."
}
'

{
  "message": "<string>",
  "response_type": "question",
  "study": {
    "id": "<string>",
    "study_type": "in-depth-interview",
    "provisioning_status": "draft",
    "fielding_status": "not_started",
    "name": "<string>",
    "use_case": "<string>",
    "recruiting_method": "panel",
    "interview_format": "chat",
    "voice": "male",
    "language": "<string>",
    "expected_duration_seconds": 900,
    "byop_config": {
      "incentive_amount": 123,
      "is_incentives_enabled": true,
      "auto_send_incentives": true
    },
    "study_link": "<string>",
    "dashboard_url": "<string>",
    "missing_requirements": [
      "<string>"
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "interview_count": 123,
    "report_status": "available"
  },
  "questions": [
    {
      "id": "<string>",
      "text": "<string>",
      "options": [
        "<string>"
      ],
      "default": "<string>"
    }
  ],
  "assumptions": [
    "<string>"
  ],
  "execution_policy": "review_before_fieldwork"
}

{
  "detail": "<unknown>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "outcome": "not_started",
    "recovery_action": "<string>",
    "docs_url": "<string>"
  }
}

{
  "detail": "<unknown>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "outcome": "not_started",
    "recovery_action": "<string>",
    "docs_url": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Authenticate with an API key (prefixed ui_sk_) or a JWT token from the dashboard.

Headers

Idempotency-Key

string | null

X-UI-Organization-ID

string | null

Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.

Maximum string length: 128

Path Parameters

study_id

string

required

Body

application/json

One user turn for the stateful Customize Plan conversation.

message

string

required

Required string length: 1 - 20000

decisions

enum<string>

default:human

human relays required decisions; agent makes reviewable assumptions when possible.

Available options:

human,

agent

execution_policy

enum<string>

default:review_before_fieldwork

Caller workflow constraint, kept separate from participant-facing research content. This endpoint never launches recruitment.

Available options:

review_before_fieldwork,

draft_only

concept_image

PublicCustomizeConceptImage · object | null

Optional native concept-image attachment for this turn. The backend validates, stores, and makes it available to Customize Plan.

Show child attributes

Response

Successful Response

The next Customize Plan message plus the study's resulting state.

message

string

required

response_type

enum<string>

required

Available options:

question,

message,

study_plan

study

PublicStudySummary · object

required

Lightweight study shape returned by the list endpoint (heavy fields such as the study plan and screener questions are stripped — fetch by id).

Show child attributes

questions

PublicPlanningQuestion · object[]

Show child attributes

assumptions

string[]

execution_policy

enum<string>

default:review_before_fieldwork

Available options:

review_before_fieldwork,

draft_only

curl --request POST \
  --url https://api.userintuition.ai/api/public/v1/studies/{study_id}/customize-plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "We want to understand how households choose a blender or microwave. Ask about one recent purchase, what triggered it, the closest alternative, and how they weighed price against reliability."
}
'

{
  "message": "<string>",
  "response_type": "question",
  "study": {
    "id": "<string>",
    "study_type": "in-depth-interview",
    "provisioning_status": "draft",
    "fielding_status": "not_started",
    "name": "<string>",
    "use_case": "<string>",
    "recruiting_method": "panel",
    "interview_format": "chat",
    "voice": "male",
    "language": "<string>",
    "expected_duration_seconds": 900,
    "byop_config": {
      "incentive_amount": 123,
      "is_incentives_enabled": true,
      "auto_send_incentives": true
    },
    "study_link": "<string>",
    "dashboard_url": "<string>",
    "missing_requirements": [
      "<string>"
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "interview_count": 123,
    "report_status": "available"
  },
  "questions": [
    {
      "id": "<string>",
      "text": "<string>",
      "options": [
        "<string>"
      ],
      "default": "<string>"
    }
  ],
  "assumptions": [
    "<string>"
  ],
  "execution_policy": "review_before_fieldwork"
}

{
  "detail": "<unknown>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "outcome": "not_started",
    "recovery_action": "<string>",
    "docs_url": "<string>"
  }
}

{
  "detail": "<unknown>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "outcome": "not_started",
    "recovery_action": "<string>",
    "docs_url": "<string>"
  }
}

Overview

Runnable examples

Studies

Interviews

Reference and usage

Platform administration

Participants

Reports

Targeting

Panels

External panels

Feasibility

Study Management

Webhooks

Authorizations

Headers

Path Parameters

Body

Response