Create Study

POST

api

public

studies

curl --request POST \
  --url https://api.userintuition.ai/api/public/v1/studies/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Recent appliance purchases",
  "study_type": "in-depth-interview",
  "recruiting_method": "byop"
}
'

{
  "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",
  "study_plan": {
    "objectives": "<string>",
    "conversation_flow": "<string>",
    "background": "<string>",
    "learning_goals": "<string>",
    "learning_goals_structured": [
      {
        "id": "<string>",
        "question": "<string>",
        "evidence_needed": "<string>"
      }
    ],
    "study_specific_rules": "<string>",
    "study_improvements": "<string>"
  },
  "screener_questions": [
    {
      "id": "<string>",
      "text": "<string>",
      "type": "single_select",
      "order": 123,
      "options": [
        {
          "id": "<string>",
          "text": "<string>",
          "disqualify": true,
          "selection_rule": "must_select"
        }
      ],
      "input_mode": "integers_only",
      "numeric_ranges": [
        {
          "min": 1,
          "max": 1
        }
      ]
    }
  ],
  "targeting_attributes": [
    {
      "qualification_id": 123,
      "allowed_options": [
        123
      ],
      "disallowed_options": [
        123
      ]
    }
  ],
  "resolved_targeting": [
    {
      "qualification_id": 123,
      "attribute": "<string>",
      "active": true,
      "include": [
        "<string>"
      ],
      "exclude": [
        "<string>"
      ],
      "applies_to": "panel",
      "approximation_note": "<string>"
    }
  ],
  "concept_links": [
    {
      "id": "<string>",
      "url": "<string>",
      "label": "<string>",
      "embeddable": true
    }
  ],
  "concept_images": [
    {
      "id": "<string>",
      "url": "<string>",
      "label": "<string>"
    }
  ],
  "invitation_count": 123,
  "interview_attempt_count": 123,
  "quality_interview_count": 123
}

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

Body

application/json

Create a study. Unknown fields, including incentive settings, are rejected.

name

string

required

Required string length: 1 - 40

recruiting_method

enum<string>

required

Available options:

panel,

byop,

synthetic_respondents

study_type

enum<string>

default:in-depth-interview

Study-type template slug

Available options:

in-depth-interview,

concept-test,

prototype-test

interview_format

enum<string> | null

chat, video, or voice. Defaults to chat and only accepts chat when recruiting_method is synthetic_respondents.

Available options:

chat,

video,

voice

voice

enum<string> | null

Interviewer voice: male (Elliot) or female (Clara)

Available options:

male,

female

language

enum<string>

Interview language: an ISO 639-1 code, or 'auto' to auto-detect. Must be one of the supported options.

Available options:

auto,

af,

am,

ar,

as,

az,

bg,

bn,

bs,

ca,

cs,

cy,

da,

de,

el,

en,

es,

et,

eu,

fa,

fi,

fil,

fr,

ga,

gl,

gu,

he,

hi,

hr,

hu,

hy,

id,

is,

it,

iu,

ja,

jv,

ka,

kk,

km,

kn,

ko,

lo,

lt,

lv,

mk,

ml,

mn,

mr,

ms,

mt,

my,

nb,

ne,

nl,

or,

pa,

pl,

ps,

pt,

ro,

ru,

si,

sk,

sl,

so,

sq,

sr,

su,

sv,

sw,

ta,

te,

th,

tr,

uk,

ur,

uz,

vi,

wuu,

yue,

zh,

zu

study_plan

PublicStudyPlan · object | null

Interview instructions as named sections.

Show child attributes

expected_duration_seconds

integer | null

Maximum planned interview duration in seconds, including all sections, transitions, and likely follow-up probes. Estimate this from the completed study plan; it is not a guaranteed participant completion time.

Required range: x >= 300

screener_questions

PublicScreenerQuestionInput · object[] | null

Show child attributes

targeting_attributes

PublicTargetingAttribute · object[] | null

Target the panel by demographic qualifications (panel studies).

Show child attributes

Response

Successful Response

Full study shape returned by get-by-id (includes the heavy fields).

string

required

study_type

enum<string>

required

Current study-type template slug

Available options:

in-depth-interview,

concept-test,

prototype-test

provisioning_status

enum<string>

required

draft when required interviewer settings are missing, ready when the study can be provisioned, and provisioned when interviews can run

Available options:

draft,

ready,

provisioned

fielding_status

enum<string>

required

Recruitment state, separate from interviewer provisioning. Panel studies report their persisted lifecycle. BYOP studies are collecting once the interviewer is provisioned, and can be paused or stopped; invitation delivery is tracked per participant. Synthetic respondents are not_applicable.

Available options:

not_started,

starting,

collecting,

fielding,

paused,

complete,

partial,

failed,

stopped,

unavailable,

not_applicable,

unknown

name

string | null

Maximum string length: 40

use_case

string | null

Historical study-type label when it is outside the current catalog

recruiting_method

enum<string>

panel, byop, or synthetic_respondents

Available options:

panel,

byop,

synthetic_respondents

interview_format

enum<string> | null

chat, video, or voice

Available options:

chat,

video,

voice

voice

enum<string> | null

male or female

Available options:

male,

female

language

string | null

Interview language code, e.g. 'en'

expected_duration_seconds

integer

default:900

Maximum planned interview duration in seconds, including transitions and likely follow-up probes. This is an estimate, not a guaranteed length.

Required range: x >= 300

byop_config

PublicByopConfigOut · object

Show child attributes

study_link

string | null

Live participant interview link; null until the interviewer is provisioned. This is not a researcher preview URL.

dashboard_url

string | null

Researcher management link for the study

missing_requirements

string[]

Fields still required before the study can be provisioned

created_at

string<date-time> | null

updated_at

string<date-time> | null

interview_count

integer | null

Completed visible non-test interviews satisfying quality criteria, matching list_interviews(status=completed).

report_status

enum<string> | null

Available options:

available,

not_generated

study_plan

PublicStudyPlanOut · object | null

Response variant — all sections optional (a study's stored prompt may not contain every section).

Show child attributes

screener_questions

PublicScreenerQuestion · object[] | null

Show child attributes

targeting_attributes

PublicTargetingAttribute · object[] | null

Show child attributes

resolved_targeting

PublicResolvedTargeting · object[]

Human-readable interpretation of the configured panel targeting

Show child attributes

concept_links

PublicConceptLink · object[]

Show child attributes

concept_images

PublicConceptImage · object[]

Show child attributes

invitation_count

integer | null

Invitation records for this study. A panel launch may use one invitation for many participants.

interview_attempt_count

integer | null

Interview attempts, including attempts that did not yield a quality interview.

quality_interview_count

integer | null

Interviews that passed the study quality criteria.

curl --request POST \
  --url https://api.userintuition.ai/api/public/v1/studies/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Recent appliance purchases",
  "study_type": "in-depth-interview",
  "recruiting_method": "byop"
}
'

{
  "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",
  "study_plan": {
    "objectives": "<string>",
    "conversation_flow": "<string>",
    "background": "<string>",
    "learning_goals": "<string>",
    "learning_goals_structured": [
      {
        "id": "<string>",
        "question": "<string>",
        "evidence_needed": "<string>"
      }
    ],
    "study_specific_rules": "<string>",
    "study_improvements": "<string>"
  },
  "screener_questions": [
    {
      "id": "<string>",
      "text": "<string>",
      "type": "single_select",
      "order": 123,
      "options": [
        {
          "id": "<string>",
          "text": "<string>",
          "disqualify": true,
          "selection_rule": "must_select"
        }
      ],
      "input_mode": "integers_only",
      "numeric_ranges": [
        {
          "min": 1,
          "max": 1
        }
      ]
    }
  ],
  "targeting_attributes": [
    {
      "qualification_id": 123,
      "allowed_options": [
        123
      ],
      "disallowed_options": [
        123
      ]
    }
  ],
  "resolved_targeting": [
    {
      "qualification_id": 123,
      "attribute": "<string>",
      "active": true,
      "include": [
        "<string>"
      ],
      "exclude": [
        "<string>"
      ],
      "applies_to": "panel",
      "approximation_note": "<string>"
    }
  ],
  "concept_links": [
    {
      "id": "<string>",
      "url": "<string>",
      "label": "<string>",
      "embeddable": true
    }
  ],
  "concept_images": [
    {
      "id": "<string>",
      "url": "<string>",
      "label": "<string>"
    }
  ],
  "invitation_count": 123,
  "interview_attempt_count": 123,
  "quality_interview_count": 123
}

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

Body

Response