Study lifecycle

Panel studies that are currently fielding must be paused or stopped before you edit them with PATCH /studies/{study_id}. Only supplied fields change.

Draft and provisioned states

Creating a study does not require every launch setting. A partial study is returned with provisioning_status: "draft" and a missing_requirements array. Study names may contain at most 40 characters. Once the name, study plan, voice, and language are present, saving the study automatically provisions its interviewer. A successful response then returns provisioning_status: "provisioned". Do not create participants or launch panel recruitment before that state. POST /studies/create-with-participants requires those four settings in the study body. It validates the complete request before creating the study or invitations. If a complete study returns provisioning_status: "ready", it is configured but not yet provisioned. Retry a PATCH with its current complete settings. Launch endpoints return 409 Conflict with code: "study_not_provisioned" until provisioning succeeds.

Concept images

Concept images can be attached in a Customize Plan turn or uploaded separately to an accessible study. Use POST /api/public/v1/studies/{study_id}/concept-images with a multipart file and participant-facing label, or POST /api/public/v1/studies/{study_id}/concept-images/from-url with JSON { "url": "https://…", "label": "Concept A" }. Supported file types are PNG, JPEG, GIF, and WebP, up to 10 MB. The URL variant rejects private-network targets and checks every redirect. Either endpoint accepts Idempotency-Key for safe retries. Images are stored privately. A study read returns a first-party image URL that expires after one hour. Fetch the study again when a URL expires; do not save the URL as a permanent asset identifier. The image id remains stable for referring to an attachment. Uploading an image stores it on the study; send its image ID in the research brief if the planning conversation should include it in the Learning Plan. Removing an image or deleting its study revokes existing image links. Deleting a study also removes its uploaded concept images from storage.

Recruitment status

fielding_status describes recruitment separately from provisioning_status, which only describes interviewer readiness. Do not infer recruitment progress from provisioning or interview counts. recruiting_method is panel, byop, or synthetic_respondents. Feasibility requests use lowercase status: received or responded. These values are declared in the response schemas. Panel-country language options and panel launch responses use lowercase language codes such as en and es. The country codes remain uppercase. The language query filter accepts either case. The interview-language catalog also includes auto for automatic detection.

Value	Meaning
`not_started`	A Panel study has not begun recruitment, or a BYOP study is not yet provisioned.
`collecting`	A provisioned BYOP study accepts interviews through its participant links.
`starting`	Panel recruitment is launching or queued.
`fielding`	Panel recruitment is active.
`paused`	Panel recruitment or BYOP collection is paused.
`complete`	Panel recruitment completed its target.
`partial`	Panel recruitment ended with a partial result.
`failed`	Panel recruitment failed.
`stopped`	Panel recruitment or BYOP collection was stopped or cancelled.
`not_applicable`	Synthetic respondents do not use recruitment fielding.
`unknown`	The backend has a newer or unrecognized Panel state.

Pause a study

POST /api/public/v1/studies/{study_id}/pause

Pausing temporarily stops new responses. For panel studies, the existing panel, recruitment progress, target cycle, and reward authorization hold are preserved. Resume the study to continue the same panel.

Resume a study

POST /api/public/v1/studies/{study_id}/resume

Resuming returns the preserved panel survey to fielding. It does not create a replacement panel or a second reward hold.

Stop a study

POST /api/public/v1/studies/{study_id}/stop

Stopping ends active or paused panel recruitment, closes the panel’s target cycle, and settles the reward hold. Any unused authorization is released. Stopping is the appropriate choice when you do not intend to continue the current panel.

Editing an active panel

An edit request for a fielding panel returns 409 Conflict:

{
  "detail": {
    "code": "active_panel_must_be_paused_or_stopped",
    "message": "This panel study is currently fielding. Pause or stop the study before editing it. Pausing preserves the panel hold; stopping settles and releases it.",
    "actions": {
      "pause": {
        "method": "POST",
        "endpoint": "/api/public/v1/studies/study_123/pause",
        "documentation_url": "https://docs.userintuition.ai/api-reference/study-lifecycle#pause-a-study"
      },
      "stop": {
        "method": "POST",
        "endpoint": "/api/public/v1/studies/study_123/stop",
        "documentation_url": "https://docs.userintuition.ai/api-reference/study-lifecycle#stop-a-study"
      }
    }
  }
}

After either action succeeds, retry the original edit request.

Overview

Runnable examples

Studies

Interviews

Reference and usage

Platform administration

Participants

Reports

Targeting

Panels

External panels

Feasibility

Study Management

Webhooks

Draft and provisioned states

Concept images

Recruitment status

Pause a study

Resume a study

Stop a study

Editing an active panel

​Draft and provisioned states

​Concept images

​Recruitment status

​Pause a study

​Resume a study

​Stop a study

​Editing an active panel

Draft and provisioned states

Concept images

Recruitment status

Pause a study

Resume a study

Stop a study

Editing an active panel