# Build a research agent
Source: https://docs.userintuition.ai/api-reference/agents

Design, field, and inspect research with the public API and MCP tools

## Start with a reviewable study

An agent can create a draft, help design its interview plan, invite participants, and retrieve evidence. The researcher should review the saved plan and the current recruitment estimate before fieldwork starts. Use an API key with `read` and `write` scopes for draft work; paid panel launch also requires `panel:launch` and a positive lifetime spend cap.

<Steps>
  <Step title="Create a draft">
    Call `POST /api/public/v1/studies/` with an `Idempotency-Key`. Save the returned study ID. See the [study lifecycle](/api-reference/study-lifecycle) for state transitions.
  </Step>

  <Step title="Design the plan">
    Call `POST /api/public/v1/studies/{study_id}/customize-plan` once per conversation turn. Relay returned `questions[]` when `decisions` is `human`. If the researcher delegates ordinary design choices with `decisions: "agent"`, show the returned `assumptions[]` and any remaining questions. Review the persisted plan before recruiting.
  </Step>

  <Step title="Choose recruitment">
    For your own participants, create invitations or a share link. For a paid panel, request the current estimate, show the amount and target to the researcher, then launch with a key that has the required scope and spend cap. The plan customization call never starts recruitment.
  </Step>

  <Step title="Follow progress and evidence">
    Poll fielding progress and report jobs, or subscribe to [webhook events](/api-reference/webhooks/overview). Retrieve the persisted report and source interviews. Keep interview IDs and source references with each answer; distinguish quotations from analysis and recommendations.
  </Step>
</Steps>

The [runnable TypeScript examples](/api-reference/developer-examples) include a fixture mode that uses fictional data and makes no network calls. Start there, then validate the narrow live path your application needs with an authorized test study.

## Connect through MCP

The [MCP setup guide](/mcp-server/overview) covers authentication and tool discovery. Discover the tool schema at runtime, because MCP and REST names or response shapes can differ. The default tool surface includes write operations; use API key scopes and spend caps to limit what a connected agent can do.

## Evaluate before a live launch

Use a fixed set of realistic briefs and record the study ID, request IDs, tool calls, final plan, estimate, and source references for each run. Include cases with missing audience details, a returned planning question, an uncertain write response, an empty study, and a paid panel estimate that exceeds the key's cap.

| Check | Pass condition |
| - | - |
| Plan questions | The agent relays required `questions[]` or labels its `assumptions[]` before claiming the plan is final. |
| Fieldwork approval | The saved plan and current estimate are shown before any paid launch call. |
| Retry safety | A timed-out write reuses its original `Idempotency-Key` with identical input, and the agent checks persisted state when the outcome remains uncertain. |
| Evidence | Every attributed quotation can be found in an accessible source interview; analysis and recommendations are labelled separately. |
| Access and spend | Read-only keys cannot write; paid operations are rejected without their specific scope and a sufficient cap. |

Count passes and failures by scenario, retain failed traces, and rerun the same set when the API contract, tool surface, or agent prompt changes. Fixture results demonstrate integration behavior; they do not establish real research quality. The [examples release checklist](https://github.com/user-intuition/examples/blob/main/docs/release-check.md) covers response shapes, pagination, citations, and source access.

## Current output formats

The public API exposes structured reports, transcript segments, and [private CSV or JSONL interview exports](/api-reference/interview-exports). Downloadable highlight clips and slide decks are still under development. Use the persisted report and interview endpoints for current integrations.


# API Changelog
Source: https://docs.userintuition.ai/api-reference/changelog

Changes to the public integration API and its OpenAPI contract

## 2026-10-01

* Webhooks can now subscribe to `study.paused`, `study.resumed`, and `study.stopped` for successful public API lifecycle transitions. Each event carries a new ID and minimal `study_id`/`fielding_status` data.

* Added private, asynchronous CSV and JSONL interview exports. Each job covers up to 100 interviews and returns `next_page` when more remain. Downloads use 15-minute signed URLs and expire after seven days.

* Added `POST /api/public/v1/studies/{study_id}/customize-plan/jobs` and `GET /api/public/v1/studies/{study_id}/customize-plan/jobs/{job_id}` for durable, pollable planning turns. Jobs return the existing structured planning response on success. Failed turns require inspection before an explicit retry; native concept images remain on the synchronous route.

* `GET /api/public/v1/interviews/{interview_id}` accepts `redact_pii=true` to mask email addresses, phone numbers, and US Social Security numbers in transcript and screener text. It omits participant email and recording URLs from that response. The `pii_redacted` field records whether masking was requested. Pattern masking cannot detect every identifier, including names and street addresses.

* Platform admins (`users.role = admin`) can read public research across organizations, search app-scoped organizations by name or active owner name/email, and select an organization for writes and billing. Organization results include active owner names and email addresses. Admin API keys retain their own scopes and spend caps; MCP tools expose the same organization search and selection.

* Added authenticated external-panel configuration routes for BYOP studies. Create or replace the provider entry mapping and outcome redirects, read the current entry URL, regenerate its token, or disable the integration. Matching MCP tools expose the same operations.

* Added public reference catalogs for languages, interview modes, voice choices, and study-type planning templates, plus a versioned interview usage read. MCP resources and the usage tool now use these public routes.

* BYOP participant invitations accept a study-scoped `external_id` and bounded scalar `metadata` on creation. Participant reads return both fields, lists can filter by exact `external_id` with `study_id`, and PATCH can update or clear the customer ID or replace metadata.

* Interview and participant lists now default to 20 results per page, matching studies and feasibility requests. Set `page_size` explicitly to retain a different page size.

* `PATCH /api/public/v1/participants/{participant_id}` updates the participant email. The older `PUT` operation remains available but is deprecated; the MCP update tool now uses PATCH.

* The API host serves the curated public specification at `/.well-known/openapi.json` as well as `/openapi.json` in production.

* Interview summaries include `ended_at`, `interview_format`, and `language`. `language` is the study's current configured language, not a detected transcript language; older interviews may have used a previous setting. Unknown historical modes remain `null`.

* Transcript `messages` now have a typed public segment schema: `id`, `role`, `message`, and optional `text_offset`, `start_s`, and `end_s`. The response remains paged and bounded.

* `DELETE /api/public/v1/webhooks/` is deprecated. Use `DELETE /api/public/v1/webhooks/{webhook_id}`; the body-based route continues to work during migration.

* The OpenAPI Bearer security scheme no longer labels every credential as a JWT. It continues to accept both API keys and dashboard tokens.

See [versioning and deprecation](/api-reference/versioning-and-deprecation) for how to handle future changes.


# Developer examples
Source: https://docs.userintuition.ai/api-reference/developer-examples

Run TypeScript examples for conducting qualitative research, retrieving study results, and searching existing evidence.

## Start with a runnable example

The [public User Intuition examples repository](https://github.com/user-intuition/examples) demonstrates three workflows using TypeScript. Your application controls the customer experience and interpretation; User Intuition provides research execution and evidence access.

```bash theme={null}
git clone https://github.com/user-intuition/examples.git
cd examples
npm run demo
```

Requires Node.js 22.18 or later. Default fixture mode makes no network calls and requires no API key or spending. Every fixture is fictional; it demonstrates data handling, not measured research performance.

<Note>
  The report and search examples were checked against the 2026-10-05 public OpenAPI and staging reads. The API search guide documents the released contract separately from the runnable example.
</Note>

## Conduct a study

The example separates draft creation, Customize Plan turns, saved-plan review, a recruitment estimate, paid launch, monitoring, and report generation. A plan may require several conversational turns; relay questions rather than inventing answers. Save the study ID to resume.

The user chooses panel recruitment or their own participants. Before paid recruitment, review the current saved plan and full estimate. The example requires explicit live mode and a separate launch approval flag. That flag is not a backend budget limit or an idempotency guarantee.

[Run the study example and fetch its source](/api-reference/examples/conduct-a-study)

## Retrieve study results

Study results expose Study Findings, Participant Responses, Participant Profiles, and Recommended Next Steps. Findings and response summaries are analysis; exact quotations are source evidence; profiles describe the sample; recommendations propose further work.

Keep source references, interview IDs, coverage, and freshness with the report. An interview-level link does not necessarily identify the exact passage behind an answer. The example demonstrates answer-to-reference relationships and checks fictional quotations against their source messages. Retrieval does not regenerate analysis.

[Run the results example and fetch its source](/api-reference/examples/retrieve-study-results)

## Search existing research

Search locates relevant study plans and structured report content across authorized studies. The API ranks candidates and returns only canonical persisted JSON. Inspect each entry in `studies`, including its `index_status`, report IDs, grouped results, dates, call IDs, and finding reference IDs before using the evidence.

Recommendations are distinct from observed evidence. A search over summaries does not prove that all transcript passages were searched. Empty results are different from an API failure, and repeated matches from one interview are not independent participants. Your agent performs the final synthesis.

[Run the search example](/api-reference/examples/search-research-example) or [read the API search guide](/api-reference/examples/search-research).

## Connect through MCP or CLI

Use the [MCP setup guide](/mcp-server/overview) for authentication and current tool discovery. The examples repository includes a [matching MCP and CLI walkthrough](https://github.com/user-intuition/examples/blob/main/docs/mcp-cli.md). REST and tool schemas may differ; use the contract for the surface you call.

## Verify before production use

Run fixture tests and the release-schema check, then validate the narrow live workflow your integration needs with an authorized test study. Do not publish real participant data in a reproduction. A timed-out write can leave an uncertain outcome; inspect persisted state before retrying.

The [release compatibility record](https://github.com/user-intuition/examples/blob/main/docs/release-check.md) covers response shapes, citations, pagination, coverage, errors, and source access. Each API endpoint page contains selectable request examples with the valid fields and values for that operation; start with [Create Study](/api-reference/public-studies/create-study).

## Machine discovery

The [example catalog](https://raw.githubusercontent.com/user-intuition/examples/main/examples.json) lists commands, inputs, outputs, side effects, and raw source URLs. Individual example pages contain complete code blocks generated from the executable source files.


# Conduct a study
Source: https://docs.userintuition.ai/api-reference/examples/conduct-a-study

Runnable TypeScript example: conduct a study, with inputs, output, source code, and execution limits.

[Raw TypeScript source](https://raw.githubusercontent.com/user-intuition/examples/main/examples/conduct-a-study/index.ts) · [Workflow walkthrough](https://github.com/user-intuition/examples/tree/main/examples/conduct-a-study) · [All examples](/api-reference/developer-examples)

## Run locally

Requires Node.js 22.18 or later. Run from the cloned repository; this file imports the shared client and contracts in `src/`. The default uses fictional local fixtures with no credentials, network calls, invitations, or spending.

```sh theme={null}
git clone https://github.com/user-intuition/examples.git
cd examples
npm run study
```

For live calls, supply `USERINTUITION_API_KEY` securely in the environment and explicitly select `--live`. Follow the walkthrough for action-specific arguments and approvals. The report and search adapters were [checked against the released API and staging](https://github.com/user-intuition/examples/blob/main/docs/release-check.md); recheck the live contract when integrating a newer API version.

## Inputs

Fixture mode needs no inputs. Live actions use --action, a study ID after creation, and the action-specific name, message, or request file described in the walkthrough.

## Expected output

Fictional plan/fieldwork walkthrough labeled with fixture mode. Live mode prints the selected operation response.

## Side effects

Fixture mode has no side effects. Live create/customize/launch/report-generation actions write data; launch starts paid recruitment and requires a separate approval flag.

## Failures

Missing study/action inputs, malformed request JSON, a missing launch approval, and HTTP failures stop the operation. An interrupted write may have succeeded; inspect saved state before retrying.

## Complete source file

The following is generated from `examples/conduct-a-study/index.ts`, not maintained as a separate snippet. SHA-256: `f8cd9f0bfeb836b06c65f54595edd330775f835fbe825a50afb07a27e927f990`.

```typescript theme={null}
import { readFile } from "node:fs/promises";
import { args, required, assertLaunchApproval } from "../../src/args.ts";
import { ResearchClient, fixture, output } from "../../src/client.ts";
import { routes } from "../../src/contracts.ts";
const options = args();
if (!options.live) {
  output({
    mode: "fictional fixture; no network, invitations, or spend",
    workflow: await fixture("workflow"),
  });
} else {
  const client = new ResearchClient();
  if (options.action === "create") {
    const name = required(options.name, "name");
    if (name.length > 40)
      throw new Error("Study name must be at most 40 characters.");
    output(
      await client.request("POST", routes.studies, {
        name,
        study_type: "in-depth-interview",
        recruiting_method: "panel",
      }),
    );
  } else {
    const id = required(options.study, "study");
    if (options.action === "customize")
      output(
        await client.request("POST", routes.customize(id), {
          message: required(options.message, "message"),
        }),
      );
    else if (options.action === "review")
      output(await client.request("GET", routes.study(id)));
    else if (options.action === "estimate" || options.action === "launch") {
      const request = JSON.parse(
        await readFile(
          required(options["request-file"], "request-file"),
          "utf8",
        ),
      );
      if (options.action === "launch")
        assertLaunchApproval(id, options["approve-launch"]);
      const study = await client.request<{ provisioning_status: string }>(
        "GET",
        routes.study(id),
      );
      if (study.provisioning_status !== "provisioned")
        throw new Error(
          "Study interviewer is not provisioned. Complete and review the saved plan. This is not a fielding-status check.",
        );
      output(
        await client.request("POST", routes.panel(id), {
          ...request,
          dry_run: options.action === "estimate",
        }),
      );
    } else if (options.action === "monitor") {
      output(
        await client.request(
          "GET",
          `${routes.interviews}?study_id=${encodeURIComponent(id)}&status=completed&page=1&page_size=20`,
        ),
      );
    } else if (options.action === "generate-report")
      output(await client.request("POST", routes.report(id)));
    else
      throw new Error(
        "Choose create, customize, review, estimate, launch, monitor, or generate-report.",
      );
  }
}
```


# Retrieve study results
Source: https://docs.userintuition.ai/api-reference/examples/retrieve-study-results

Runnable TypeScript example: retrieve study results, with inputs, output, source code, and execution limits.

[Raw TypeScript source](https://raw.githubusercontent.com/user-intuition/examples/main/examples/retrieve-study-results/index.ts) · [Workflow walkthrough](https://github.com/user-intuition/examples/tree/main/examples/retrieve-study-results) · [All examples](/api-reference/developer-examples)

## Run locally

Requires Node.js 22.18 or later. Run from the cloned repository; this file imports the shared client and contracts in `src/`. The default uses fictional local fixtures with no credentials, network calls, invitations, or spending.

```sh theme={null}
git clone https://github.com/user-intuition/examples.git
cd examples
npm run results
```

For live calls, supply `USERINTUITION_API_KEY` securely in the environment and explicitly select `--live`. Follow the walkthrough for action-specific arguments and approvals. The report and search adapters were [checked against the released API and staging](https://github.com/user-intuition/examples/blob/main/docs/release-check.md); recheck the live contract when integrating a newer API version.

## Inputs

Live mode requires --study YOUR\_STUDY\_ID. Add --fetch-source to fetch the first supporting interview.

## Expected output

JSON containing mode, report, and source\_references. With --fetch-source, a second JSON object contains the reference and source\_interview, or a source\_status explaining why none was fetched.

## Side effects

Read-only in live mode; it does not generate a report or start research.

## Failures

Missing credentials or study ID, HTTP failures, invalid JSON, and unresolved source interviews are failures, not empty evidence. Stale or unknown freshness is reported separately.

## Complete source file

The following is generated from `examples/retrieve-study-results/index.ts`, not maintained as a separate snippet. SHA-256: `1dca3ac1a43df59b393f2d163e86128c731b146ce505d177a633e4e6bbc69672`.

```typescript theme={null}
import { args, required } from "../../src/args.ts";
import {
  ResearchClient,
  fixture,
  output,
} from "../../src/client.ts";
import { routes, type Report } from "../../src/contracts.ts";
const options = args();
const report = options.live
  ? await new ResearchClient().request<Report>(
      "GET",
      routes.reportFull(required(options.study, "study")),
    )
  : await fixture<Report>("report");
output({
  mode: options.live ? "live" : "fictional fixture; no network or spend",
  report,
  source_references: report.references,
});
if (report.is_stale === true)
  console.error("This report is stale; retrieval did not regenerate it.");
if (report.is_stale == null) console.error("Report freshness is unknown.");

// Inspect one supporting interview without silently fetching an entire library.
if (options["fetch-source"]) {
  const reference = report.references.find((ref) => ref.interview_id);
  if (!reference?.interview_id) {
    output({
      source_status: "No interview reference is available in this report.",
    });
  } else {
    const interview = options.live
      ? await new ResearchClient().request(
          "GET",
          routes.interview(reference.interview_id),
        )
      : (
          await fixture<Array<{ id: string; messages: unknown[] }>>(
            "interviews",
          )
        ).find((item) => item.id === reference.interview_id);
    if (!interview)
      throw new Error(
        "Referenced interview was not found; do not infer its contents.",
      );
    output({
      reference,
      source_interview: interview,
      instruction:
        "Inspect the original passage. A retrieved interview is not automatic verification of a generated summary.",
    });
  }
}
```


# Search research
Source: https://docs.userintuition.ai/api-reference/examples/search-research-example

Runnable TypeScript example: search research, with inputs, output, source code, and execution limits.

[Raw TypeScript source](https://raw.githubusercontent.com/user-intuition/examples/main/examples/search-research/index.ts) · [Workflow walkthrough](https://github.com/user-intuition/examples/tree/main/examples/search-research) · [All examples](/api-reference/developer-examples)

## Run locally

Requires Node.js 22.18 or later. Run from the cloned repository; this file imports the shared client and contracts in `src/`. The default uses fictional local fixtures with no credentials, network calls, invitations, or spending.

```sh theme={null}
git clone https://github.com/user-intuition/examples.git
cd examples
npm run search
```

For live calls, supply `USERINTUITION_API_KEY` securely in the environment and explicitly select `--live`. Follow the walkthrough for action-specific arguments and approvals. The report and search adapters were [checked against the released API and staging](https://github.com/user-intuition/examples/blob/main/docs/release-check.md); recheck the live contract when integrating a newer API version.

## Inputs

Use --query with the research question and --study for a live scoped search. Optional --cursor, --limit, and --fetch-source constrain or extend retrieval. Fixture mode returns a fixed match and does not execute the query.

## Expected output

JSON containing mode, request, and response. The response groups canonical results under studies and includes next\_cursor. With --fetch-source, a second object contains source\_kind and source or explains that there are no matches.

## Side effects

Retrieves existing evidence; does not create studies, regenerate reports, invite people, or launch recruitment.

## Failures

Invalid limits, missing live credentials or study ID, HTTP errors, invalid response shapes, and unresolved sources are failures. A successful empty nested results array is distinct from these errors.

## Complete source file

The following is generated from `examples/search-research/index.ts`, not maintained as a separate snippet. SHA-256: `f9d5d4e9d49b518feb7e22fbce170bbc661184ccc16c039cb94e282bbcabbfe5`.

```typescript theme={null}
import { args, limit, required } from "../../src/args.ts";
import {
  ResearchClient,
  fixture,
  output,
} from "../../src/client.ts";
import {
  routes,
  type SearchRequest,
  type SearchResponse,
} from "../../src/contracts.ts";
const options = args();
const request: SearchRequest = {
  query:
    options.query ?? "What makes people think the product is too expensive?",
  limit: limit(options.limit),
  cursor: options.cursor ?? null,
  filters: {
    study_ids: [options.live ? required(options.study, "study") : (options.study ?? "example-study")],
    content_types: ["study_finding", "participant_response"],
  },
};
const response = options.live
  ? await new ResearchClient().request<SearchResponse>(
      "POST",
      routes.search,
      request,
    )
  : await fixture<SearchResponse>("search");
if (!Array.isArray(response.studies) ||
    response.studies.some((study) => !Array.isArray(study.results)))
  throw new Error(
    "Unexpected search response: studies or nested results is not an array.",
  );
output({
  mode: options.live
    ? "live"
    : "fictional fixture; query is illustrative, not executed",
  request,
  response,
});
// Fetch a source with routes.reportFull(study.study_id) or routes.interview(result.interview_id).
// Paginate with the same query/filters and next_cursor. No new study is created by this example.

if (options["fetch-source"]) {
  const first = response.studies.flatMap((study) =>
    study.results.map((result) => ({ study, result })),
  )[0];
  if (!first) {
    output({ source_status: "No search matches; no source was fetched." });
  } else {
    const { study, result } = first;
    const interviewId = result.interview_id;
    const source = options.live
      ? await new ResearchClient().request(
          "GET",
          interviewId
            ? routes.interview(interviewId)
            : routes.reportFull(study.study_id),
        )
      : interviewId
        ? (
            await fixture<Array<{ id: string; messages: unknown[] }>>(
              "interviews",
            )
          ).find((item) => item.id === interviewId)
        : await fixture("report");
    if (!source)
      throw new Error(
        "Search source was not found; do not infer its contents.",
      );
    output({
      content_id: result.content_id,
      study_id: study.study_id,
      indexed_report_id: study.indexed_report_id,
      source_kind: interviewId ? "interview" : "report",
      source,
      instruction:
        "Check source context and the indexed report ID before citing. This is one result, not exhaustive coverage.",
    });
  }
}
```


# Bring Your Own Panel
Source: https://docs.userintuition.ai/api-reference/external-panels

Connect an external respondent provider to a BYOP study.

Bring Your Own Panel lets your respondent provider send people into a BYOP study through one entry URL. It is separate from [individual participant invitations](/mcp-server/tools/participants) and from paid User Intuition Panel recruitment.

1. Create and configure a study with `recruiting_method: "byop"` and review its saved plan.
2. Confirm the study is provisioned and review its plan. Then `PUT /api/public/v1/studies/{study_id}/external-panel` with completion and screen-out redirect URLs. Optional settings map the provider's respondent, session, or external study IDs and quota-full or technical-failure redirects.
3. Give the returned `entry_url` to the provider after checking the parameter mapping and redirects. The provider substitutes its respondent ID in the entry URL. User Intuition creates a session and returns the respondent to the matching outcome URL.
4. Use `GET` to inspect the current configuration. `POST .../regenerate-token` immediately invalidates the previous entry URL; use an `Idempotency-Key` for safe retries, then update the provider with the replacement. `DELETE` disables new entries without deleting completed interviews.

All configuration routes require an API key with `read` for GET or `write` for changes, plus access to the BYOP study. A paid Panel or synthetic-respondent study cannot use this integration. The `entry_url` is a live respondent link; handle it as a provider credential.

The same workflow is available through the MCP tools `get_external_panel`, `configure_external_panel`, `regenerate_external_panel_token`, and `delete_external_panel`.


# Feasibility request lifecycle
Source: https://docs.userintuition.ai/api-reference/feasibility-lifecycle

Review, page through, and withdraw specialist audience requests.

Use a feasibility request when a panel audience needs manual review. Submission
returns a request ID and `status: "received"`. Keep that ID to retrieve the
request after a client timeout.

`GET /api/public/v1/feasibility-requests/` returns a bounded page with
`requests`, `total_count`, `page`, and `page_size`. The default page size is 20;
the maximum is 100. Requests are ordered newest first.

`GET /api/public/v1/feasibility-requests/{request_id}` returns one request,
including any estimate or response. `expected_response_by` is a committed
review deadline when present. A null value means no deadline has been set;
it does not imply an immediate response.

To withdraw a request that is still `received`, call
`POST /api/public/v1/feasibility-requests/{request_id}/cancel`. The result has
`status: "cancelled"` and `cancelled_at`. Repeating the cancellation returns
the same cancelled request. A request already marked `responded` cannot be
withdrawn and returns 409.


# Interview exports
Source: https://docs.userintuition.ai/api-reference/interview-exports

Download study interview evidence as private CSV or JSONL files

## Export one page

Call `POST /api/public/v1/studies/{study_id}/exports/interviews` with `format=csv` or `format=jsonl`. The default `page=1` covers up to 100 interviews. A read-scoped API key can queue the export. Send an `Idempotency-Key` when retrying the same request after a timeout.

```http theme={null}
POST /api/public/v1/studies/{study_id}/exports/interviews?format=jsonl&page=1&redact_pii=true
Authorization: Bearer ui_sk_...
Idempotency-Key: 97127ee4-65c2-4978-8f8f-4a19dd19812d
```

The `202` response includes a `job_id`. Poll `GET /api/public/v1/studies/{study_id}/exports/interviews/jobs/{job_id}` until `status` is `succeeded`. The successful response includes `download_url`, `record_count`, and `next_page`. Queue that next page to retrieve the rest of a large study.

The JSONL file has one public interview object per line, with its spoken transcript turns. The CSV file has one row per spoken turn, with interview and participant IDs, status, quality, role, turn ID, message, and available timestamps. A CSV file may have more rows than `record_count`, which counts interviews.

## Privacy and retention

Exports default to `redact_pii=true`. This masks email addresses, phone numbers, and US Social Security numbers in transcript and screener text, and omits participant email and recording URLs from JSONL. Pattern masking does not detect every identifier, including names and street addresses. Set `redact_pii=false` only if your use requires the unmasked public interview fields.

Files live in a private storage bucket. The polling endpoint checks study access and job ownership before issuing a fresh signed URL that lasts 15 minutes. The job stops issuing URLs after seven days; the job processor deletes expired export objects. Store downloaded files according to your own retention policy.


# API Introduction
Source: https://docs.userintuition.ai/api-reference/introduction

Integrate with User Intuition to manage studies, participants, interviews, and webhooks

## Public Integration API

Supported settings and scoped usage are available through the [public reference and usage endpoints](/api-reference/reference-and-usage).

The User Intuition API allows you to programmatically manage studies, invite participants, access interview recordings and transcripts, generate reports, field panels, and set up webhooks to receive interview data.

Building an autonomous workflow? Start with [Build a research agent](/api-reference/agents) for the review points, safe retry rules, and an evaluation recipe.

For bulk interview evidence, use [interview exports](/api-reference/interview-exports) to request a private CSV or JSONL file by page.

For an agent-friendly study-design flow, create a study draft and call `POST /api/public/v1/studies/{study_id}/customize-plan` once per conversation turn. The default `decisions: "human"` returns structured `questions[]` for the caller to relay. Use `decisions: "agent"` only when the researcher delegates ordinary design choices; report the returned `assumptions[]` and relay any remaining required questions. Put draft-only workflow constraints in `execution_policy`, outside the research `message`. Customization never launches recruitment, and later invitation or paid-launch approval is still required.

For a planning turn that may take longer than the client timeout, use `POST /api/public/v1/studies/{study_id}/customize-plan/jobs`. It returns `202` and a durable `job_id`; poll `GET /api/public/v1/studies/{study_id}/customize-plan/jobs/{job_id}` for the same structured response in `result`. Only one planning turn may run for a study at a time. A failed job is not replayed automatically because a conversation turn may have changed the saved study; inspect that state before explicitly submitting another turn. Upload a native concept image with the synchronous endpoint first, then use the async endpoint for later text turns.

<Card title="OpenAPI Specification" icon="file-code" href="/api-reference/openapi.json">
  View the complete OpenAPI specification
</Card>

The public OpenAPI document is also available from the API host at `https://api.userintuition.ai/openapi.json` and `https://api.userintuition.ai/.well-known/openapi.json`. Both production URLs list public integration endpoints only.

See the [API changelog](/api-reference/changelog) for contract changes and the [versioning and deprecation policy](/api-reference/versioning-and-deprecation) before migrating an integration.

Review the public [Security & Trust center](https://www.userintuition.ai/security/) for current compliance status, data protection, retention, and incident-response details. Interview detail reads can request `redact_pii=true` to mask common structured identifiers and omit direct identity and recording links; this is pattern masking, so applications handling sensitive interviews should still apply their own review controls.

For current availability checks of the API and MCP server, see the [service status page](https://status.userintuition.ai/).

## Safe retries for creating resources

Send a unique `Idempotency-Key` header when creating a study, participant batch, feasibility request, or webhook, uploading a concept image, customizing a study plan, generating a report, sending a participant reward, or launching a paid panel. The combined create-study-with-participants operation accepts it too. If a request times out, retry with **the same key and identical input**. A completed operation returns its original response without repeating the write. Use a new key for a new operation or changed input.

```http theme={null}
Idempotency-Key: 97127ee4-65c2-4978-8f8f-4a19dd19812d
```

Keys are scoped to the authenticated user, organization, and operation. They contain 1–255 visible ASCII characters without spaces. Reusing a key with different input returns `409 idempotency_key_reused`. Completed results can be replayed for 30 days; after that, treat the key as new. If the first request is still running or its result is uncertain, the API returns `409 idempotency_result_pending`; retrieve the current resource before deciding what to do. An unresolved pending operation remains held until reconciled. Calls without a key retain ordinary behavior and cannot be safely replayed after an uncertain timeout.

A changed request that reuses a key did not start; use a new key. A failed read-only check, such as a missing or inaccessible study before creating participants, also does not start the operation, so the same key can be retried after the prerequisite is fixed.

Participant batch creation and report generation return `202` with a durable `job_id`. Poll `GET /api/public/v1/participants/jobs/{job_id}` or `GET /api/public/v1/studies/{study_id}/report/jobs/{job_id}` until `status` is `succeeded`, then follow `result_url`. Failed jobs return a safe summary; contact support with the job ID when a retry has exhausted. A report also emits `report.ready` when persisted. Use `GET /api/public/v1/studies/{study_id}/fielding-progress` for current completions, target, quality counts, and a rate-based finish estimate when enough data exists.

<Card title="Runnable developer examples" icon="code" href="/api-reference/developer-examples">
  Conduct a study, retrieve the four report sections, and search existing evidence. Start with fictional fixtures that require no account or spending.
</Card>

## Base URL

All API requests should be made to:

```
https://api.userintuition.ai
```

## Authentication

All endpoints require Bearer token authentication. You can authenticate with either an **API key** or a **JWT token**.

```bash theme={null}
Authorization: Bearer <your_api_key_or_jwt_token>
```

### API keys (recommended)

API keys are long-lived credentials ideal for server-to-server integrations and MCP clients. Ordinary users' keys are scoped to their organization. They start with the prefix `ui_sk_`.

Users with the platform role `users.role = admin` can read research across organizations. They can [list organization IDs and select one](/api-reference/platform-admins) for scoped operations. An admin's API key still obeys its own scopes and spend cap.

New keys default to `read`. Add `write` to create or change research. Paid panel launches require `panel:launch`, and participant rewards require `rewards:send`, in each case alongside `write` and a positive lifetime USD spend cap. The cap counts reserved and completed operations; an uncertain operation remains reserved until reconciled. Existing keys retain broad public API scopes and may have no cap, so rotate them to adopt the new controls. API keys use the versioned public API and listed catalog reads; dashboard and billing routes require a dashboard session.

An API key can launch a one-time paid panel after receiving an estimate. Recurring panels are created from a dashboard session because later cycles can be repriced beyond a key's one-cycle estimate.

Use the versioned public interview and report endpoints with an API key. The legacy dashboard endpoints that return raw interview messages or embedded call records require a dashboard session token.

Create and manage your keys from the **Manage Account** pane in the dashboard — no API call required to get started.

<Steps>
  <Step title="Open Manage Account">
    Sign in to the [User Intuition Dashboard](https://app.userintuition.ai), click your avatar in the bottom-left corner of the sidebar, then select **Manage Account**.
  </Step>

  <Step title="Go to the API Keys tab">
    In the account management dialog, click **API Keys** in the sidebar.
  </Step>

  <Step title="Create a key">
    Enter a descriptive name, choose scopes, set a lifetime USD cap if selecting a paid scope, then click **Create Key**. The new key appears in a banner at the top of the page.
  </Step>

  <Step title="Copy the key immediately">
    Click **Copy Key** to copy it to your clipboard. The full key is only shown **once** — after you dismiss the banner or navigate away, only the key prefix remains visible.
  </Step>

  <Step title="Use the key">
    Pass the key as a Bearer token in the `Authorization` header:

    ```bash theme={null}
    Authorization: Bearer ui_sk_aBcDeFgHiJkLmNoPqRs...
    ```
  </Step>
</Steps>

To revoke a key, return to the **API Keys** tab and click the trash icon next to it. Revoked keys stop working immediately and cannot be restored.

<Warning>
  The raw API key is only shown once at creation. If you lose it, revoke the old key and create a new one.
</Warning>

<Note>
  See [Account settings → API keys](/resources/account-settings#api-keys) for the full UI walkthrough.
</Note>

### JWT tokens

JWT tokens are short-lived tokens issued by the dashboard. They are useful for quick testing.

<Steps>
  <Step title="Sign in to your account">
    Sign in to your [User Intuition Dashboard](https://app.userintuition.ai) if you haven't already.
  </Step>

  <Step title="Open your profile">
    Click on your profile in the bottom-left corner of the sidebar. This will show your name and company.
  </Step>

  <Step title="Select View JWT Token">
    Select **"View JWT Token"** from the dropdown menu (it has a key icon).
  </Step>

  <Step title="Copy your token">
    A dialog will appear displaying your JWT token. Click the **"Copy Token"** button to copy the token to your clipboard.
  </Step>

  <Step title="Confirmation">
    You'll see a confirmation message when the token has been successfully copied.
  </Step>
</Steps>

<Warning>
  Keep your JWT token secure and do not share it with others. This token provides authenticated access to your account.
</Warning>

## Available Resources

<CardGroup>
  <Card title="Studies" icon="robot" href="/api-reference/public-studies/list-studies">
    Create and manage your studies, screeners, and interview configuration.
  </Card>

  <Card title="Interviews" icon="phone" href="/api-reference/public-interviews/list-interviews">
    Access interview records, transcripts, recordings, and analysis data.
  </Card>

  <Card title="Participants" icon="envelope" href="/api-reference/public-participants/create-participants">
    Invite participants, send rewards, and track their status.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/overview">
    Receive interview data at your own endpoint as soon as an interview completes.
  </Card>
</CardGroup>

## Response Format

All responses are returned in JSON format. Successful list responses include the resource collection plus pagination information (the collection key matches the resource, e.g. `studies`, `participants`, `interviews`):

```json theme={null}
{
  "studies": [...],
  "total_count": 100,
  "page": 1,
  "page_size": 20
}
```

## Error Handling

The API uses standard HTTP status codes:

| Status Code | Description |
| - | - |
| `200` | Success |
| `201` | Created |
| `400` | Bad Request - Invalid input |
| `401` | Unauthorized - Invalid or missing API key or session token |
| `403` | Forbidden - The credential cannot access this resource |
| `404` | Not Found |
| `409` | Conflict - The resource is not in the required state |
| `422` | Validation error |
| `429` | Too Many Requests |
| `500` | Internal Server Error |

Every public API JSON error includes an `error` object and an `X-Request-ID` response header. The `request_id` in the body matches that header. The existing `detail` field remains for clients that already use it; its shape can be a string, list, or object.

```json theme={null}
{
  "detail": {
    "code": "stale_panel_estimate",
    "message": "The estimate expired or its study, launch inputs, balance, or price changed.",
    "recovery_action": "estimate_panel"
  },
  "error": {
    "code": "stale_panel_estimate",
    "message": "The estimate expired or its study, launch inputs, balance, or price changed.",
    "field": null,
    "request_id": "74c5e6ec-9b78-4df1-97ce-bd12c952ca5a",
    "outcome": "not_started",
    "recovery_action": "estimate_panel",
    "docs_url": "https://docs.userintuition.ai/api-reference/introduction"
  }
}
```

For a write with `outcome: "unknown"`, retrieve the current resource state before retrying. `field` identifies the first invalid field when validation fails. Include the request ID when contacting support; do not include credentials.

An error with `outcome: "not_started"` means the request was rejected before that operation changed state. For example, a stale panel estimate or an invalid pause, resume, or stop transition is rejected before launch or fielding changes begin. Other conflicts can still report `unknown`; retrieve the resource before retrying those writes.

| Situation | `outcome` | Recovery |
| - | - | - |
| Input or rate-limit rejection before work begins | `not_started` | Correct input or wait for `Retry-After` |
| A conflict checked before a write | `not_started` | Follow `recovery_action` |
| A write whose result may have changed state | `unknown` | Retrieve current state before retrying |
| A failed read | `failed` | Retry the read |

Use the returned `outcome` and `recovery_action`, not the HTTP status alone, to decide whether a write is safe to repeat.

## Report freshness and historical search

`is_stale: true` means the saved report no longer matches its current inputs. Those inputs include interview evidence, study settings, and report generation settings. Therefore `stale_reason: "inputs_changed"` can appear with `new_interviews_since: 0`; regenerate the report to use the current settings.

Search documents indexed before fieldwork dates were introduced may have `research_period: null`. Date filters exclude undated documents. Older reports with a saved interview evidence snapshot can be reindexed to restore their fieldwork dates; reports without that snapshot must be regenerated before date-filtered search can include them.

## Rate Limiting

API requests are rate limited to ensure fair usage. The default budget is 120 requests per 60 seconds per authenticated user; deployed configuration can change it. Successful responses include `RateLimit-Policy` and `RateLimit` headers showing the active limit, remaining requests, and reset time. A `429 Too Many Requests` response also includes `Retry-After`. Wait for the indicated delay before retrying a read. For a write, check current state before retrying. If the limiter is unavailable, requests continue without rate headers.

## Support

For API support, contact [support@userintuition.ai](mailto:support@userintuition.ai).


# Panel targeting quotas
Source: https://docs.userintuition.ai/api-reference/panel-targeting

Set fixed interview targets for selected panel attribute options while leaving remaining capacity open

Panel targeting quotas let you reserve part or all of a panel launch for specific answers to eligible single-select targeting attributes. You can preview 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`. This combined endpoint is for dry-run estimates only. To recruit, create the study, obtain its current estimate, and launch it with that estimate ID after approval.

## Request formats

The request pages contain selectable, copyable examples beside the request-body schema:

* [Launch Panel](/api-reference/public-studies/launch-panel) includes an untargeted cost estimate, the playground-safe array form, the equivalent object-map form, and a paid launch.
* [Create Study and Launch Panel](/api-reference/public-studies/create-study-and-launch-panel) includes a targeted dry run. Paid recruitment uses the separate Launch Panel endpoint with a current estimate ID.

In the playground-safe array form, add one `{ option_id, target }` item for every fixed target. Direct API clients may instead send `option_targets` as an object whose keys are option IDs and values are fixed interview counts. Both forms have identical behavior. Options omitted from either form remain **Open** and share the panel capacity left after fixed targets.

## 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.

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


# Platform admin access
Source: https://docs.userintuition.ai/api-reference/platform-admins

Discover organizations and select the right organization for public API operations.

Only a user whose database role is `users.role = admin` has platform-wide public API access. An organization membership role such as owner or admin does not grant access to other organizations. The backend checks the current database role for each public API session or API-key request. API keys still need the relevant `read`, `write`, `panel:launch`, or `rewards:send` scope and retain their lifetime spend cap.

Call `GET /api/public/v1/admin/organizations` with a `read` credential to get paginated organization IDs, names, and active owners' names and email addresses in the current app. Pass `search` to match an organization name, owner name, or owner email before pagination. An organization can have multiple owners; `owners` is an array and can be empty. The endpoint is available only to platform admins.

Without an organization selection, platform admins can list and read public research across the app. Supply an organization ID to narrow account-scoped lists and usage, inspect its wallet, create work in that organization, or change its studies:

```http theme={null}
GET /api/public/v1/account/ HTTP/1.1
Authorization: Bearer ui_sk_...
X-UI-Organization-ID: org_example
```

The same optional header appears on public API operations. It is required when a platform admin changes a study in another organization, creates its participants, or performs a paid action against its wallet. The API rejects an unknown organization and rejects the header for non-admin callers. An update without the study's organization selected returns `409 admin_organization_required`; a different selected organization returns `404`. Selecting an organization changes the request's billing and audit context; it does not remove API-key scope checks or agent approval requirements.

The MCP tools use the optional `organization_id` input for the same selection. Start with `list_organizations`, optionally searching by organization name, owner name, or owner email. Show the matches to the human and pass the selected ID to the relevant tool. `get_account` and `get_interview_usage_stats` also accept it. Platform admins should show the selected organization and the current estimate to the human before a paid launch or participant reward.


# List Admin Organizations
Source: https://docs.userintuition.ai/api-reference/public-admin/list-admin-organizations

/api-reference/openapi.json get /api/public/v1/admin/organizations
Find organizations and active owners in this app for platform-admin selection.



# Get Interview Export Job
Source: https://docs.userintuition.ai/api-reference/public-exports/get-interview-export-job

/api-reference/openapi.json get /api/public/v1/studies/{study_id}/exports/interviews/jobs/{job_id}
Poll a private export and receive a fresh 15-minute URL when complete.



# Queue Interview Export
Source: https://docs.userintuition.ai/api-reference/public-exports/queue-interview-export

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/exports/interviews
Queue a private CSV or JSONL export for one page of a study's interviews.



# Delete Study External Panel
Source: https://docs.userintuition.ai/api-reference/public-external-panels/delete-study-external-panel

/api-reference/openapi.json delete /api/public/v1/studies/{study_id}/external-panel
Disable the external-panel entry link for an owned BYOP study.



# Get Study External Panel
Source: https://docs.userintuition.ai/api-reference/public-external-panels/get-study-external-panel

/api-reference/openapi.json get /api/public/v1/studies/{study_id}/external-panel
Get the external-panel entry link and outcome redirects for an owned BYOP study.



# Put Study External Panel
Source: https://docs.userintuition.ai/api-reference/public-external-panels/put-study-external-panel

/api-reference/openapi.json put /api/public/v1/studies/{study_id}/external-panel
Create or replace the external-panel integration for an owned BYOP study.



# Regenerate Study External Panel Token
Source: https://docs.userintuition.ai/api-reference/public-external-panels/regenerate-study-external-panel-token

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/external-panel/regenerate-token
Replace the public entry token, immediately invalidating the old link.



# Get Feasibility Request
Source: https://docs.userintuition.ai/api-reference/public-feasibility/get-feasibility-request

/api-reference/openapi.json get /api/public/v1/feasibility-requests/{request_id}
Get a feasibility request by ID.



# List Feasibility Requests
Source: https://docs.userintuition.ai/api-reference/public-feasibility/list-feasibility-requests

/api-reference/openapi.json get /api/public/v1/feasibility-requests/
List the current account's feasibility requests, newest first.



# Submit Feasibility Request
Source: https://docs.userintuition.ai/api-reference/public-feasibility/submit-feasibility-request

/api-reference/openapi.json post /api/public/v1/feasibility-requests/
Submit an audience for manual feasibility review.



# Delete Interview
Source: https://docs.userintuition.ai/api-reference/public-interviews/delete-interview

/api-reference/openapi.json delete /api/public/v1/interviews/{interview_id}
Soft-delete an interview owned by the authenticated user.



# Get Interview
Source: https://docs.userintuition.ai/api-reference/public-interviews/get-interview

/api-reference/openapi.json get /api/public/v1/interviews/{interview_id}
Read one interview's public metadata and a bounded page of transcript messages.



# List Interviews
Source: https://docs.userintuition.ai/api-reference/public-interviews/list-interviews

/api-reference/openapi.json get /api/public/v1/interviews/
List interview summaries with pagination and optional study, participant, status, or quality filters.



# List Panel Countries
Source: https://docs.userintuition.ai/api-reference/public-panel-countries/list-panel-countries

/api-reference/openapi.json get /api/public/v1/panel-countries/
Supported panel countries with their language options. Provide `language`
OR `country` to filter (not both); omit both to list all.



# Create Participants
Source: https://docs.userintuition.ai/api-reference/public-participants/create-participants

/api-reference/openapi.json post /api/public/v1/participants/
Queue up to 100 invitations. Poll the returned job before listing participants.



# Get Participant
Source: https://docs.userintuition.ai/api-reference/public-participants/get-participant

/api-reference/openapi.json get /api/public/v1/participants/{participant_id}
Retrieve one BYOP participant and their current lifecycle status.



# List Participants
Source: https://docs.userintuition.ai/api-reference/public-participants/list-participants

/api-reference/openapi.json get /api/public/v1/participants/
List BYOP participants and invitation status, optionally filtered by study or email.



# Patch Participant
Source: https://docs.userintuition.ai/api-reference/public-participants/patch-participant

/api-reference/openapi.json patch /api/public/v1/participants/{participant_id}
Update email, customer ID, or bounded metadata.



# Send Participant Reward
Source: https://docs.userintuition.ai/api-reference/public-participants/send-participant-reward

/api-reference/openapi.json post /api/public/v1/participants/{participant_id}/reward
Send the configured incentive to a participant (BYOP studies only).



# Update Participant
Source: https://docs.userintuition.ai/api-reference/public-participants/update-participant

/api-reference/openapi.json put /api/public/v1/participants/{participant_id}
Deprecated: use PATCH /api/public/v1/participants/{participant_id}.



# Get Study Type
Source: https://docs.userintuition.ai/api-reference/public-reference/get-study-type

/api-reference/openapi.json get /api/public/v1/reference/study-types/{slug}
Read one visible planning template by slug.



# List Interview Languages
Source: https://docs.userintuition.ai/api-reference/public-reference/list-interview-languages

/api-reference/openapi.json get /api/public/v1/reference/languages
List language codes accepted by public study creation.



# List Interview Modes
Source: https://docs.userintuition.ai/api-reference/public-reference/list-interview-modes

/api-reference/openapi.json get /api/public/v1/reference/modes
List the supported interview formats.



# List Study Types
Source: https://docs.userintuition.ai/api-reference/public-reference/list-study-types

/api-reference/openapi.json get /api/public/v1/reference/study-types
Page through visible planning templates without their internal prompts.



# List Voice Choices
Source: https://docs.userintuition.ai/api-reference/public-reference/list-voice-choices

/api-reference/openapi.json get /api/public/v1/reference/voices
List product voice settings and display names without implementation data.



# Search Research
Source: https://docs.userintuition.ai/api-reference/public-research-search/search-research

/api-reference/openapi.json post /api/public/v1/research/search/
Rank candidate content, then return canonical stored JSON.



# Create Study
Source: https://docs.userintuition.ai/api-reference/public-studies/create-study

/api-reference/openapi.json post /api/public/v1/studies/
Create a draft study. Customize its plan before inviting participants or launching recruitment.



# Create Study And Launch Panel
Source: https://docs.userintuition.ai/api-reference/public-studies/create-study-and-launch-panel

/api-reference/openapi.json post /api/public/v1/studies/create-and-launch-panel
Preview a Panel study without creating or fielding it. Paid launch requires
a persisted study and a current estimate from the two-step launch flow.



# Create Study With Participants
Source: https://docs.userintuition.ai/api-reference/public-studies/create-study-with-participants

/api-reference/openapi.json post /api/public/v1/studies/create-with-participants
Create a BYOP study and its participant invitations in one request.



# Customize Study Plan
Source: https://docs.userintuition.ai/api-reference/public-studies/customize-study-plan

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/customize-plan
Run one resumable turn through the same planning agent and tools used by
the dashboard's Customize Plan page.

The conversation id is stored on the study. Questions are returned to the
caller; completed plan markdown is persisted automatically.



# Delete Study
Source: https://docs.userintuition.ai/api-reference/public-studies/delete-study

/api-reference/openapi.json delete /api/public/v1/studies/{study_id}
Soft-delete a study and remove its linked research from normal reads.



# Generate Report
Source: https://docs.userintuition.ai/api-reference/public-studies/generate-report

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/report
Queue report analysis and return a job to poll; report.ready also fires on completion.



# Get Customize Study Job
Source: https://docs.userintuition.ai/api-reference/public-studies/get-customize-study-job

/api-reference/openapi.json get /api/public/v1/studies/{study_id}/customize-plan/jobs/{job_id}
Poll an asynchronous planning turn. A failed turn is not replayed automatically; inspect the saved study before retrying.



# Get Report
Source: https://docs.userintuition.ai/api-reference/public-studies/get-report

/api-reference/openapi.json get /api/public/v1/studies/{study_id}/report
Read the latest persisted report. Choose an overview, one section, or the full report with view.



# Get Study
Source: https://docs.userintuition.ai/api-reference/public-studies/get-study

/api-reference/openapi.json get /api/public/v1/studies/{study_id}
Retrieve the persisted study, including its current plan, status, and participant link.



# Launch Panel
Source: https://docs.userintuition.ai/api-reference/public-studies/launch-panel

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/launch-panel
Launch a paid panel for a Panel-type study (use ``dry_run`` for a cost estimate).



# List Studies
Source: https://docs.userintuition.ai/api-reference/public-studies/list-studies

/api-reference/openapi.json get /api/public/v1/studies/
List studies visible to this account with pagination and optional filters.



# Patch Study
Source: https://docs.userintuition.ai/api-reference/public-studies/patch-study

/api-reference/openapi.json patch /api/public/v1/studies/{study_id}
Partially update a study. Only provided fields change; screener_questions
and targeting_attributes are patched independently (one doesn't wipe the other).



# Pause Study
Source: https://docs.userintuition.ai/api-reference/public-studies/pause-study

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/pause
Pause a study. Panel surveys, target cycles, and reward holds are preserved.



# Queue Customize Study Plan
Source: https://docs.userintuition.ai/api-reference/public-studies/queue-customize-study-plan

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/customize-plan/jobs
Queue one planning turn and return immediately with a durable job ID.



# Resume Study
Source: https://docs.userintuition.ai/api-reference/public-studies/resume-study

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/resume
Resume a paused study. A preserved panel survey returns to fielding.



# Stop Study
Source: https://docs.userintuition.ai/api-reference/public-studies/stop-study

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/stop
Stop recruitment and prevent additional interviews through study links.



# List Targeting Attributes
Source: https://docs.userintuition.ai/api-reference/public-targeting/list-targeting-attributes

/api-reference/openapi.json get /api/public/v1/targeting-attributes/
Catalog of panel targeting attributes, searchable by name and filterable by category.



# Get Interview Usage
Source: https://docs.userintuition.ai/api-reference/public-usage/get-interview-usage

/api-reference/openapi.json get /api/public/v1/usage/interviews
Read bounded usage with the same resolved scope and totals as the dashboard.



# Create Webhook
Source: https://docs.userintuition.ai/api-reference/public-webhooks/create-webhook

/api-reference/openapi.json post /api/public/v1/webhooks/
Register a signed event webhook. The signing secret appears only in the creation response.



# Delete Webhook
Source: https://docs.userintuition.ai/api-reference/public-webhooks/delete-webhook

/api-reference/openapi.json delete /api/public/v1/webhooks/
Deprecated: use DELETE /api/public/v1/webhooks/{webhook_id}. The body-based form remains available during migration.



# Delete Webhook By Id
Source: https://docs.userintuition.ai/api-reference/public-webhooks/delete-webhook-by-id

/api-reference/openapi.json delete /api/public/v1/webhooks/{webhook_id}
Delete a registered webhook by ID.



# Reference catalogs and usage
Source: https://docs.userintuition.ai/api-reference/reference-and-usage

Read supported study settings and bounded interview usage from the public API.

The versioned public API provides read-only configuration catalogs. Each accepts the same API key or dashboard session as the other public endpoints:

| Endpoint | Returns |
| - | - |
| `GET /api/public/v1/reference/languages` | Accepted language codes, names, and native names, including `auto` |
| `GET /api/public/v1/reference/modes` | Supported interview formats |
| `GET /api/public/v1/reference/voices` | Public `male` and `female` voice values with display names |
| `GET /api/public/v1/reference/study-types` | Visible planning templates, paged and without internal prompts |
| `GET /api/public/v1/reference/study-types/{slug}` | One visible planning template |
| `GET /api/public/v1/usage/interviews` | Eligible interview counts, credits used, and resolved query scope |

Use the `voice` value when creating a study; the display name is informational. A study-type planning template describes a use case. Public study creation accepts `in-depth-interview`, `concept-test`, or `prototype-test` as the research method. Study-type responses omit internal planning prompts.

Usage accepts optional `start_date`, `end_date`, `cadence` (`daily`, `weekly`, or `monthly`), and `app_id`. Omitted dates resolve to an inclusive 30-day UTC range ending today. The response includes that resolved range and app in `scope`, so a zero total has a defined meaning. `total_interviews` counts eligible non-test interviews; `total_units` also includes non-refunded synthetic runs. Rows include bounded per-period counts and units.


# Sandbox quickstart
Source: https://docs.userintuition.ai/api-reference/staging-quickstart

Test the dashboard, API, and MCP workflows against staging with AI respondents.

The sandbox uses staging data and credentials. Study design, analysis, and report workflows use the staging services. Participant links and the public feedback page are disabled: opening one shows a sandbox message, and the interview API rejects participant entry. Use **Test with AI** to preview an interview.

| Surface | Sandbox URL |
| - | - |
| Dashboard | [sandbox.userintuition.ai](https://sandbox.userintuition.ai) |
| Public API | `https://staging.userintuition.ai` |
| MCP | `https://mcp.sandbox.userintuition.ai/mcp` |

Create a staging API key in the sandbox dashboard under **Manage Account → API Keys**. A production key does not authenticate against staging. For a local MCP client, set `BACKEND_URL=https://staging.userintuition.ai`, `APP_URL=https://sandbox.userintuition.ai`, and `USERINTUITION_API_KEY` to the staging key. For hosted MCP clients, connect to the sandbox MCP URL above and complete its OAuth flow.

## Design and test a study

Create a chat study with synthetic respondents. Send the research brief through Customize Plan, answer any returned `questions`, and review the saved plan. Wait for `provisioning_status` to become `provisioned`.

```sh theme={null}
export UI_API_KEY='ui_sk_...'
export UI_API_BASE='https://staging.userintuition.ai'

curl -fsS "$UI_API_BASE/api/public/v1/studies/" \
  -H "Authorization: Bearer $UI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Sandbox concept feedback","study_type":"in-depth-interview","recruiting_method":"synthetic_respondents","interview_format":"chat"}'

export UI_STUDY_ID='<id from create response>'
curl -fsS "$UI_API_BASE/api/public/v1/studies/$UI_STUDY_ID/customize-plan" \
  -H "Authorization: Bearer $UI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"message":"Interview early-stage founders about how they evaluate customer research tools and what evidence earns their trust."}'

curl -fsS "$UI_API_BASE/api/public/v1/studies/$UI_STUDY_ID" \
  -H "Authorization: Bearer $UI_API_KEY"
```

In the dashboard, open **Test Conversation → Test with AI**. This runs one test interview and lets you watch the AI respondent. Test calls are excluded from report sample counts. The public feedback link and **Test it yourself** are unavailable in the sandbox. AI tests are currently unavailable for studies with a concept link.

## Launch three synthetic responses

In **Ready to Launch**, choose **Launch Synthetic Study**. The sandbox starts a batch of **three** AI respondent interviews automatically. This is the minimum report sample; the three-response sandbox batch does not debit credits. Wait for all three to finish and pass interview quality checks. If any response is unusable, launch another synthetic batch from the study dashboard.

The synthetic launch control and Test with AI are dashboard workflows; they are not operations in the stable public API or MCP tool catalog. API and MCP clients can use the staging study design and reporting endpoints before and after those dashboard steps.

## Generate and retrieve the report

Once three usable synthetic responses are complete, open **Dashboard → Reports → Generate Report**, or use the public API (and its `generate_report` MCP equivalent):

```sh theme={null}
curl -fsS -X POST "$UI_API_BASE/api/public/v1/studies/$UI_STUDY_ID/report" \
  -H "Authorization: Bearer $UI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

export UI_JOB_ID='<job_id from response>'
curl -fsS "$UI_API_BASE/api/public/v1/studies/$UI_STUDY_ID/report/jobs/$UI_JOB_ID" \
  -H "Authorization: Bearer $UI_API_KEY"

curl -fsS "$UI_API_BASE/api/public/v1/studies/$UI_STUDY_ID/report?view=overview" \
  -H "Authorization: Bearer $UI_API_KEY"
```

With fewer than three usable synthetic responses, the sandbox rejects report generation with `insufficient_synthetic_responses`. Fetch `view=full` or a named section for detailed evidence. Keep the same idempotency key when retrying an uncertain report request. See the [API introduction](/api-reference/introduction) for job states and report views.


# Study lifecycle
Source: https://docs.userintuition.ai/api-reference/study-lifecycle

Pause, resume, or stop a study before editing an active panel.

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

```http theme={null}
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

```http theme={null}
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

```http theme={null}
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`:

```json theme={null}
{
  "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.


# Versioning and Deprecation
Source: https://docs.userintuition.ai/api-reference/versioning-and-deprecation

How public API changes are announced and migrated

The integration API is served under `/api/public/v1/`. The [OpenAPI specification](/api-reference/openapi.json) describes the current public contract; the [changelog](/api-reference/changelog) records additions and deprecations.

Within v1, we may add endpoints, optional response fields, optional request fields, and new event types. Clients should ignore response fields they do not recognize and handle webhook event types they have not subscribed to. We will not silently repurpose an existing field or remove an operation from v1.

When an operation is deprecated, we mark it in OpenAPI and document its replacement. The old operation remains available while integrations migrate. Any planned removal will be announced in the changelog with a migration path and a date before it takes effect. No removal date is set for the body-based webhook deletion route or participant PUT route.

For an API change that cannot preserve the v1 contract, we will introduce a new versioned route or explicitly announced migration. Security and incident response may require faster changes; those exceptions will be communicated through the changelog and support channels as soon as practical.


# Webhooks
Source: https://docs.userintuition.ai/api-reference/webhooks/overview

Subscribe to interview, study, and report events at your own HTTPS endpoint.

## Overview

Webhooks send an HTTP `POST` to your `hook_url` when subscribed events occur.
Choose `interview.completed`, `study.completed`, `report.ready`, `study.paused`,
`study.resumed`, `study.stopped`, participant lifecycle events, and/or
`study.quota_reached` in `event_types`. Omit `study_id` for an account-wide webhook, or include an owned
`study_id` to receive events for one study. The default subscription is
`interview.completed`.

Each subscribed event uses an envelope with `id`, `type`, `study_id`, and `data`.
For `interview.completed`, `data` has the **same public shape** returned by
[Get Interview](/api-reference/public-interviews/get-interview), including the
participant, quality, messages, recording links, and screener responses.

<Steps>
  <Step title="Register a webhook">
    Call [Create Webhook](/api-reference/public-webhooks/create-webhook) with the `hook_url`
    that should receive events, with optional `study_id` and `event_types`. The
    response includes a `signing_secret` — store it securely to verify signatures.
    Send an `Idempotency-Key` to recover the same response after a timeout without
    registering a second webhook. The same-key response can be replayed for 30
    days while the webhook and secret remain current; ordinary reads hide the
    secret.
  </Step>

  <Step title="Receive interview data">
    Your endpoint receives a signed `POST` when a subscribed event occurs. The
    interview payload is described below; study and report events use smaller data objects.
  </Step>

  <Step title="Stop receiving data">
    Delete the webhook by its `id` to stop further deliveries. The URL-based
    delete endpoint remains available for account-wide registrations.
  </Step>
</Steps>

<Note>
  List and get operations return webhook IDs, scopes, event types, and URLs without
  revealing stored signing secrets. Use secret rotation when the original secret
  is lost or needs replacement; the new secret appears only in the rotation response.
</Note>

## Participant lifecycle events

| Event | When it fires | Data |
| - | - | - |
| `participant.screened` | Successful saved screener submission | `participant_id`, `interview_id` |
| `participant.started` | VAPI in-progress callback matched to a saved interview and invite | `participant_id`, `interview_id` |
| `participant.quality_scored` | Completed interview with an initial public quality rating | `participant_id`, `interview_id`, `quality` |
| `study.quota_reached` | Active target cycle reaches its target | `cycle_id`, `completed_at` |

These events are opt-in. They add no email, transcript, screener answer, or
recording URL. Test interviews and panel fielding control records do not emit
participant lifecycle events. Rejected screeners do not emit `participant.screened`.
Start coverage is the VAPI callback path; it does not imply every chat or synthetic
runtime emits a start event. Quality events cover the initial completion rating,
not subsequent manual rescoring. Delivery ordering is not guaranteed.

Participant event IDs combine event type and persisted interview ID. Quota event
IDs include the target cycle ID. Deduplicate by envelope `id`, independently of
signature verification.

## Delivery behavior

| Property | Value |
| - | - |
| Method | `POST` |
| Content type | `application/json` |
| Trigger | The subscribed interview, study lifecycle, or report event |
| Timeout | 30 seconds — respond before then |
| Retries | Non-`2xx` responses and network failures retry with exponential backoff, up to 24 attempts |
| Expected response | Any `2xx` status. Acknowledge quickly and do heavy processing asynchronously |

Return `2xx` promptly and deduplicate using the stable event `id`: a timed-out
delivery may have reached your receiver before it is retried. Inspect
`/webhooks/{webhook_id}/deliveries` for status, timing, and coarse failure
reasons. The history does not store payloads.

## Payload

Subscribed events use `{id, type, study_id, data}`. For `interview.completed`, `data`
is the completed interview in the same public shape as `GET /interviews/{id}`.
The participant is nested under `data.participant`.

```json theme={null}
{
  "id": "a1b2c3d4-0000-0000-0000-000000000000",
  "type": "interview.completed",
  "study_id": "11111111-2222-3333-4444-555555555555",
  "data": {
  "id": "a1b2c3d4-0000-0000-0000-000000000000",
  "study_id": "11111111-2222-3333-4444-555555555555",
  "participant": {
    "id": "66666666-7777-8888-9999-000000000000",
    "email": "jordan@example.com"
  },
  "participant_source": "byop",
  "status": "completed",
  "quality": "Good",
  "ended_because": "participant_left",
  "started_at": "2026-06-30T14:02:11Z",
  "duration_seconds": 577,
  "messages": [
    { "id": "turn_0", "role": "moderator", "message": "Thanks for joining..." },
    { "id": "turn_1", "role": "participant", "message": "Happy to help..." }
  ],
  "total_message_segments": 2,
  "next_message_offset": null,
  "audio_recording_url": "https://.../recording.mp3",
  "video_recording_url": null,
  "screener_responses": [
    { "question": "What is your role?", "type": "single_select", "answer": "Product Manager" }
  ]
  }
}
```

`study.completed` is emitted when its active target cycle reaches its target. Each
newly persisted report has its own `report.ready` event ID.

```json theme={null}
{"id":"report-id","type":"report.ready","study_id":"study-id","data":{"report_id":"report-id"}}
```

The `study.completed` envelope has the same top-level fields, with a cycle ID
as `id` and `data.completed_at` instead of `data.report_id`. A test ping uses
`{"type":"webhook.test","id":"webhook-id"}` and contains no participant or
study data. Test pings use the same signing headers and appear in delivery history.

Public API pause, resume, and stop calls emit `study.paused`, `study.resumed`,
and `study.stopped` after the transition succeeds. Their `data` contains only
`study_id` and the resulting `fielding_status`. Each transition receives a new
event ID; deduplicate redeliveries by that ID. These lifecycle events currently
cover the public API routes, not dashboard transitions.

### Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Stable event identifier; the interview ID for `interview.completed` |
| `type` | string | Subscribed event type |
| `study_id` | string | Identifier of the study this event belongs to |
| `data` | object | Public event data; the following interview fields are inside `data` |
| `data.id` | string | Unique identifier of the interview |
| `participant` | object \| null | Who took the interview. `null` for anonymous panel interviews |
| `participant.id` | string | Participant identifier |
| `participant.email` | string \| null | Participant email, when available |
| `participant_source` | string | `byop`, `panel`, `external_panel`, `link`, or `unknown`. `participant` is null for anonymous sources |
| `status` | string | Final status of the interview, e.g. `completed` |
| `quality` | string \| null | Quality label: `Poor`, `Fair`, `Good`, or `Excellent` |
| `ended_because` | string \| null | Normalized reason: `completed`, `participant_left`, `time_limit`, `technical_error`, or `screened_out`; null when unknown |
| `started_at` | string (date-time) \| null | When the interview started |
| `duration_seconds` | integer \| null | Interview length in seconds |
| `messages` | array \| null | Spoken turns with `id`, `role` (`moderator` or `participant`), and `message`; system prompts and tool calls are excluded |
| `total_message_segments` | integer | Number of spoken turns in the webhook payload |
| `next_message_offset` | integer \| null | Always null in completion webhooks, which include the full spoken transcript |
| `audio_recording_url` | string \| null | Link to the audio recording, when available |
| `video_recording_url` | string \| null | Link to the video recording, for video-mode studies |
| `screener_responses` | array \| null | Participant's screener answers as `{ question, type, answer }` |

<Note>
  Anonymous panel interviews have no identifiable participant, so `participant` is
  `null` for them. Internal columns (transcripts of the raw call, internal IDs, and
  the like) are never included — the webhook delivers exactly the public interview
  shape.
</Note>

## Authentication

Every delivery is **signed** so you can verify it genuinely came from User Intuition.
When you register a webhook, the response includes a `signing_secret` (prefixed
`whsec_`, shown **once**). Each request carries two headers:

| Header | Description |
| - | - |
| `X-UI-Timestamp` | Unix timestamp (seconds) when the request was signed |
| `X-UI-Signature` | `sha256=<hex>` — HMAC-SHA256 of `"<X-UI-Timestamp>.<raw body>"`, keyed with your `signing_secret` |

Copyable [TypeScript and Python SDK companion helpers](https://github.com/user-intuition/examples/blob/main/docs/sdk-helpers.md)
verify raw-body signatures and poll existing jobs with bounded waits. They live
outside Fern-generated SDK code, so regeneration cannot overwrite them.

### Verifying a signature

Recompute the HMAC over `"<timestamp>.<raw request body>"` using your stored
`signing_secret` and compare it to `X-UI-Signature` in constant time. Use the
**raw request body bytes** — do not re-serialize the parsed JSON, or the signature
won't match.

```python theme={null}
import hmac, hashlib, time

def verify(request_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    # Reject stale signatures; separately deduplicate event IDs within the window.
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "sha256=" + hmac.new(
        secret.encode(), f"{timestamp}.".encode() + request_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
```

<Steps>
  <Step title="Verify the signature">
    Reject any request whose `X-UI-Signature` doesn't match your recomputed HMAC.
  </Step>

  <Step title="Check the timestamp">
    Reject requests with an `X-UI-Timestamp` outside a small window (e.g. 5 minutes)
    to reject stale signatures. Separately deduplicate verified event IDs.
  </Step>

  <Step title="Use HTTPS">
    Always register an `https://` URL so the payload is encrypted in transit.
  </Step>
</Steps>

<Warning>
  Store the `signing_secret` securely — it is shown only once, at creation. If you
  lose it or need to rotate it, call the secret-rotation endpoint and update your
  receiver with the new secret. Legacy webhooks created before signing was introduced are delivered
  **without** signature headers.
</Warning>

## Managing webhooks

Use `GET /api/public/v1/webhooks/` to find webhook IDs and
`GET /api/public/v1/webhooks/{webhook_id}` to inspect one registration. Neither
response includes its stored signing secret. Use
`POST /api/public/v1/webhooks/{webhook_id}/rotate-secret` to replace a lost or
compromised secret; update the receiver with the new one immediately.

Use `POST /api/public/v1/webhooks/{webhook_id}/test` to send a signed, data-free
test event. Check `GET /api/public/v1/webhooks/{webhook_id}/deliveries` for recent
attempts (`page` and `page_size` are bounded). Delete by ID with
`DELETE /api/public/v1/webhooks/{webhook_id}`. Repeating the delete returns 404.
The older `DELETE /api/public/v1/webhooks/` operation accepts a JSON body and is deprecated. New integrations should use the ID route.

<CardGroup>
  <Card title="Create Webhook" icon="webhook" href="/api-reference/public-webhooks/create-webhook">
    Register a URL, optional study scope, and event subscriptions.
  </Card>

  <Card title="Delete Webhook" icon="trash" href="/api-reference/public-webhooks/delete-webhook-by-id">
    Stop sending completed interviews to a registered webhook ID.
  </Card>
</CardGroup>


# Command Reference
Source: https://docs.userintuition.ai/cli/commands

OAuth login, API-key management, discovery, and direct tool invocation from the userintuition-mcp CLI.

The CLI supports authentication, API-key management, tool discovery, and direct tool invocation. The older `call <tool>` form remains an alias for compatibility.

```
userintuition-mcp <command> [args...]
```

| Subcommand | Purpose |
| - | - |
| `login [--scopes read,write,...]` | Sign in through browser OAuth with PKCE. |
| `auth status` | Show whether OAuth and a saved API key are configured. |
| `auth logout` | Remove locally saved OAuth and API-key credentials. |
| `api-key create [--name <name>] [--scopes read,write,...] [--spend-cap-usd <amount>]` | Create an organization API key and save it locally. |
| `api-key list` | List active organization API keys (never raw secrets). |
| `api-key revoke <id>` | Revoke an organization API key. |
| `list` | Print every tool name on stdout, one per line. |
| `describe <tool> [--json]` | Print a tool's metadata and schemas for humans or automation. |
| `<tool> [flags]` | Run a tool and write its response to stdout. |
| `call <tool> [flags]` | Compatibility alias for direct tool invocation. |
| `help` | Print usage. Also matched by `--help` or `-h`. With no arguments, the binary starts its stdio MCP transport. |

***

## Authentication and API keys

```bash theme={null}
userintuition-mcp login
userintuition-mcp auth status
userintuition-mcp api-key create --name "My laptop"
userintuition-mcp api-key list
userintuition-mcp api-key revoke <key_id>
userintuition-mcp auth logout
```

`login` uses the hosted MCP OAuth service and opens a temporary callback only on `127.0.0.1`. `api-key create` requires that OAuth login, prints the raw key once, and saves it for subsequent CLI and stdio MCP calls.

Login requests `read,write` by default. To authorize paid hosted tools, run `login --scopes read,write,panel:launch,rewards:send` and approve the requested access in the browser. You can grant only the paid scope you need.

The CLI creates a read-only key by default. For a research agent that also writes, use `--scopes read,write`. Paid scopes require `write` and a positive lifetime cap, for example `--scopes read,write,panel:launch --spend-cap-usd 100`.

***

## `list`

```bash theme={null}
userintuition-mcp list
```

Writes one tool name per line to stdout. Sorted alphabetically. Pipe into other shell tools:

```bash theme={null}
# Count tools
userintuition-mcp list | wc -l

# Grep for a capability
userintuition-mcp list | grep ^create_
```

No backend call is made — `list` works without an API key.

***

## `describe <tool> [--json]`

```bash theme={null}
userintuition-mcp describe launch_panel
```

The human-readable form prints:

* The tool's title (one line)
* Its full description (the same text MCP clients see)
* Every input flag (`--name`, optional flag suffix, type, enum choices, default, and description)

Use this to discover argument names and types without leaving the terminal. Like `list`, it makes no backend call.

Use `--json` before or after the tool name for a stable machine-readable object:

```bash theme={null}
userintuition-mcp describe launch_panel --json | jq .inputSchema
userintuition-mcp describe --json launch_panel
```

The object includes `name`, `title`, `description`, `inputSchema`, `outputSchema`, and `annotations`. Schemas are JSON Schema, so agents and scripts can inspect types, enum values, defaults, and required fields without parsing terminal prose.

If the tool name is unknown, prints `Unknown tool: <name>` to stderr and exits with code `2`.

***

## `<tool> [flags]`

```bash theme={null}
userintuition-mcp <tool> [--key value ...]
userintuition-mcp <tool> --input-json '<json>'
userintuition-mcp <tool> --input-json @<file>
```

Runs the tool. Output is the tool's text response written to stdout — typically JSON, the same payload an MCP client would receive. Tool errors remain JSON on stdout, but return a non-zero status so shells and agents cannot mistake them for success.

### Argument forms

You can pass inputs three ways. They behave identically once parsed.

<Tabs>
  <Tab title="Inline flags">
    `--key value` pairs. Values are JSON-parsed when possible, so the right type lands in the schema:

    ```bash theme={null}
    userintuition-mcp launch_panel \
      --study_id ast_123 \
      --target 25 \
      --incident_rate 50 \
      --country_code US \
      --dry_run true
    ```

    * `--target 25` → number `25`
    * `--dry_run true` → boolean `true`
    * `--quality '["Excellent"]'` (on `list_interviews`) → array
    * `--country_code US` → string (JSON parse fails, falls back to string)

    Flags with no value (e.g. `--verbose`) are treated as boolean `true`.
  </Tab>

  <Tab title="Inline JSON">
    For deeply nested inputs:

    <Warning>
      `screener_questions` REPLACES the entire list, and the study may already carry
      panel and custom questions you can't see. Read first, then send the **complete
      merged list** — existing questions plus your additions:

      ```bash theme={null}
      userintuition-mcp get_study --study_id ast_123
      ```
    </Warning>

    ```bash theme={null}
    userintuition-mcp create_participants --input-json '{
      "study_id": "ast_123",
      "participants": [
        {"email": "participant@example.com", "silent": true}
      ]
    }'
    ```

    When `--input-json` is provided, all other `--flag` arguments are ignored.
  </Tab>

  <Tab title="JSON file">
    Prefix the path with `@`:

    ```bash theme={null}
    userintuition-mcp create_study --input-json @study.json
    ```

    Best for inputs that live in source control alongside the script that uses them.
  </Tab>
</Tabs>

### Input validation

Inputs are validated against the tool's Zod schema **before** any backend call. Missing required fields, wrong types, and enum mismatches all fail fast:

```bash theme={null}
$ userintuition-mcp launch_panel --study_id x --target notanumber
Invalid input for launch_panel: [
  {
    "code": "invalid_type",
    "expected": "number",
    "received": "string",
    "path": ["target"],
    ...
$ echo $?
2
```

### Exit codes

| Code | Meaning |
| - | - |
| `0` | Tool completed successfully and its response is on stdout. |
| `2` | CLI usage error — unknown subcommand, unknown tool, or input failed schema validation. |
| `1` | The tool returned an error, or authentication, network, or an unexpected runtime failure occurred. Tool error JSON remains on stdout. |

### Output and pipes

Tool responses go to **stdout**. Diagnostic logs (handler errors, stack traces) go to **stderr**. This separation means you can safely pipe into `jq` without log noise:

```bash theme={null}
userintuition-mcp list_interviews --study_id ast_123 --page_size 1 | jq .
```

Backend errors round-trip as JSON on stdout, so a pipeline never silently drops them:

```bash theme={null}
$ userintuition-mcp get_study --study_id bogus | jq .
{"error": "Study not found"}
$ echo ${PIPESTATUS[0]}
1
```

Recoverable API failures may include typed fields in addition to the backward-compatible `error` string:

```json theme={null}
{
  "error": "Service unavailable",
  "code": "service_unavailable",
  "http_status": 503,
  "request_id": "req_123",
  "retry_after": "30",
  "outcome": "unknown",
  "recovery_action": "retrieve_current_state_before_retry"
}
```

For consequential writes such as a paid Panel launch, a timeout or server failure means the outcome is unknown. Retrieve the current study state before deciding whether another write is safe; a request ID is diagnostic context, not an idempotency guarantee.

***

## `help`

```bash theme={null}
userintuition-mcp help
userintuition-mcp --help
userintuition-mcp -h
```

All three forms print the same usage summary plus the full tool list. Makes no backend call.

***

## Environment

| Variable | Required | Description |
| - | - | - |
| `USERINTUITION_API_KEY` | No | API key override, prefixed with `ui_sk_`. Takes precedence over saved credentials. |
| `USERINTUITION_CONFIG_DIR` | No | Override the directory containing `credentials.json`. |
| `USERINTUITION_OAUTH_ISSUER_URL` | No | Override the hosted OAuth issuer. Defaults to `https://mcp.userintuition.ai`. |
| `BACKEND_URL` | No | Override the backend API URL. Defaults to `https://api.userintuition.ai`. |
| `REQUEST_TIMEOUT_MS` | No | Timeout for ordinary API operations. Defaults to 30,000 ms. |
| `LONG_OPERATION_TIMEOUT_MS` | No | Timeout for long-running operations such as customization and report generation. Defaults to 120,000 ms. |

***

## Tool inventory

The CLI exposes 49 direct tool commands. The MCP-only `review_study` app is available in supported hosts. For full descriptions grouped by capability, browse the [MCP tool reference](/mcp-server/tools/studies) — shared names, schemas, validation, and responses are identical.

The quickest way to see what's available locally:

```bash theme={null}
userintuition-mcp list | less
userintuition-mcp describe <name> --json
```


# User Intuition CLI
Source: https://docs.userintuition.ai/cli/overview

Call the same tools as the MCP server from a shell — 35 commands for studies, recruitment, interviews, and analysis, ready for scripts, CI, and ad-hoc debugging.

The User Intuition CLI is the **same binary as the MCP server**, invoked as a plain command-line tool. Its 49 direct commands include `create_study`, `list_studies`, `launch_panel`, `generate_report`, `search_research`, and `answer_research`. The `review_study` app is MCP-only. No MCP client is required for direct commands.

## When to reach for the CLI

* **Shell scripts and CI jobs.** Pipe study results into `jq`, write a cost-gate before launching a Panel study, automate cleanup of test studies.
* **Cron and scheduled work.** Run nightly status sweeps, refresh cached reports, alert on long-running studies.
* **Ad-hoc debugging.** Pin down whether a problem is the tool, the backend, or your MCP client — by isolating the call from the agent.
* **Onboarding a teammate.** A browser login and one `userintuition-mcp list_studies` command are enough to get started.

## When to use the MCP server instead

If an AI agent should *choose* the tool and fill in arguments (Claude, ChatGPT, Cursor), use the [MCP server](/mcp-server/overview). The CLI assumes you already know which tool and which arguments.

## What you get

The CLI ships with the Node build of the MCP server (`@userintuition-ai/mcp` on npm). It uses the same OAuth service, API keys, input validation, public API endpoints, and response shapes — the only thing that changes is the transport.

<Note>
  The CLI is **Node-only**. For Python integrations, use the [REST API](/api-reference/introduction).
</Note>

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/cli/quickstart">
    Install the binary and make your first call in under two minutes.
  </Card>

  <Card title="Command reference" icon="terminal" href="/cli/commands">
    Every subcommand, every flag, with examples.
  </Card>

  <Card title="Recipes" icon="book" href="/cli/recipes">
    Practical patterns — CI cost gates, lifecycle scripts, batch operations.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/cli/troubleshooting">
    Auth errors, missing binaries, common pitfalls.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.userintuition.ai/cli/quickstart

Install the User Intuition CLI and make your first call in under two minutes.

## 1. Install

<Tabs>
  <Tab title="One-shot (npx)">
    No install — runs the latest published version on demand:

    ```bash theme={null}
    npx -y @userintuition-ai/mcp list
    ```

    Slower per-invocation (npm fetches metadata). Best for occasional use.
  </Tab>

  <Tab title="Global">
    ```bash theme={null}
    npm install -g @userintuition-ai/mcp
    userintuition-mcp list
    ```

    Installs once, then `userintuition-mcp` is on your `PATH`. Best for daily use.
  </Tab>

  <Tab title="Project-local">
    ```bash theme={null}
    npm install --save-dev @userintuition-ai/mcp
    npx userintuition-mcp list
    ```

    Pinned to your project's `package.json` and lockfile. Best for CI and reproducible scripts.
  </Tab>
</Tabs>

## 2. Sign in

```bash theme={null}
userintuition-mcp login
```

The CLI opens your browser, completes OAuth with PKCE on a temporary loopback callback, and saves the refreshable login in a private local credentials file.

```bash theme={null}
userintuition-mcp auth status
```

<Note>
  Browser OAuth is best for interactive use. Existing `USERINTUITION_API_KEY` environments continue to work and take precedence over saved credentials.
</Note>

## 3. Verify the connection

```bash theme={null}
userintuition-mcp list_studies
```

A JSON object with a `studies` array (possibly empty) confirms the CLI, your login, and network egress to `api.userintuition.ai` are all working.

## 4. Create an API key for stdio or CI

After OAuth login, the CLI can create and save an organization-scoped key:

```bash theme={null}
userintuition-mcp api-key create --name "My laptop"
```

The raw `ui_sk_...` key is returned once and saved locally with file mode `0600`. Subsequent CLI calls and local stdio MCP sessions use it automatically. For CI, copy it into the `USERINTUITION_API_KEY` secret in your CI provider rather than copying the local credentials file.

This key has read access. Add `--scopes read,write` when the agent needs to create or change research. Paid actions require their own scopes and a `--spend-cap-usd` value.

## 5. First real call

Estimate the cost of fielding a panel for one of your studies without spending anything:

```bash theme={null}
userintuition-mcp estimate_panel \
  --study_id <your_study_id> \
  --target 25 \
  --incident_rate 50 \
  --country_code US
```

You should see the cost and timeline estimate on stdout — no panel is provisioned and nothing is charged. Review and explicitly approve the complete study plan and estimate before changing `--dry_run` to `false`.

## Next steps

<CardGroup>
  <Card title="Command reference" icon="terminal" href="/cli/commands">
    Full reference for `list`, `describe`, `call`, and every flag.
  </Card>

  <Card title="Recipes" icon="book" href="/cli/recipes">
    CI cost gates, lifecycle scripts, batch operations.
  </Card>
</CardGroup>


# Recipes
Source: https://docs.userintuition.ai/cli/recipes

Practical patterns for using the User Intuition CLI in scripts, CI, and day-to-day automation.

Concrete patterns you can copy and adapt. Each one assumes `userintuition-mcp` is on your `PATH` and you have either run `userintuition-mcp login` or set `USERINTUITION_API_KEY`.

***

## Cost gate in CI

Refuse to merge a PR if its planned panel recruit would exceed a budget. `estimate_panel` returns the current cost and heuristic timeline without launching or charging anything:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

estimate=$(userintuition-mcp estimate_panel \
  --study_id "$STUDY_ID" \
  --target 25 \
  --incident_rate 50 \
  --country_code US)

cost_usd=$(jq -r '.estimated_total_cost_usd' <<<"$estimate")

budget_usd=750

if (( $(echo "$cost_usd > $budget_usd" | bc -l) )); then
  echo "::error::Panel would cost \$$cost_usd — exceeds \$$budget_usd cap" >&2
  exit 1
fi

echo "Panel estimate: \$$cost_usd ✓"
```

***

## Panel lifecycle script

Field a panel for an existing Panel study, poll until the target number of interviews lands (or 24 hours elapse), then generate and export the report:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

study_id="$1"
target=25

# 1. Launch (dry-run first if you haven't previewed the cost — see the CI gate above)
userintuition-mcp launch_panel \
  --study_id "$study_id" \
  --target "$target" \
  --incident_rate 50 \
  --country_code US \
  --dry_run false
echo "Panel launched for $study_id"

# 2. Poll — list_interviews returns a total_count envelope, so page_size 1 is
#    enough. Filter to completed interviews: the unfiltered total also counts
#    in-progress and failed sessions.
deadline=$(( $(date +%s) + 86400 ))
while (( $(date +%s) < deadline )); do
  n=$(userintuition-mcp list_interviews \
      --study_id "$study_id" --status completed --page_size 1 \
      | jq -r '.total_count // 0')
  echo "  completed=$n/$target"
  (( n >= target )) && break
  sleep 600
done

# 3. Analyze and export
userintuition-mcp generate_report --study_id "$study_id" > /dev/null
userintuition-mcp get_study_report --study_id "$study_id" \
  > "report-$study_id.json"
echo "Saved: report-$study_id.json"
```

***

## Daily standup digest

A cron job that writes per-study interview counts into a Slack-ready text file every morning. `list_interviews` with `page_size: 1` is the cheap way to count — the envelope's `total_count` covers the whole study, not just the page:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

userintuition-mcp list_studies --page_size 50 \
  | jq -r '.studies[] | "\(.id)\t\(.name)"' \
  | while IFS=$'\t' read -r id name; do
      n=$(userintuition-mcp list_interviews \
          --study_id "$id" --status completed --page_size 1 \
          | jq -r '.total_count // 0')
      echo "  • $name — $n completed interviews"
    done > /tmp/studies-digest.txt

# Then post via your Slack tool of choice
cat /tmp/studies-digest.txt
```

Schedule with cron:

```
0 9 * * 1-5 USERINTUITION_API_KEY=ui_sk_... /usr/local/bin/digest.sh
```

***

## Bulk cleanup of test studies

Delete every study whose name starts with `test_`:

```bash theme={null}
userintuition-mcp list_studies --page_size 100 \
  | jq -r '.studies[] | select(.name | startswith("test_")) | .id' \
  | while read -r id; do
      echo "Deleting $id"
      userintuition-mcp delete_study --study_id "$id"
    done
```

<Warning>
  `delete_study` is destructive. Sanity-check the `jq` filter against `list_studies` output before running the loop.
</Warning>

***

## Review low-quality interviews

List interviews classified as `Poor`, then fetch each full record for review:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

study_id="$1"

userintuition-mcp list_interviews \
  --study_id "$study_id" --quality '["Poor"]' --page_size 100 \
  | jq -r '.interviews[].id' \
  | while read -r id; do
      userintuition-mcp get_interview --interview_id "$id" > "interview-$id.json"
      echo "Saved interview-$id.json"
    done
```

<Warning>
  `delete_interview --interview_id <id>` is available after review, but deletion is destructive. The public API does not expose a reversible hide operation.
</Warning>

***

## Discovering tools by capability

The CLI ships every tool the MCP server has. To find one for a job:

```bash theme={null}
# Anything that creates something
userintuition-mcp list | grep ^create_

# Anything related to interviews
userintuition-mcp list | grep interview

# Inspect a candidate
userintuition-mcp describe create_participants
```

This is often faster than scrolling the [tool reference](/mcp-server/tools/studies).

***

## Patterns to avoid

* **Don't hard-code IDs.** Always derive them from a fresh `list_*` call. IDs from a teammate's account won't resolve.
* **Don't omit `--dry_run true` when iterating on a panel launch.** Real recruiting starts the moment you flip it to `false`.
* **Don't count by page.** Read `list_interviews.total_count` instead of counting one page's `interviews` array.
* **Don't parse stdout in shell with `grep`/`sed`.** Use `jq` — responses are JSON and may add fields between versions.
* **Don't share your `USERINTUITION_API_KEY` in CI logs.** Mask it as a secret. Anyone with the key can spend panel budget on your account.


# Troubleshooting
Source: https://docs.userintuition.ai/cli/troubleshooting

Fixes for the most common CLI errors — missing binaries, auth failures, validation errors, and network problems.

## `command not found: userintuition-mcp`

The binary isn't on your `PATH`. Pick the install style you used and verify:

<Tabs>
  <Tab title="Global install">
    ```bash theme={null}
    npm install -g @userintuition-ai/mcp
    which userintuition-mcp     # should print a path
    ```

    If `which` is empty, your global `npm` bin directory isn't on `PATH`. Run `npm config get prefix` and add `<prefix>/bin` to `PATH`.
  </Tab>

  <Tab title="Project-local install">
    ```bash theme={null}
    npm install --save-dev @userintuition-ai/mcp
    npx userintuition-mcp list  # use `npx` — node_modules/.bin/ isn't on PATH by default
    ```
  </Tab>

  <Tab title="One-shot">
    ```bash theme={null}
    npx -y @userintuition-ai/mcp list
    ```

    No install needed — npm downloads on demand.
  </Tab>

  <Tab title="Local checkout (contributors)">
    A package's own `bin` does **not** appear in its own `node_modules/.bin/`. Use one of:

    ```bash theme={null}
    # Symlink globally
    cd userintuition-mcpserver-ts && npm link
    userintuition-mcp list

    # Or run dist directly
    node ./dist/index.js list

    # Or run source via tsx (no build step)
    npx tsx ./src/index.ts list
    ```
  </Tab>
</Tabs>

***

## `No authentication found`

```
No authentication found. Run `userintuition-mcp login` …
```

The CLI could not find a saved OAuth login, a saved API key, or `USERINTUITION_API_KEY`. Start with:

```bash theme={null}
userintuition-mcp login
userintuition-mcp auth status
```

For non-interactive CI, set `USERINTUITION_API_KEY` as a secret. Common causes:

1. **Not exported in the current shell.**
   ```bash theme={null}
   export USERINTUITION_API_KEY=ui_sk_...
   userintuition-mcp list_studies
   ```
2. **Set in `~/.zshrc` but the shell didn't reload.** Open a new terminal or `source ~/.zshrc`.
3. **Running under `sudo` or a different user.** `sudo` strips most env vars — prefix the call: `sudo USERINTUITION_API_KEY=ui_sk_... userintuition-mcp call …`
4. **CI secret not wired.** Confirm the variable is set as a secret in your CI provider *and* exposed to the step that runs the CLI.

***

## `401 Unauthorized` from the backend

The key is read but the backend rejected it.

* **Revoked or rotated.** Run `userintuition-mcp login`, then `userintuition-mcp api-key create --name "Replacement"`, and update any CI secret.
* **Wrong environment.** Production keys (`ui_sk_live_...`) don't work against staging and vice versa. Check `BACKEND_URL` if you've overridden it.
* **Typo / wrapping whitespace.** `echo "$USERINTUITION_API_KEY" | wc -c` — should match expected key length (no trailing newline issues).

***

## `Invalid input for <tool>: …`

Zod schema validation failed *before* the CLI tried to call the backend. The error message names the offending field.

```bash theme={null}
$ userintuition-mcp launch_panel --study_id x --target notanumber
Invalid input for launch_panel: [
  {
    "code": "invalid_type",
    "expected": "number",
    "received": "string",
    "path": ["target"],
    ...
```

Re-read the schema:

```bash theme={null}
userintuition-mcp describe launch_panel
```

Common variants:

* **Missing required flag.** Add it.
* **String where a number/boolean/array is expected.** Make sure the value is JSON-parseable: `--target 25` not `--target "twenty-five"`; `--include '["transcript"]'` not `--include transcript`.
* **Nested objects.** Use `--input-json` rather than flags.

***

## Tool call hangs or times out

Network egress to `api.userintuition.ai` may be blocked or slow.

```bash theme={null}
curl -sS -w "%{http_code}\n" -o /dev/null https://api.userintuition.ai/health
# Expect 200
```

If the curl works but the CLI hangs, the tool may legitimately be long-running (e.g. `generate_report`, which takes 30–120 seconds). Check the equivalent operation in the dashboard — if it normally takes minutes, the CLI behaves the same way.

If you're on a corporate network, confirm a proxy hasn't TLS-intercepted the connection. Node respects `HTTPS_PROXY`; set it explicitly if needed.

***

## `EACCES` / permission denied on the binary

After a manual `tsc` build, `dist/index.js` may not be executable.

```bash theme={null}
chmod +x ./dist/index.js
```

`npm publish` handles this automatically — only a concern for local builds.

***

## Output isn't valid JSON

The CLI writes the tool's text response verbatim to stdout. Most tools return JSON; a few (e.g. PowerPoint generation) return a URL or status string. Use `userintuition-mcp describe <tool>` to confirm the response shape, and check whether the tool returned an `{"error": …}` envelope on a logical failure.

If stderr contents are being mixed into your pipe, redirect them out: `userintuition-mcp list_studies 2>/dev/null | jq .`.

***

## Still stuck?

Run the equivalent MCP call through the official inspector to isolate whether the issue is the CLI or the underlying tool:

```bash theme={null}
npx @modelcontextprotocol/inspector npx -y @userintuition-ai/mcp
```

If it reproduces there, the bug is in the tool or the backend — open an issue at [github.com/userintuition](https://github.com/userintuition). If it only reproduces in the CLI, please include the exact command, your CLI version (`npm ls -g @userintuition-ai/mcp`), and Node version (`node --version`).


# Create Study
Source: https://docs.userintuition.ai/creating-a-study/create-study

Pick the study type that matches what you want to learn. There are three, and all three follow the same setup process.

Pick the study type that matches what you want to learn. There are three, and all three follow the same setup process — what differs is whether participants react to something, and what.

**In-depth Interview** is selected by default.

***

## The three study types

| Study type | Best for | What participants do |
| - | - | - |
| **In-depth Interview** | Understanding experiences, motivations, and decisions | Talk through what they did and why |
| **Concept Test** | Reactions to an image or video | React to your concept and explain the reaction |
| **Prototype Test** | Watching people use something | Work through your prototype while narrating |

### In-depth Interview

**No stimulus required — just a conversation.** Use this when you want to learn from people's lived experience. Charles guides a focused discussion about what they did, why, and what they'd change.

Reach for it when you're doing discovery, digging into a decision moment, exploring before you commit to a direction, or hunting for unmet needs.

### Concept Test

**You have something to show.** An ad, a landing-page mockup, packaging, a feature explainer. Add the image or video, and Charles walks participants through reacting to it.

Reach for it for creative testing, messaging validation, packaging or pricing-page reactions, or A/B-style concept comparison.

### Prototype Test

**You have something to try.** A prototype, a clickable mockup, or a live site. Share the link and participants work through it while narrating their thinking.

Reach for it to validate a flow before you build it, find where people get stuck, compare an old design against a new one, or run a pre-launch usability check.

<Card title="Study types in depth" icon="layer-group" href="/study-types/overview">
  What each study type does, how to set it up, and what you get back.
</Card>

***

## How to select your study type

1. Review the three cards on screen
2. Click the one that matches what you're trying to learn
3. The selected card is highlighted with a dark background
4. Click **Save & Continue**

> **Not sure?** Start with **In-depth Interview**. Charles will help shape the plan once you describe what you want to learn, and you can come back and change it.

***

## What happens next

You'll move to [Step 2: Customize Plan](/creating-a-study/customize-plan), where you work with Charles to tailor the research plan to your context.

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I change my study type after selecting it?">
    Yes. Click **Back** at any point during setup to return here and pick a different one.
  </Accordion>

  <Accordion title="Do different study types cost different amounts?">
    No. Cost depends on the interview format — chat, voice, or video — not the study type. See [Billing and credits](/resources/billing-and-credits).
  </Accordion>

  <Accordion title="What if my research spans more than one study type?">
    Pick the one that matches your primary objective. During Step 2, tell Charles about your other objectives and he'll work them into the plan.
  </Accordion>

  <Accordion title="Can I show an image in an in-depth interview?">
    Yes. In-depth interviews accept concept images too, so a conversation can turn into a concept test partway through if that's what the moment calls for.
  </Accordion>
</AccordionGroup>


# Customize Plan
Source: https://docs.userintuition.ai/creating-a-study/customize-plan

Work with Charles, our AI researcher, to design a research plan tailored to your specific context and objectives. This step ensures your study asks the right questions.

Work with Charles, our AI researcher, to design a research plan tailored to your specific context and objectives. This step ensures your study asks the right questions to get the insights you need.

***

## Overview

In this step, you'll provide context about your research goals so Charles can create a customized learning plan. The more context you provide, the more tailored and effective your study will be.

> **Why this matters:** A generic NPS study asks generic questions. A customized NPS study for your specific situation—your company, your recent changes, your hypotheses—delivers actionable insights you can act on immediately.

***

## Chatting with Charles

You work with Charles in a chat interface — type your context, and the research plan builds in the panel on the right as you go. You can keep refining it by continuing the conversation.

***

## What Charles Will Ask

Charles will ask clarifying questions to understand your research context. The specific questions depend on your study type and what you share, but typically include:

### Context Questions

* **Company/Product:** What company or product is this research for?
* **Situation:** What's happening that prompted this research?
* **Hypotheses:** What do you think might be causing the issue or driving the behavior?

### Scope Questions

* **Target participants:** Which customer segments should we prioritize?
* **Time period:** What timeframe are we focusing on?
* **Channels/touchpoints:** Are there specific areas of the experience to focus on?

### Objective Questions

* **Key question:** What's the one question that must be answered for this study to be successful?
* **Decisions:** What decisions will this research inform?
* **Stakeholders:** Who will be using these insights?

***

## Example Conversation

Here's an example of how a conversation with Charles might go for an NPS study:

**You:**

> "We're Nike Store and our NPS scores have dropped significantly over the past few months. We want to understand why our customers are less satisfied and what's driving the decline."

**Charles:**

> "Before I draft the Learning Plan, a few quick clarifications will sharpen the objectives and conversation flow:
>
> 1. **Scope of decline:** Which channels and geographies are included in the NPS drop (Nike.com, Nike App, SNKRS, owned retail, outlet, third-party marketplaces; US only or broader)? Over what exact period?
>
> 2. **Hypothesis inventory:** Beyond general dissatisfaction, do you have internal theories—pricing changes, inventory issues, shipping delays, recent app updates, return policy changes?
>
> 3. **Target participants:** Which segments should we prioritize, and which respondent roles? Do you want a balanced mix of detractors, passives, and promoters?"

***

## The Research Plan Panel

As you provide context, Charles generates a research plan that appears in the right panel. This plan includes:

| Section | Description |
| - | - |
| **Objective** | What the study aims to accomplish |
| **Background** | Context about your company and situation |
| **Learning Goals** | Answerable research questions, with the evidence needed beneath each goal |
| **Conversation Flow** | Section-by-section outline with time estimates |
| **Study-Specific Rules** | Instructions that shape how the moderator runs the conversation |

***

## Editing the Research Plan

You have two ways to refine the research plan:

### Option 1: Continue the Conversation

Keep chatting with Charles to request changes. For example:

* "Can you add questions about our recent pricing changes?"
* "I'd like to focus more on the mobile app experience"
* "Remove the section about competitive alternatives"

Charles will update the plan based on your feedback.

> **Screener questions:** You can ask Charles to add screener questions at any time—for example, "add a screener for senior product managers." He'll prefer standard panel qualifications where they fit.

### Option 2: Edit Directly in Step 3

You can also edit the research plan directly in the next step (Review Goals). This is useful for making small text changes or fine-tuning specific questions.

***

## Minimum context required

While you can proceed without extensive customization, Charles needs some basic context to create an effective study:

* **Company/Product name:** So the interviewer knows who they're representing
* **Core research question:** What you're trying to learn

> **Tip:** If you're confident the default research plan meets your needs, you can type something like "Use your best judgment" to proceed with the standard template. However, providing context typically results in more actionable insights.

***

## Proceeding to the Next Step

Once you're satisfied with the research plan showing in the right panel:

1. Review the plan to ensure it addresses your key questions
2. Click **Save & Continue** to proceed to [Step 3: Review Goals](/creating-a-study/review-goals)

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I skip the conversation with Charles?">
    You need to provide some basic context (company name and research question), but you can keep it brief if the default plan meets your needs.
  </Accordion>

  <Accordion title="What if Charles asks a question I don't know the answer to?">
    That's okay! Just tell Charles what you do know. He'll work with whatever context you can provide.
  </Accordion>

  <Accordion title="Can I come back and change the plan later?">
    Yes. You can click **Back** to return to this step at any point, or edit the plan directly in Step 3.
  </Accordion>

  <Accordion title="How long does this step typically take?">
    Most users complete this step in 5-10 minutes. Complex research needs may take longer.
  </Accordion>
</AccordionGroup>


# Creating a Study Overview
Source: https://docs.userintuition.ai/creating-a-study/overview

How to create a research study in User Intuition — six setup steps, then inviting participants from your dashboard.

Setting up a study takes about 10–15 minutes across six steps. A seventh — inviting participants — happens on your dashboard once the study is live.

***

## The Setup Process

| Step | Name | What You'll Do |
| - | - | - |
| 1 | [Create Study](/creating-a-study/create-study) | Pick one of the three study types |
| 2 | [Customize Plan](/creating-a-study/customize-plan) | Work with Charles to tailor the research plan |
| 3 | [Review Goals](/creating-a-study/review-goals) | Review and edit the generated plan |
| 4 | [Setup Interview](/creating-a-study/setup-interview) | Moderator voice, format, language, recruiting method, screeners |
| 5 | [Test Conversation](/creating-a-study/test-conversation) | Experience the study as a participant would |
| 6 | [Ready to Launch](/creating-a-study/ready-to-launch) | Review everything and launch |
| 7 | [Invite Participants](/recruiting/overview) | From your dashboard, once the study is live |

***

## Before You Begin

### What You'll Need

* **A clear research question** — what are you trying to learn?
* **Context to share** — background about your company, your situation, or your hypotheses

### What You'll Create

* A research plan tailored to your specific question
* A configured moderator ready to run natural conversations
* A study ready to launch to your participants

***

## Tips for Success

**Invest time in customization**

The more context you give Charles in Step 2, the better your research plan. Don't rush it.

**Always test before launch**

A ten-minute test conversation can save you from discovering a problem after twenty participants have already hit it.

**Size the study before you launch it**

Most studies are smaller than the confidence people want from them. The [sample size calculator](/resources/sample-size) shows what your planned number actually buys, and what it would take to reach the confidence you're after.

**Keep your research focused**

Resist asking about everything. A study that goes deep on 4–6 topics beats one that skims twelve.

**Write for your participants**

Use language your participants actually use. Avoid internal jargon in your questions.

***

## After Launch

Once your study is live, you manage it from the Study Dashboard:

| Guide | Description |
| - | - |
| [Dashboard](/managing-your-study/dashboard) | Metrics, study status, and the tabs |
| [Study actions](/managing-your-study/study-actions) | Edit, duplicate, pause, rewards, delete |
| [Recruiting participants](/recruiting/overview) | Every way to reach participants |
| [Calls & transcripts](/results/calls-and-transcripts) | Review completed interviews |
| [Reports](/results/reports) | Generate and interpret insights |

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How long does setup take?">
    Most people finish in 10–15 minutes. Complex studies take longer.
  </Accordion>

  <Accordion title="Can I save and return later?">
    Yes. Progress saves automatically — close the browser and pick up where you left off.
  </Accordion>

  <Accordion title="Can I duplicate an existing study?">
    Yes. On the dashboard, open **Actions** and choose **Duplicate Study** to use it as a starting point for a new one.
  </Accordion>

  <Accordion title="What if I make a mistake?">
    Click **Back** at any point to revise an earlier step. Most things can still be changed after launch, though changing questions mid-study makes early and late responses harder to compare.
  </Accordion>
</AccordionGroup>


# Ready to Launch
Source: https://docs.userintuition.ai/creating-a-study/ready-to-launch

Review your complete study configuration and launch. Once launched, your study is live and ready to receive participants.

Review your complete study configuration and launch. Once launched, your study is live and ready to receive participants.

***

## Overview

This is the final step before your study goes live. Take a moment to review everything and ensure your study is configured exactly as you want it.

***

## What You'll See

### Summary Cards

At the top of the screen, three cards summarize your key configurations:

| Card | Shows |
| - | - |
| **Study Type** | The type you selected (In-depth Interview, Concept Test, or Prototype Test) |
| **Interviewer** | The voice you chose (Elliot or Clara) |
| **Interview Format** | The format you configured (Chat, Voice, or Video) |

### Study Name

Your study name is displayed prominently. This is how the study will appear in your dashboard.

### Research Plan Preview

The complete research plan is displayed, including:

* Objective
* Background
* Learning Goals
* Conversation Flow
* Study-Specific Rules

***

## Final Review Checklist

Before launching, confirm:

<Accordion title="Research Plan">
  * [ ] Objective clearly states what you're trying to learn
  * [ ] Questions are written in participant-friendly language
  * [ ] All important topics are covered
  * [ ] Time allocations are appropriate for each section
</Accordion>

<Accordion title="Interviewer Settings">
  * [ ] Voice selection matches your brand and audience
  * [ ] Interview mode is appropriate for your participants
</Accordion>

<Accordion title="Study Configuration">
  * [ ] Study name is descriptive and recognizable
  * [ ] You've tested the conversation (recommended)
</Accordion>

***

## Making Last-Minute Changes

If you need to modify anything before launch:

1. Click **Back** to return to the relevant step
2. Make your changes
3. Click **Save & Continue** through subsequent steps
4. Return to this screen to launch

***

## What Happens Next

After you launch, here's what to expect:

<Steps>
  <Step title="Study goes live">
    Your study is immediately active and can receive participants
  </Step>

  <Step title="Invite participants">
    From the dashboard, you'll invite participants via email, link, panel, or widget
  </Step>

  <Step title="Conversations happen">
    As participants complete interviews, data flows into your dashboard
  </Step>

  <Step title="Review and analyze">
    Access transcripts, listen to recordings, and generate reports
  </Step>

  <Step title="Get notified when complete">
    When your study hits its target, you and your organization's admins receive
    an email with the top insights at a glance and a link to the full report
    on your dashboard.
  </Step>
</Steps>

<Info>
  **Important:** Launching does not automatically send invitations to anyone. After launching, you'll need to actively invite participants from your study dashboard.
</Info>

***

## Launching Your Study

When you're ready:

<Steps>
  <Step title="Review one final time">
    Scroll through the research plan to confirm everything looks right
  </Step>

  <Step title="Click Launch">
    Click the **Save and Launch** button
  </Step>

  <Step title="You're live!">
    Your study is now active and you'll be taken to the study dashboard
  </Step>
</Steps>

***

## After Launch

Once launched, you'll be redirected to your Study Dashboard where you can:

* **Invite participants** using multiple methods
* **Monitor progress** with real-time metrics
* **Review calls** as they complete
* **Generate reports** once you have enough responses

<CardGroup>
  <Card title="Invite Participants" icon="users" href="/recruiting/overview">
    Learn about all invitation methods
  </Card>

  <Card title="Dashboard Overview" icon="chart-line" href="/managing-your-study/dashboard">
    Navigate your study dashboard
  </Card>
</CardGroup>

***

## Can I Make Changes After Launch?

Yes, but with caveats:

| Change Type | Possible? | Recommendation |
| - | - | - |
| Edit research plan | Yes | Avoid after participants have responded |
| Change interviewer voice | Yes | Avoid after participants have responded |
| Change interview mode | Yes | Avoid after participants have responded |
| Rename study | Yes | Safe to do anytime |

<Warning>
  **Best Practice:** We strongly discourage making changes to your study after participants have started completing interviews. Changing questions or flow mid-study means earlier and later responses won't be directly comparable, which can compromise your analysis.
</Warning>

If significant changes are needed after collecting responses, consider creating a new study instead.

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I pause or unpause a launched study?">
    Yes. Open **Actions** on the study dashboard and choose **Pause Study**. While paused, the study stops taking new responses and the **Invite Participants** menu is disabled. Choose **Resume Study** to start it again. A study that has already reached its target is complete and can't be paused.
  </Accordion>

  <Accordion title="What if I need to start over?">
    You can delete the study and create a new one. Note that deleting is permanent—all data will be lost.
  </Accordion>

  <Accordion title="How soon can I invite participants?">
    Immediately. Once launched, you can start inviting participants right away from the dashboard.
  </Accordion>

  <Accordion title="Is there a limit to how many studies I can have active?">
    No. There's no limit on how many studies you can have.
  </Accordion>
</AccordionGroup>


# Review Goals
Source: https://docs.userintuition.ai/creating-a-study/review-goals

Review and refine the research plan that Charles generated. This is your opportunity to make direct edits before the study goes live.

Review and refine the research plan that Charles generated in the previous step. This is your opportunity to make direct edits before the study goes live.

***

## Overview

The Review Goals screen displays the complete research plan in an editable format. You can review every element of the plan and make changes directly in the document editor.

***

## What You'll See

### Study Name

At the top of the screen, you'll see a field to name your study. Charles suggests a default name based on your conversation, but you can change it to whatever makes sense for your organization.

Study names can contain up to 40 characters. Use a short, recognizable name that distinguishes the study in your dashboard.

**Best practices for naming studies:**

* Include the research type (e.g., "NPS Deep Dive")
* Include a date or quarter (e.g., "Q1 2024")
* Include the customer segment if relevant (e.g., "Enterprise Customers")

**Example names:**

* "Nike Voice Survey"
* "Q4 Churn Analysis - SMB Segment"
* "Post-Launch NPS - Mobile App Users"

***

### The Research Plan Document

Below the study name, you'll see the full research plan in a rich text editor. The plan typically includes:

**Objective** — A clear, concise statement of what the study aims to accomplish. This should directly address the business question you're trying to answer.

**Background** — Context about your company and situation that informs how the AI interviewer approaches conversations.

**Learning Goals** — Specific, answerable research questions, each with the evidence needed underneath. Relevant perspectives or a distinct boundary may also appear under a goal. New plans use this single section; older plans may retain a separate Key Questions list.

**Conversation Flow** — A section-by-section outline of how each interview will progress, including time estimates.

**Study-Specific Rules** — Instructions that guide the AI interviewer's behavior, ensuring professional, unbiased conversations.

***

## Editing the Research Plan

The editor includes standard formatting tools:

| Tool | Function |
| - | - |
| **Undo/Redo** | Reverse or restore recent changes |
| **Heading dropdown** | Change text to Heading 1, Heading 2, or paragraph |
| **Bold** | Make text bold |
| **Italic** | Make text italic |
| **Link** | Add a hyperlink |
| **Bulleted list** | Create a bulleted list |
| **Numbered list** | Create a numbered list |
| **Quote** | Format text as a block quote |

### Making Edits

1. Click anywhere in the document to place your cursor
2. Highlight text to modify or delete it
3. Type to add new content or use formatting tools

### Common Edits

| Edit Type | How To |
| - | - |
| **Add a question** | Navigate to the relevant section and type your question |
| **Remove a question** | Select and delete questions that aren't relevant |
| **Adjust focus** | Modify time estimates and question counts for each section |
| **Refine language** | Adjust wording to match how your customers talk |

***

## Saving Your Changes

Your changes are saved automatically as you edit. When you're satisfied with the research plan:

1. Review the complete document one more time
2. Click **Save & Continue** to proceed to [Step 4: Set Up Your Interviewer](/creating-a-study/setup-interview)

***

## Going Back to Charles

If you want Charles to make more substantial changes to the plan:

1. Click **Back** to return to Step 2
2. Tell Charles what changes you'd like
3. Charles will update the plan, and you can review it again

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I add entirely new sections to the research plan?">
    Yes. You can add any content you need. Just make sure it follows the overall structure so the AI interviewer can execute it properly.
  </Accordion>

  <Accordion title="What if I accidentally delete something important?">
    Use the **Undo** button to restore deleted content. If you've made many changes and want to start over, click **Back** to return to Step 2 and regenerate the plan.
  </Accordion>

  <Accordion title="How long should the research plan be?">
    There's no strict limit, but keep in mind that longer plans mean longer interviews. Most effective studies have 4-6 main topic areas with 2-4 questions each.
  </Accordion>

  <Accordion title="Will participants see this document?">
    No. Participants only experience the natural conversation with the AI interviewer. This document guides the AI's behavior but is not shown to participants.
  </Accordion>
</AccordionGroup>


# Setup Interview
Source: https://docs.userintuition.ai/creating-a-study/setup-interview

Configure how participants will experience the interview: moderator voice, format, language, recruiting method, and screener questions.

This step configures how participants will experience the interview. There are five sections, each collapsible.

***

## Moderator Voice

Choose who will conduct the interview. Each voice is built for research conversations — warm, professional, and easy to sit with for twenty minutes.

To preview one, click the **play button** on its card. We recommend listening to each before you choose, since the voice sets the tone of every conversation in the study.

Click a card to select it. Your choice saves automatically.

<Note>
  In chat format, participants never hear the moderator, so the voice selection applies to voice and video only. The moderator's personality stays the same across all three.
</Note>

***

## Interview Format

How participants will interact with the moderator.

| Format | What participants do | Credits per interview |
| - | - | - |
| **Chat** | Type their responses | 0.5 |
| **Voice** | Speak and hear the moderator | 1 |
| **Video** | Speak on camera, optionally sharing their screen | 2 |

**You choose the format; participants can't change it.** Whatever you set here applies to every interview in the study.

<Card title="Interview modes in depth" icon="microphone" href="/getting-started/interview-modes">
  Permissions, screen sharing, cost, and what each format is good for.
</Card>

***

## Interview Language

Select the language for the interview. Eighty-two are available, plus auto-detect. English appears first in the selector, the remaining languages are alphabetical, and auto-detect appears last.

<Columns>
  <div>
    English — `en`<br />
    Afrikaans — `af`<br />
    Albanian (Shqip) — `sq`<br />
    Amharic (አማርኛ) — `am`<br />
    Arabic (العربية) — `ar`<br />
    Armenian (Հայերեն) — `hy`<br />
    Assamese (অসমীয়া) — `as`<br />
    Azerbaijani (Azərbaycanca) — `az`<br />
    Basque (Euskara) — `eu`<br />
    Bengali (বাংলা) — `bn`<br />
    Bosnian (Bosanski) — `bs`<br />
    Bulgarian (Български) — `bg`<br />
    Burmese (မြန်မာ) — `my`<br />
    Cantonese (粵語) — `yue`<br />
    Catalan (Català) — `ca`<br />
    Croatian (Hrvatski) — `hr`<br />
    Czech (Čeština) — `cs`<br />
    Danish (Dansk) — `da`<br />
    Dutch (Nederlands) — `nl`<br />
    Estonian (Eesti) — `et`<br />
    Filipino — `fil`<br />
    Finnish (Suomi) — `fi`<br />
    French (Français) — `fr`<br />
    Galician (Galego) — `gl`<br />
    Georgian (ქართული) — `ka`<br />
    German (Deutsch) — `de`<br />
    Greek (Ελληνικά) — `el`<br />
    Gujarati (ગુજરાતી) — `gu`
  </div>

  <div>
    Hebrew (עברית) — `he`<br />
    Hindi (हिन्दी) — `hi`<br />
    Hungarian (Magyar) — `hu`<br />
    Icelandic (Íslenska) — `is`<br />
    Indonesian (Bahasa Indonesia) — `id`<br />
    Inuktitut (ᐃᓄᒃᑎᑐᑦ) — `iu`<br />
    Irish (Gaeilge) — `ga`<br />
    Italian (Italiano) — `it`<br />
    Japanese (日本語) — `ja`<br />
    Javanese (Basa Jawa) — `jv`<br />
    Kannada (ಕನ್ನಡ) — `kn`<br />
    Kazakh (Қазақша) — `kk`<br />
    Khmer (ភាសាខ្មែរ) — `km`<br />
    Korean (한국어) — `ko`<br />
    Lao (ພາສາລາວ) — `lo`<br />
    Latvian (Latviešu) — `lv`<br />
    Lithuanian (Lietuvių) — `lt`<br />
    Macedonian (Македонски) — `mk`<br />
    Malay (Bahasa Melayu) — `ms`<br />
    Malayalam (മലയാളം) — `ml`<br />
    Maltese (Malti) — `mt`<br />
    Mandarin Chinese (中文) — `zh`<br />
    Marathi (मराठी) — `mr`<br />
    Mongolian (Монгол) — `mn`<br />
    Nepali (नेपाली) — `ne`<br />
    Norwegian Bokmål (Norsk bokmål) — `nb`<br />
    Odia (ଓଡ଼ିଆ) — `or`
  </div>

  <div>
    Pashto (پښتو) — `ps`<br />
    Persian (فارسی) — `fa`<br />
    Polish (Polski) — `pl`<br />
    Portuguese (Português) — `pt`<br />
    Punjabi (ਪੰਜਾਬੀ) — `pa`<br />
    Romanian (Română) — `ro`<br />
    Russian (Русский) — `ru`<br />
    Serbian (Српски) — `sr`<br />
    Sinhala (සිංහල) — `si`<br />
    Slovak (Slovenčina) — `sk`<br />
    Slovenian (Slovenščina) — `sl`<br />
    Somali (Soomaali) — `so`<br />
    Spanish (Español) — `es`<br />
    Sundanese (Basa Sunda) — `su`<br />
    Swahili (Kiswahili) — `sw`<br />
    Swedish (Svenska) — `sv`<br />
    Tamil (தமிழ்) — `ta`<br />
    Telugu (తెలుగు) — `te`<br />
    Thai (ไทย) — `th`<br />
    Turkish (Türkçe) — `tr`<br />
    Ukrainian (Українська) — `uk`<br />
    Urdu (اردو) — `ur`<br />
    Uzbek (Oʻzbekcha) — `uz`<br />
    Vietnamese (Tiếng Việt) — `vi`<br />
    Welsh (Cymraeg) — `cy`<br />
    Wu Chinese (吴语) — `wuu`<br />
    Zulu (isiZulu) — `zu`
  </div>
</Columns>

### Pick a specific language wherever you can

**Setting a specific language localizes the whole participant experience**, not just the conversation: the screener questions and the moderator's opening line are all translated into it before the participant sees them.

**Auto-detect (Ask Participant)** doesn't do that. It lets each participant choose their language once the conversation starts — but the screener questions stay in **English**, and so does the moderator's opening line. A participant who came for a Spanish interview meets an English screener and an English greeting first, which is a confusing way to begin.

<Warning>
  If you know most interviews will be in one language, **set that language** rather than using auto-detect. Reserve auto-detect for genuinely mixed audiences where you can't predict the language and are willing to accept an English screener.
</Warning>

For multi-market research where each market matters, running one study per language gives every participant a fully localized experience — and gives you results you can compare market by market.

***

## Recruiting Method

How you'll reach participants. Two options:

| Option | Meaning |
| - | - |
| **BYOP** | Bring your own participants and manage recruiting yourself |
| **Panel** | Recruit participants from our network of quality respondents |

**This choice determines your invite options after launch.** BYOP studies get a study link, email invites, and an embed code. Panel studies get panel recruiting and niche audience requests.

<Card title="Recruiting participants" icon="users" href="/recruiting/overview">
  How to choose between them, and what each costs.
</Card>

***

## Screener Questions and Targeting Attributes

Qualify participants before they reach the interview.

### Standard attributes

Six common attributes are one click away as pills: **Age**, **Gender**, **Zip Code**, **Region**, **Household Income**, and **Ethnicity**. Click one to add it to your screener.

For anything beyond those, click **Advanced** to browse the full catalog of standard qualifications.

### Custom questions

Click **Add Question** to write your own. Each custom question is either **Single Select** (participants pick one option) or **Multiple Select** (they pick several).

For each answer option you can mark whether it **disqualifies** the participant — anyone choosing it won't proceed to the interview.

Questions can be reordered by dragging, and collapsed while you work on others.

### Randomizing Answer Options

When editing a multiple-choice screener question, use the **Randomize options** checkbox next to the question type to shuffle the order of that question's answer options.

* It's available on single-select and multiple-select questions.
* When enabled, participants see that question's answer options in a fresh random order each time they open the screener.
* Randomizing helps reduce **order bias**—the tendency to pick whichever option appears first—so your qualifying data better reflects genuine choices.
* Leave it unchecked to always show options in the order you wrote them. That's the better choice when the order is meaningful, such as ranked scales or ascending ranges.

<Note>
  Randomization changes only the order options are displayed. Which options qualify or disqualify a participant is unaffected.
</Note>

***

## Proceeding to the Next Step

Review your selections and click **Save & Continue** to move to [Step 5: Test Conversation](/creating-a-study/test-conversation).

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I add screener questions later?">
    Yes — either here, or by asking Charles in Step 2. He'll use standard qualifications where they fit.
  </Accordion>

  <Accordion title="What if a participant's device doesn't support the format?">
    They'll see an error. Voice and video need a working microphone, and video needs a camera. Chat works anywhere.
  </Accordion>

  <Accordion title="Where do I set participant rewards?">
    After launch, from the dashboard **Actions** menu. See [Study actions](/managing-your-study/study-actions).
  </Accordion>
</AccordionGroup>


# Test Conversation
Source: https://docs.userintuition.ai/creating-a-study/test-conversation

Experience your study from a participant's perspective before launching. This step lets you validate that the conversation flows naturally and covers the topics you need.

Experience your study from a participant's perspective before launching. This step lets you validate that the conversation flows naturally and covers the topics you need.

You'll have a real conversation with the moderator you configured, running the research plan you just built. Optional, but a ten-minute test catches problems while they're still cheap to fix.

***

## How to run a test

### Starting the Test

1. On the Test Conversation screen, you'll see: **"Ready to test your study?"**
2. Click **Start Test Conversation** to begin
3. Experience the full participant flow

### During the Test

Once the test begins, you'll experience the full participant flow:

1. The moderator greets you and introduces the study
2. You're asked questions from your research plan
3. The moderator probes deeper based on your responses
4. The conversation wraps up

**Tips for effective testing:**

* **Respond naturally:** Don't just give short answers. Respond as a real participant would.
* **Try different response types:** Give some detailed answers and some brief answers.
* **Test edge cases:** What happens if you give an unexpected answer?
* **Complete the full conversation:** Don't skip ahead—experience the entire flow.

### Ending the Test

When the conversation concludes (or if you end it early):

1. You'll see a feedback screen: **"How was the conversation?"**
2. Select **Good** or **Needs Work** to provide quick feedback
3. Optionally, add written comments in the text field
4. Click **Submit** to record your feedback

***

## Making Adjustments

If you identify issues during testing, you have several options:

### Option 1: Minor Adjustments

For small changes to question wording or flow:

1. Click **Back** to return to Step 3 (Review Goals)
2. Edit the research plan directly
3. Proceed through the steps again to re-test

### Option 2: Major Changes

For significant restructuring of the research plan:

1. Click **Back** repeatedly to return to Step 2 (Customize Plan)
2. Chat with Charles about the changes you need
3. Let Charles regenerate the research plan
4. Review and test again

### Option 3: Proceed Anyway

If the issues are minor and you're comfortable proceeding:

1. Note the issues for future improvement
2. Click **Save & Continue** to proceed to launch

***

## Usage Limits

**Test conversations do not count against your usage limits.** You can test as many times as you need to get the conversation right.

This encourages thorough testing without worrying about consuming your allotted interviews.

***

## Skipping the Test

While testing is optional, we strongly recommend completing at least one test conversation before launch. However, if you're confident in your research plan:

1. Click **Save & Continue** without starting a test
2. You'll proceed to Step 6 (Ready to Launch)

> **Warning:** Skipping testing means your first real participant will be your first test. We recommend always testing before inviting participants.

***

## Proceeding to the Next Step

After testing (or choosing to skip):

1. Review any feedback or issues you noted
2. Make adjustments if needed by clicking **Back**
3. Click **Save & Continue** to proceed to [Step 6: Ready to Launch](/creating-a-study/ready-to-launch)

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I test multiple times?">
    Yes! Test as many times as you need. Each test helps you refine the experience.
  </Accordion>

  <Accordion title="Do test conversations appear in my results?">
    They're labelled with a **Test** badge so you can tell them apart from real participants, and they're never eligible for rewards.
  </Accordion>

  <Accordion title="Can other team members test the conversation?">
    Yes. Anyone with access to the study can run a test conversation.
  </Accordion>

  <Accordion title="How long does a test conversation take?">
    Test conversations take as long as a real interview—typically 10-20 minutes depending on your research plan. You can end early if you've seen enough.
  </Accordion>

  <Accordion title="The moderator responded differently than I expected. Is that a problem?">
    Not necessarily — it adapts to each conversation, so no two run identically. It's worth adjusting your research plan if it *consistently* misses an important probe or heads somewhere you don't want.
  </Accordion>
</AccordionGroup>


# Interview Modes
Source: https://docs.userintuition.ai/getting-started/interview-modes

Interviews run as chat, voice, or video. How the three differ in what they capture, what participants have to allow, and what they cost.

Every study runs in one of three formats: **chat**, **voice**, or **video**.

**You choose the format when you build the study, in [Step 4](/creating-a-study/setup-interview). Participants can't change it**, and it applies to every interview in the study.

***

## The three formats

| | Chat | Voice | Video |
| - | - | - | - |
| **What participants do** | Type their responses | Speak, and hear the moderator | Speak on camera |
| **What's captured** | Transcript | Transcript + audio | Transcript + audio + video |
| **Device permission needed** | None | Microphone | Camera and microphone |
| **Screen sharing** | — | Available | Available |
| **Credits per interview** | 0.5 | 1 | 2 |

***

## Chat

Participants type their answers in a text conversation.

The lowest-friction option — nothing to allow, nothing to set up, and it works anywhere a browser does. Participants can take their time composing an answer, which suits detailed or technical questions and anyone answering in a second language.

The trade-off is that typed answers tend to be shorter and flatter than spoken ones. You lose hesitation, emphasis, and the moment someone talks themselves into a different opinion.

***

## Voice

Participants speak and hear the moderator, like a phone call.

This is the workhorse format. Spoken answers run longer and reveal more than typed ones, and a twenty-minute conversation isn't tiring in the way twenty minutes of typing would be. You get tone, hesitation, and the moment someone changes their mind.

Participants can also **share their screen** in voice interviews, which is enough for most walkthroughs — you see what they're doing without needing them on camera.

***

## Video

Participants speak on camera, and can share their screen.

Use video when you need to see the person or what they're looking at: reactions to a concept, watching someone work through an interface, or research where facial expression is part of the finding.

<Note>
  **You can't require a participant to turn their camera on.** Camera control sits with the participant in their browser. If they decline, the interview still runs and is still recorded as a voice conversation — you just don't get the video track. Plan for a share of any video study to come back without video.
</Note>

***

## Permissions and privacy

Chat needs no device access at all.

Voice and video ask for the microphone — and, for video, the camera — **before the interview starts**. That means participants meet the privacy question up front, while they're still deciding whether to take part, rather than being surprised by it mid-conversation. Consent is handled before any recording begins.

If a participant's device or browser can't support the format, they'll see an error before the conversation starts rather than partway through.

***

## Cost

Interviews are billed in credits, and the format sets the multiplier:

| Format | Credits |
| - | - |
| Chat | 0.5 |
| Voice | 1 |
| Video | 2 |

A video interview costs four times a chat interview. If you don't need the camera, voice gets you most of the depth at half the price.

<Card title="Billing and credits" icon="credit-card" href="/resources/billing-and-credits">
  What a credit costs on each plan.
</Card>

***

## Choosing

Start with **voice**. It's the best depth-per-credit trade in the platform and suits most research.

Move to **video** when seeing the participant or their screen is part of the finding — and accept that some participants will keep their camera off.

Use **chat** when speaking isn't practical: participants in open-plan offices, sensitive topics people would rather type, or audiences where typing lowers the barrier enough to matter for your response rate.

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can a participant switch formats mid-interview?">
    No. The format is fixed for the whole study.
  </Accordion>

  <Accordion title="Can I change the format after launch?">
    Yes, from **Actions → Edit Study**, but responses collected before and after won't be directly comparable. If you're partway through, duplicate the study instead.
  </Accordion>

  <Accordion title="Does the moderator appear on camera in video interviews?">
    No. The moderator speaks and listens; there's no on-camera avatar. Participants see themselves and their own screen share.
  </Accordion>

  <Accordion title="Does the voice selection matter in chat studies?">
    No. Participants never hear the moderator in chat, so the voice applies only to voice and video. The moderator's personality is the same across all three.
  </Accordion>
</AccordionGroup>


# Key Concepts
Source: https://docs.userintuition.ai/getting-started/key-concepts

Understand the core concepts behind User Intuition: studies, interviews, the moderator, and the Intelligence Hub — and how they fit together.

A few concepts shape how everything on the platform works. Worth five minutes before you build your first study.

***

## Studies

A **study** is a research project focused on a specific question. Each one has:

* **A research plan** — the objective, answerable Learning Goals with evidence requirements, and conversation flow
* **An interview setup** — moderator voice, format, language, recruiting method, and screeners
* **Participants** — who you've invited and where they've got to
* **Results** — completed interviews, transcripts, and reports

### Study types

There are three. All follow the same setup process; what differs is whether participants react to something, and what.

| Type | Best for |
| - | - |
| **In-depth Interview** | Experiences, motivations, and decisions — no stimulus |
| **Concept Test** | Reactions to an image or video |
| **Prototype Test** | Watching people work through a prototype or live site |

<Card title="Study types in depth" icon="layer-group" href="/study-types/overview">
  What each one does and when to reach for it.
</Card>

***

## Interviews

An **interview** — also called a call — is one conversation between the moderator and one participant. Interviews are:

* **Conversational** — natural dialogue, not a rigid survey
* **Adaptive** — the moderator follows up based on what it hears
* **Deep** — it probes past the first answer to get at the reasoning underneath
* **Recorded** — transcript captured automatically, with audio or video where the format includes it

### Interview formats

| Format | What participants do | Credits |
| - | - | - |
| **Chat** | Type their responses | 0.5 |
| **Voice** | Speak and hear the moderator | 1 |
| **Video** | Speak on camera, optionally sharing their screen | 2 |

You set the format when you build the study. Participants can't change it.

<Card title="Interview modes" icon="microphone" href="/getting-started/interview-modes">
  How chat, voice, and video differ — permissions, screen sharing, and cost.
</Card>

### Interview quality

Every completed interview is rated **Excellent**, **Good**, **Fair**, or **Poor**, based on how long the conversation ran, how substantive the answers were, and how much of your research plan it actually covered.

***

## Charles, your AI researcher

**Charles** helps you design studies. During setup he asks clarifying questions about your goals, drafts a research plan, and revises it as you give feedback. You work with Charles in chat.

***

## The moderator

The **moderator** is the AI that runs the actual conversations with participants. It follows your research plan while adapting to each conversation, probes deeper when something interesting surfaces, and keeps a warm, professional tone throughout. It achieves 98% participant satisfaction.

Charles and the moderator are different things: **Charles helps you design the study; the moderator runs it.**

***

## Participants

**Participants** are the people who complete your interviews. There are two ways to reach them:

| Approach | Methods |
| - | - |
| **Bring your own participants** | Share a study link · Send email invites · Embed a widget |
| **Research panel** | Recruit from our panel · Recruit a niche audience |

You choose which when you set up the study, and it determines your invite options on the dashboard.

<Card title="Recruiting participants" icon="users" href="/recruiting/overview">
  How to choose, and what each method costs.
</Card>

***

## Reports

**Reports** synthesize findings across multiple interviews into an executive summary, top insights, analysis by theme, and supporting quotes. They need at least 2 completed interviews and can be regenerated as more come in.

***

## Intelligence Hub

The **Intelligence Hub** is a workspace for analyzing knowledge across studies rather than within one. Sync completed studies, upload external documents, and ask questions in plain language across everything at once. It also generates reports and presentations.

Where a per-study report answers "what did this study find?", the Intelligence Hub answers "what do we know?" — and gets richer with every study you add.

<Card title="Intelligence Hub guide" icon="brain" href="/results/intelligence-hub">
  Sync sources, ask questions, and generate outputs.
</Card>

***

## Key metrics

You'll see these on every study dashboard:

| Metric | Meaning |
| - | - |
| **Responses** | Completed interviews |
| **Avg Length** | Average interview duration |
| **Quality** | Responses meeting quality thresholds |
| **Study Progress** | Responses collected against your target |

***

## Credits

Interviews are paid for in **credits**. How many an interview costs depends on its format — chat 0.5, voice 1, video 2 — and what a credit costs depends on your plan. Test conversations are free.

<Card title="Billing and credits" icon="credit-card" href="/resources/billing-and-credits">
  Plans, credit pricing, and panel costs.
</Card>

***

## Next Steps

* [Quickstart](/getting-started/quickstart) — launch your first study
* [Creating a Study](/creating-a-study/overview) — the full setup guide


# Quickstart Guide
Source: https://docs.userintuition.ai/getting-started/quickstart

Launch your first research study in about 15 minutes. This guide walks you through the essential steps to go from zero to collecting insights.

This guide gets you from zero to collecting insights in about 15 minutes. For detail on each step, see [Creating a Study](/creating-a-study/overview).

***

## Prerequisites

Before you begin, have ready:

* A clear research question — what are you trying to learn?
* Context about your company and situation
* A list of people to invite, or a plan to use our research panel

***

## Step 1: Create Study

Choose one of three study types: **In-depth Interview**, **Concept Test**, or **Prototype Test**. In-depth Interview is selected by default.

Click **Save & Continue**.

> **Not sure which?** Start with In-depth Interview and tell Charles what you want to learn. You can change it later.

***

## Step 2: Customize Plan

Chat with Charles about your company, what you're trying to learn, and any hypotheses you have. Your research plan builds in the panel on the right as you talk.

**Example input:**

> "We're Nike Store and our satisfaction scores have dropped over the past few months. We want to understand why customers are less happy and what's driving the decline."

This step usually takes 5–10 minutes. The more context you give Charles, the more useful the plan.

***

## Step 3: Review Goals

* Give your study a descriptive name
* Review the generated research plan
* Edit any questions or flow directly
* Click **Save & Continue**

***

## Step 4: Setup Interview

Five things to configure:

* **Moderator voice** — preview the options and pick one
* **Interview format** — Chat, Voice, or Video. You choose this; participants can't change it
* **Interview language** — 82 languages, or auto-detect and let the participant pick
* **Recruiting method** — bring your own participants, or use our panel. This determines your invite options later
* **Screener questions** — qualify participants before they reach the interview

Click **Save & Continue**.

***

## Step 5: Test Conversation

> **Recommended.** Optional, but a test run catches problems before real participants hit them.

* Click **Start Test Conversation**
* Experience the interview the way a participant will
* Leave feedback when you're done

Test conversations are free and don't consume credits.

***

## Step 6: Ready to Launch

Review your complete study configuration — study type, moderator, format, and the full research plan — then click **Save and Launch**.

Your study is live. Launching doesn't invite anyone yet.

***

## Step 7: Invite Participants

You're taken to your study dashboard. Open the **Invite Participants** menu — what you see depends on the recruiting method you chose in Step 4.

| If you chose | Your options |
| - | - |
| **Bring your own participants** | Copy the study link · Send email invites · Copy the embed code |
| **Panel** | Recruit from our panel · Recruit a niche audience |

See [Recruiting Participants](/recruiting/overview) for how to choose and what each method costs.

***

## What's Next?

* [Creating a Study](/creating-a-study/overview) — detail on each setup step
* [Study Types](/study-types/overview) — what each of the three actually does
* [Recruiting Participants](/recruiting/overview) — every way to reach participants
* [Reviewing Your Results](/results/calls-and-transcripts) — transcripts, reports, and the Intelligence Hub


# HubSpot
Source: https://docs.userintuition.ai/integrations/hubspot

Sync HubSpot CRM contacts, companies, and deals into User Intuition and invite them to interviews directly from HubSpot record pages.

The HubSpot integration connects your HubSpot CRM to User Intuition so the people, companies, and deals you already track in HubSpot become available as Participants for Studies. Once installed, embedded cards appear on HubSpot record pages showing sync status, and a deep link lets you invite any CRM contact to an Interview without leaving HubSpot.

***

## What the HubSpot app does

<CardGroup>
  <Card title="Sync CRM data" icon="arrows-rotate">
    Pulls contacts, companies, and deals from your HubSpot portal into User Intuition as Participants and segments.
  </Card>

  <Card title="Embedded UI" icon="window">
    Adds a User Intuition card to contact, company, and deal record pages inside HubSpot.
  </Card>

  <Card title="One-click invite" icon="paper-plane">
    Invite a HubSpot contact to a Study Interview via a deep link from the CRM card.
  </Card>

  <Card title="Automatic provisioning" icon="user-plus">
    Creates or links a User Intuition account during the OAuth flow so installers do not need to sign up separately.
  </Card>
</CardGroup>

***

## Installation

The HubSpot app is installed through HubSpot's standard OAuth flow. Once authorized, an account record is created on the User Intuition side and the embedded cards become available across your portal.

<Steps>
  <Step title="Open the listing">
    Find **User Intuition** in the HubSpot Marketplace (or follow the install link shared by your team) and click **Install**.
  </Step>

  <Step title="Choose your portal">
    Select the HubSpot account you want to connect. You must be an admin of that portal to install third-party apps.
  </Step>

  <Step title="Authorize the requested scopes">
    HubSpot will display the scopes the app requests (read access to contacts, companies, deals, and the ability to render UI extensions on CRM records). Click **Connect app** to authorize.
  </Step>

  <Step title="Land in User Intuition">
    After OAuth completes, you will be redirected to User Intuition. If your email is already associated with a User Intuition account, you will be signed in directly. If not, an invitation is created so you can finish setting up an account using a password or Google sign-in.
  </Step>

  <Step title="First sync">
    A default **All Contacts** segment is created automatically. You can trigger the initial sync from the HubSpot record card or from the app settings page.
  </Step>
</Steps>

<Note>
  The connection between User Intuition and HubSpot is one-to-one per portal. Reinstalling on the same portal updates the existing connection rather than creating a duplicate.
</Note>

***

## CRM record cards

After installation, a **User Intuition** card appears on contact, company, and deal records in HubSpot.

The card surfaces:

* The current sync state for the connected portal (idle, syncing, completed, or error)
* A count of Participants imported into User Intuition
* A button to trigger or re-trigger a sync
* A deep link to open the contact, company, or deal in User Intuition and invite them to an Interview

<Tabs>
  <Tab title="Contact card">
    Displays the sync status for the portal and a **Send to User Intuition** action that opens the matching Participant in User Intuition. From there you can attach the contact to a Study and send an Interview invite.
  </Tab>

  <Tab title="Company card">
    Shows whether the company has been synced and links to the company's record in User Intuition, where you can see all associated Participants.
  </Tab>

  <Tab title="Deal card">
    Shows sync status for the deal and lets you jump to the deal's view in User Intuition for follow-up research with the people on that deal.
  </Tab>
</Tabs>

<Note>
  Card content is rendered with HubSpot UI Extensions, so it follows HubSpot's native look and feel and respects HubSpot's user permissions on the underlying record.
</Note>

***

## App settings page in HubSpot

Open the User Intuition app from **Settings** → **Integrations** → **Connected apps** in HubSpot. The settings page provides:

* An overview of the connected portal and its current sync status
* A button to trigger a manual full sync of contacts, companies, and deals
* High-level batch and timing settings used by the app
* A link out to your User Intuition workspace

Use this page when you want to kick off a sync portal-wide rather than from a single record.

***

## What syncs

The integration moves data **from HubSpot into User Intuition**. It does not push interview data back into HubSpot.

| HubSpot object | Becomes in User Intuition | Notes |
| - | - | - |
| Contact | Participant | Email, name, and phone are mapped; remaining properties are stored on the Participant record. |
| Company | Company / segment context | Used to group Participants and surface company context in research. |
| Deal | Deal context | Provides additional context for Interviews tied to a sales motion. |
| HubSpot list (where applicable) | Segment | Lists become segments you can target when sending Interview invites. |

### Manual triggering

You can start a sync at any time from:

* The User Intuition card on any HubSpot record
* The User Intuition settings page in HubSpot's connected apps screen

A manual sync re-fetches contacts, companies, and deals in batches and updates Participants in User Intuition. Repeated syncs are idempotent — existing Participants are updated in place rather than duplicated.

### Automated triggering

The app subscribes to HubSpot webhook events for incremental updates so changes flow through without requiring a full re-sync each time:

* **Contact created** — a new Participant is created in User Intuition.
* **Contact property changed** — the matching Participant is updated.
* **App uninstalled** — triggers cleanup (see below).

For larger portals, periodic full syncs are still useful as a backstop in case any incremental events are missed.

<Warning>
  Initial syncs on large portals can take several minutes. The card will display an in-progress state and update once the sync completes.
</Warning>

***

## Inviting CRM contacts to Interviews

The CRM card includes a deep link from any HubSpot contact directly into User Intuition. Use it to:

<Steps>
  <Step title="Open the contact in HubSpot">
    Navigate to the contact's record. The User Intuition card appears in the right-hand sidebar (or wherever you have placed it in your record layout).
  </Step>

  <Step title="Open in User Intuition">
    Click the link on the User Intuition card. You are taken to the matching Participant in your User Intuition workspace.
  </Step>

  <Step title="Send an invite">
    From the Participant view, attach them to a Study and send an Interview invite. You can also send invites in bulk to a synced segment from the Studies area.
  </Step>
</Steps>

<Note>
  Bulk invites to an entire HubSpot list (or any synced segment) are sent from User Intuition rather than from inside HubSpot. The HubSpot card focuses on per-record actions.
</Note>

***

## Uninstall behavior

Uninstalling the User Intuition app from HubSpot triggers cleanup on both sides:

1. HubSpot fires the **app uninstalled** webhook to the User Intuition HubSpot service.
2. The HubSpot app calls User Intuition's external integration API to remove the connection.
3. Local OAuth tokens, sync state, and the HubSpot account record are removed.
4. Imported Participants and segments associated with the disconnected portal are detached so they no longer receive automated updates from HubSpot.

<Warning>
  Reconnecting a previously disconnected portal will start fresh — sync state and external mapping are not preserved across an uninstall. Plan a reconnection during a quiet window if you have a large portal.
</Warning>

***

## Pitfalls and known limits

<CardGroup>
  <Card title="Admin install only">
    Installing the app requires HubSpot admin permissions on the portal. If install fails, confirm the installer's role.
  </Card>

  <Card title="Email is the bridge">
    Participants are matched to HubSpot contacts by email. Contacts without an email address sync but cannot receive Interview invites.
  </Card>

  <Card title="One portal per workspace">
    A given User Intuition workspace is connected to a single HubSpot portal. Connecting another portal requires a separate workspace.
  </Card>

  <Card title="Outbound only">
    The integration syncs data into User Intuition. Interview transcripts and outcomes are not currently written back to HubSpot records.
  </Card>

  <Card title="Webhook coverage">
    Incremental updates rely on HubSpot's contact webhooks. Property updates that are not part of the subscribed events are picked up on the next full sync.
  </Card>

  <Card title="Large portals">
    Initial sync time scales with the size of your portal. For very large CRMs, expect the first sync to run for several minutes before the card shows a completed state.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="Create a Study" icon="plus" href="/creating-a-study/overview">
    Build a Study and invite synced HubSpot contacts as Participants.
  </Card>

  <Card title="Intelligence Hub" icon="brain" href="/results/intelligence-hub">
    Combine Interview results from synced HubSpot contacts with other Studies for cross-cutting analysis.
  </Card>
</CardGroup>


# MCP Server
Source: https://docs.userintuition.ai/integrations/mcp-server

Let Claude, ChatGPT, and other AI agents operate User Intuition through the Model Context Protocol — create studies, check results, and manage research with natural language.

The MCP server has its own section. See the [MCP tab](/mcp-server/overview) for
the 34-tool reference, setup instructions, Customize Plan workflow, and links to ready-to-use
[research Skills](/skills/overview).


# Shopify Integration
Source: https://docs.userintuition.ai/integrations/shopify

Connect your Shopify store to User Intuition to sync customers and segments, then invite them to research interviews without leaving the Shopify Admin.

The User Intuition Shopify app is an embedded admin app that bridges your Shopify store and your User Intuition workspace. Once installed, customers and customer segments sync automatically into User Intuition so you can recruit existing buyers as Participants for Studies and Interviews — directly from inside the Shopify Admin.

***

## What you can do with the Shopify app

<CardGroup>
  <Card title="Sync your customer base">
    Imported customers become Participants you can invite to Interviews — including their name, email, phone, and order history.
  </Card>

  <Card title="Sync customer segments">
    Shopify customer segments (for example, VIPs, recent buyers, or churned customers) sync into User Intuition so you can target Studies at the audience that matters.
  </Card>

  <Card title="Run Studies in-admin">
    Browse your Studies, create new ones, and check sync status from inside the Shopify Admin — no separate login required.
  </Card>

  <Card title="Stay GDPR-compliant">
    The app implements Shopify's required compliance webhooks so customer-data and shop-redaction requests are honored automatically.
  </Card>
</CardGroup>

***

## Installing the app

The User Intuition app is an OAuth-based Shopify app. Installation creates a `Shop` record on the User Intuition side and bootstraps your User Intuition account automatically — you don't need to sign up separately first.

<Steps>
  <Step title="Install from the Shopify App Store">
    Locate the User Intuition listing and click the install action. Shopify will walk you through the standard OAuth permission grant.
  </Step>

  <Step title="Approve the requested scopes">
    The app requests read access to customers and orders so it can sync segments and customer profiles into User Intuition. No write scopes are requested.
  </Step>

  <Step title="Land in the embedded admin UI">
    After approving, Shopify redirects you to the embedded app inside your Admin. The app auto-creates your User Intuition account using your shop's email on file — there is no extra sign-in step.
  </Step>

  <Step title="Initial sync runs in the background">
    The app immediately kicks off a customer and segment sync. You can keep working while it completes.
  </Step>
</Steps>

<Note>
  Your User Intuition user is linked to your shop domain. If you uninstall and reinstall on the same shop, the app reconnects to your existing account rather than creating a new one.
</Note>

***

## The embedded admin UI

The User Intuition app appears in your Shopify Admin under **Apps**. Opening it loads the embedded UI inside the Shopify Admin shell — you never leave the Admin tab.

From inside the embedded app you can:

* See current sync status (pending, syncing, segments synced, complete) and how many customers have been imported so far
* Browse your Studies and their status (creating, fielding, complete, and so on)
* Create a new Study using the in-Admin Study builder
* Open deep links to your User Intuition workspace for anything that lives outside the embedded experience

<Note>
  The embedded UI uses Shopify Polaris components, so it looks and feels native to the Shopify Admin.
</Note>

***

## What syncs and how often

Two kinds of data sync from Shopify into User Intuition: **segments** and **customers**.

| Data | Direction | Trigger |
| - | - | - |
| Customer segments | Shopify → User Intuition | On install, and whenever a sync is initiated |
| Customers (with email, phone, orders, tags) | Shopify → User Intuition | On install, and whenever a sync is initiated |
| Default "All Customers" segment | Created in User Intuition | On first connection |

### Batched sync

Customer syncs run in **batches** rather than as a single large request. This keeps each request small enough to be reliable on large stores and lets the embedded UI report progressive status updates as batches complete. You'll see counts climb in the embedded app as batches are processed.

The sync flow at a high level:

1. The embedded app fetches segments from the Shopify Admin GraphQL API and posts them to User Intuition.
2. The app then walks through customers in batches, posting each batch.
3. Each Participant is upserted on a stable `(shop_domain, customer_id)` key, so re-runs don't create duplicates.
4. Customers are linked to the segments they belong to in Shopify.
5. When the final batch completes, the connection status flips to **complete**.

<Note>
  Re-running a sync is safe. It refreshes existing Participants and segments rather than creating duplicates.
</Note>

***

## Inviting customers to Interviews

Once customers are synced, they appear as Participants inside your User Intuition workspace. From there you can:

* Filter Participants by the Shopify segment they belong to (for example, only invite VIPs)
* Search Participants by name, email, or phone
* Select Participants and invite them to a Study

Each Participant carries their full Shopify customer object (orders, total spent, tags, and so on) so you can use that context when building screeners or reviewing Interview responses.

***

## GDPR and compliance webhooks

Shopify requires every public app to implement three compliance webhooks. The User Intuition app subscribes to all of them:

| Webhook | What we do |
| - | - |
| `customers/data_request` | Acknowledge the request so the merchant can fulfill it. Imported Participant data lives under your User Intuition account. |
| `customers/redact` | Remove the affected customer's Participant record and any imported metadata for them. |
| `shop/redact` | Remove all imported segments, Participants, and shop state associated with the uninstalled shop. |

<Warning>
  Compliance webhooks fire on Shopify's schedule (typically 48 hours after uninstall for shop redaction). If you need a customer's data removed immediately, trigger redaction from your Shopify Admin rather than waiting for the scheduled webhook.
</Warning>

***

## Disconnecting and uninstalling

You can disconnect the integration at any time by uninstalling the app from your Shopify Admin's **Apps** page.

When you uninstall:

<Steps>
  <Step title="Shopify fires the app-uninstalled webhook">
    Shopify notifies the User Intuition app that your shop has uninstalled.
  </Step>

  <Step title="The app calls the User Intuition delete endpoint">
    User Intuition removes the external connection record and the shop's imported segments and Participants from your workspace's external integration tables.
  </Step>

  <Step title="Local shop state is cleaned up">
    The app's local `Shop` record and sync state are removed.
  </Step>

  <Step title="Compliance redaction follows">
    Shopify later fires `shop/redact` (typically after 48 hours), which triggers a final sweep to make sure nothing tied to the shop remains.
  </Step>
</Steps>

<Note>
  Studies you've already created and Interview transcripts you've already collected are part of your User Intuition workspace — they are not deleted when you uninstall the Shopify app. Only the integration link and the imported customer/segment data are removed.
</Note>

***

## Common setup pitfalls

<CardGroup>
  <Card title="Shop email missing on Shopify">
    Auto-bootstrap uses the shop's contact email on file in Shopify to create or look up your User Intuition account. If that email is blank, set it under **Settings → Store details** before opening the embedded app for the first time.
  </Card>

  <Card title="Very large customer bases">
    Stores with hundreds of thousands of customers may take several minutes for the initial sync to complete. The embedded app shows progressive batch counts — let it run rather than refreshing repeatedly.
  </Card>

  <Card title="No segments visible after install">
    If you haven't created any customer segments in Shopify yet, only the default "All Customers" segment will appear in User Intuition. Create segments in **Customers → Segments** in your Shopify Admin and re-run the sync.
  </Card>

  <Card title="Reinstalling on the same shop">
    Reinstalling reconnects to your existing User Intuition workspace. Studies, Participants, and balances persist across reinstalls on the same shop domain.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="Create a Study" icon="plus" href="/creating-a-study/overview">
    Build a Study and invite your synced Shopify customers as Participants.
  </Card>

  <Card title="Invite customers" icon="users" href="/recruiting/invite-customers">
    Filter, search, and invite imported customers to Interviews.
  </Card>
</CardGroup>


# Stripe
Source: https://docs.userintuition.ai/integrations/stripe

Connect your Stripe account to sync customers and customer cohorts into User Intuition as research participants.

The Stripe integration turns the customers in your Stripe account into a research panel. Once connected, your Stripe customers and customer-derived segments sync into User Intuition, where you can invite them to Studies and run Interviews against the same cohorts you already manage in Stripe.

<Note>
  This integration is delivered as a Stripe App that runs alongside your Stripe Dashboard. The app handles the sync; User Intuition handles the research.
</Note>

***

## What this integration does

<CardGroup>
  <Card title="Sync customers as Participants">
    Every Stripe customer becomes a Participant record in User Intuition with their email, name, phone, and Stripe metadata, ready to be invited to a Study.
  </Card>

  <Card title="Sync customer cohorts as segments">
    Cohorts derived from your Stripe data — for example, all customers, active subscribers, or customers grouped by product — are imported as segments you can target.
  </Card>

  <Card title="Stay in sync over time">
    Webhook events from Stripe (customer created, customer updated, subscription changes) flow back to User Intuition so your panel stays current as your Stripe data changes.
  </Card>

  <Card title="Send Interview invites to a cohort">
    Pick any synced segment and launch a Study against it — invites go out to every Participant in the cohort in one action.
  </Card>
</CardGroup>

***

## Connecting Stripe

The Stripe app uses Stripe's OAuth flow to authorize User Intuition against your Stripe account. The connection is established once, after which sync runs automatically.

<Steps>
  <Step title="Open the integrations area">
    In User Intuition, navigate to the integrations area and choose **Stripe**.
  </Step>

  <Step title="Start the OAuth flow">
    Click the option to connect Stripe. You will be redirected to Stripe to authorize the User Intuition app against the Stripe account you choose.
  </Step>

  <Step title="Approve the requested access">
    Review the permissions Stripe shows you and approve. Stripe will issue an authorization code, which the User Intuition Stripe app exchanges for an access token.
  </Step>

  <Step title="Wait for the initial sync">
    On approval, you are redirected back to User Intuition. A background sync begins immediately — fetching your customers and cohorts and populating your panel.
  </Step>
</Steps>

<Note>
  You can also reach the connection flow from inside the Stripe Dashboard if you have the User Intuition app installed there. Either entry point produces the same result.
</Note>

***

## What gets synced

When you connect Stripe, the following data flows into User Intuition:

| Stripe object | Becomes in User Intuition | Notes |
| - | - | - |
| Customer | Participant | Includes email, name, phone, currency, and Stripe metadata. |
| Subscription | Participant data | Subscription status and plan are attached to the customer's Participant record. |
| Customer cohorts | Segments | For example, "All Customers", "Active Subscribers", or per-product groupings. |

Each synced Participant keeps a reference back to its Stripe customer ID, so updates from Stripe (created, updated, deleted) keep the User Intuition record aligned over time.

<Warning>
  User Intuition only sees customer data your Stripe account exposes through the authorized scope. Card numbers, payment methods, and other sensitive payment data are never synced.
</Warning>

***

## Required access

The User Intuition Stripe app requests read-write access to your Stripe account through Stripe Connect. In practice, the app uses this access to:

* List and read Stripe customers (for the initial backfill and ongoing sync).
* List and read subscriptions and the products they reference (to derive segments).
* Receive webhook events for `customer.created`, `customer.updated`, `customer.deleted`, `customer.subscription.created`, `customer.subscription.updated`, and `customer.subscription.deleted`.
* Receive `account.application.deauthorized` so the app can clean up if you disconnect.

If a permission is unavailable for your account, the corresponding sync step is skipped and a status message is recorded so you know what was missed.

***

## Sending an Interview to a Stripe cohort

Once your Stripe data is synced, any Stripe-derived segment can be used as the Participant pool for a Study.

<Steps>
  <Step title="Pick a segment">
    Open the Participants area of User Intuition. Synced Stripe segments appear alongside any other imported sources. Each segment shows a count of Participants it contains.
  </Step>

  <Step title="Attach the segment to a Study">
    Choose the Study you want to run, and select the Stripe segment as its Participant source.
  </Step>

  <Step title="Send Interview invites">
    Trigger the invite action. User Intuition creates an Interview invite for every Participant in the segment that has an email address. Participants without an email are skipped automatically.
  </Step>
</Steps>

<Note>
  Re-running an invite for a segment is safe — Participants who already have an outstanding invite for the same Study are not invited a second time.
</Note>

***

## Connection status

You can check the state of your Stripe connection at any time. The integration tracks where it is in the lifecycle:

| Status | Meaning |
| - | - |
| `pending` | The account is connected but the first sync has not yet started. |
| `syncing` | The Stripe app is fetching customers and cohorts in the background. |
| `segments_synced` | Cohorts have been imported; customer sync is still in progress. |
| `complete` | The initial backfill finished. Ongoing updates flow in via Stripe webhooks. |

The total number of imported Participants is also surfaced so you can confirm the sync brought in what you expect.

***

## Updates and ongoing sync

After the initial backfill, the integration is event-driven. Whenever a relevant change happens in Stripe, the Stripe app receives the webhook, validates its signature, and forwards a normalized update to User Intuition:

<Tabs>
  <Tab title="Customer changes">
    A `customer.created` or `customer.updated` event from Stripe upserts the matching Participant in User Intuition. A `customer.deleted` event is logged and the Participant is marked accordingly.
  </Tab>

  <Tab title="Subscription changes">
    Subscription create, update, and delete events update the subscription status and plan stored on the customer's Participant record, so segments based on subscription state stay accurate.
  </Tab>

  <Tab title="Disconnects">
    If the Stripe app is uninstalled from the Stripe side, an `account.application.deauthorized` event triggers cleanup of the stored access token and marks the account as disconnected.
  </Tab>
</Tabs>

***

## Disconnecting

You can end the integration from either side:

* **From User Intuition** — open the Stripe integration in the integrations area and choose to disconnect. The stored access token is removed and no further events are processed.
* **From the Stripe Dashboard** — uninstall or revoke the User Intuition app. Stripe will send an `account.application.deauthorized` event, and User Intuition will clear the stored credentials.

Disconnecting stops new data from flowing in. Participants and segments already imported into User Intuition remain available for any Study they are attached to.

<Warning>
  Reconnecting after a disconnect re-runs the initial sync. Existing Participants are matched on their Stripe customer ID and updated rather than duplicated.
</Warning>

***

## Troubleshooting

<CardGroup>
  <Card title="No customers appearing">
    If the connection succeeds but no Participants show up, check the connection status. A status of `syncing` means the backfill is still in progress; very large customer lists are paginated and processed in batches.
  </Card>

  <Card title="Stale data in segments">
    Segments are refreshed as Stripe webhook events arrive. If a recent change in Stripe is not reflected, confirm the Stripe app is still installed and that webhook delivery is healthy in the Stripe Dashboard.
  </Card>

  <Card title="Customers without email">
    Stripe customers that lack an email address are still synced, but they cannot be sent Interview invites. Add an email to the customer in Stripe and the next sync will fill it in.
  </Card>

  <Card title="Reconnecting under a different account">
    Disconnect the existing Stripe account first, then start the OAuth flow again with the new account. Mixing customers from two Stripe accounts in the same connection is not supported.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="Create a Study" icon="plus" href="/creating-a-study/overview">
    Build the Study you want to run against your Stripe customers
  </Card>

  <Card title="HubSpot integration" icon="plug" href="/integrations/hubspot">
    Sync Participants from HubSpot using the same pattern
  </Card>
</CardGroup>


# Welcome to User Intuition
Source: https://docs.userintuition.ai/introduction/welcome

User Intuition is an AI-moderated research platform. Run interviews, concept tests, and prototype tests at scale, and turn the conversations into insight you can act on.

User Intuition is an **AI-moderated research platform**. An AI moderator runs real conversations with your participants — by chat, voice, or video — and probes past the first answer to get at the reasoning underneath.

Every conversation feeds a searchable body of customer knowledge that gets more useful as it grows.

***

## What you can run

Three study types, all set up the same way:

| Study type | Use it when | What participants do |
| - | - | - |
| [**In-depth Interview**](/study-types/in-depth-interview) | You want to understand experiences, motivations, and decisions | Talk through what they did and why |
| [**Concept Test**](/study-types/concept-test) | You have an image or video you want reactions to | React to your concept and explain the reaction |
| [**Prototype Test**](/study-types/prototype-test) | You have a prototype or live site you want people to try | Work through it while narrating their thinking |

Whatever the topic — why deals are won or lost, why customers leave, what's breaking in onboarding, how a new design lands — it's one of these three.

***

## Why User Intuition

### Depth at scale

Run hundreds of interviews at once without collapsing them into a survey. The moderator adapts to each conversation and follows up on what it hears, holding 98% participant satisfaction while it does.

### Insight that compounds

Every interview feeds your organization's Intelligence Hub. What used to be buried in slide decks and people's heads becomes searchable, and each new study makes the last ones more useful.

***

## Getting started

* [Quickstart](/getting-started/quickstart) — launch your first study in about 15 minutes
* [Key Concepts](/getting-started/key-concepts) — studies, interviews, the moderator, and the Intelligence Hub
* [Interview Modes](/getting-started/interview-modes) — chat, voice, and video

***

## Need help?

* **Email:** [support@userintuition.ai](mailto:support@userintuition.ai)
* **Search:** use the bar at the top of any page


# Dashboard
Source: https://docs.userintuition.ai/managing-your-study/dashboard

Monitor your study from the dashboard: key metrics, study status, the Invites, Calls and Reports tabs, and how to invite participants.

After launching, the Study Dashboard is where you watch progress, invite participants, and reach your results.

You land here automatically after launch. To come back later, click **Dashboard** in the left navigation and pick your study.

***

## Key metrics

Four cards across the top:

| Metric | Description |
| - | - |
| **Responses** | Completed interviews |
| **Avg Length** | Average duration of completed conversations |
| **Quality** | Responses meeting quality thresholds |
| **Study Progress** | Responses collected against your target |

### Understanding quality

An interview counts toward **Quality** based on three things: whether it ran long enough to cover the ground, whether the participant gave substantive answers rather than one-word ones, and how much of your research plan the conversation actually reached.

Interviews that fall short are still recorded and still readable — they're just tracked separately, so your headline number reflects the responses you'd actually build a decision on.

***

## Study status

A badge next to your study name shows where it stands.

| Status | Meaning |
| - | - |
| **Creating** | Still being set up |
| **Launching** | Going live |
| **Queued** | Waiting to start fielding |
| **Fielding** | Actively collecting responses |
| **Complete** | Target reached |
| **Partial** | Finished short of target |
| **Paused** | Stopped by you; no new responses |
| **Cancelled** | Stopped and closed out |
| **Failed** | Something went wrong — contact support |

Panel studies show a status throughout. Studies where you bring your own participants show a badge once they're complete or paused.

***

## Tabs

### Invites

Everyone you've invited and where they've got to — email address, when the invitation was sent, and when the interview was taken. Test invites carry a **Test** badge.

Actions per row let you resend, delete, or copy that participant's invite link.

### Calls

Every completed interview, with its quality rating and end reason. Click a row for the transcript, screener responses, and summary.

<Card title="Calls & transcripts" icon="microphone" href="/results/calls-and-transcripts">
  Reviewing individual interviews in detail.
</Card>

### Reports

Synthesis across all completed interviews in the study.

<Card title="Reports" icon="chart-bar" href="/results/reports">
  Generating and interpreting reports.
</Card>

***

## Inviting participants

Click **Invite Participants**. What you see depends on the recruiting method you chose in Step 4.

| Bring your own participants | Panel |
| - | - |
| **Copy Study Link** — share it anywhere | **Copy Test Link** — try the study yourself |
| **Send Email Invites** — we email your list | **Recruit from Our Panel** — set a target and field it |
| **Copy Embed Code** — put it in your product | **Recruit a Niche Audience** — request a quote for hard-to-reach people |

The menu is disabled while a study is paused.

<Card title="Recruiting participants" icon="users" href="/recruiting/overview">
  How to choose a method, and what each one costs.
</Card>

***

## Managing the study

The **Actions** menu in the top right handles everything else — editing, duplicating, pausing, rewards, and deletion.

<Card title="Study actions" icon="gear" href="/managing-your-study/study-actions">
  View, edit, duplicate, pause, enable rewards, delete.
</Card>

***

## Real-time updates

The dashboard updates as participants finish. Metrics refresh, new responses appear in the Invites and Calls tabs, and the progress bar advances. You don't need to reload the page.

***

## Quick tips

<CardGroup>
  <Card title="Watch quality, not just volume">
    Twenty interviews with a low quality share is a study that needs a look, not a study that's nearly done.
  </Card>

  <Card title="Review the first few">
    Listen to your earliest interviews to confirm the conversation is going where you intended, while there's still time to adjust.
  </Card>

  <Card title="Track your response rate">
    Compare invites sent against calls completed. A low rate usually means the invitation, not the study.
  </Card>

  <Card title="Let it run">
    Changing questions mid-study makes early and late responses hard to compare.
  </Card>
</CardGroup>


# Study Actions
Source: https://docs.userintuition.ai/managing-your-study/study-actions

Everything in the dashboard Actions menu, and what differs between panel studies and studies where you bring your own participants.

The **Actions** menu in the top right of your study dashboard holds everything you can do to a study after it's live.

Most of it works the same either way. A few things depend on whether you're running a **panel** study or bringing in your **own participants** — including what you get charged for.

| Action | Panel studies | Your own participants |
| - | :-: | :-: |
| View Study | ✓ | ✓ |
| Edit Study | ✓ | ✓ |
| Duplicate Study | ✓ | ✓ |
| Pause / Resume Study | ✓ | ✓ |
| Delete Study | ✓ | ✓ |
| Enable Rewards | — | ✓ |

***

## Available on every study

### View Study

Opens the complete configuration — research plan, moderator voice, format, language, and screener questions — read-only.

Useful for checking what you actually asked before you interpret a result, and for sharing the design with a colleague who wasn't involved in setting it up.

### Edit Study

Reopens the setup flow so you can change the research plan, moderator, format, or screeners.

<Warning>
  **Think carefully about editing a study that's already collecting.** Changing questions or flow partway through means early and late responses aren't directly comparable, which weakens the analysis you're collecting the data for.
</Warning>

Safe at any time:

* Renaming the study
* Fixing a typo that doesn't change a question's meaning

Risky once responses are in:

* Adding, removing, or rewording questions
* Changing the interview format
* Changing the moderator voice
* Changing screener criteria

If you need substantial changes after collecting responses, **duplicate the study and edit the copy** instead. That way the first set of responses stays intact and comparable.

### Duplicate Study

Copies the entire configuration into a new study — research plan, moderator settings, screeners — without any of the responses.

Use it to run the same study with a different audience, to re-run it next quarter for comparison, or to make substantial changes without contaminating data you've already collected.

### Pause and Resume

**Pause Study** stops the study taking new responses. While paused:

* Anyone following your study link sees **"This study is no longer active"** rather than starting an interview
* The **Invite Participants** menu is disabled, and invites can't be resent
* Test conversations still work, so you can keep checking the study yourself
* Everything already collected stays exactly where it is

**Resume Study** starts it again and reopens the same links — you don't need to redistribute anything.

A study that has reached its target is **Complete**, and complete studies can't be paused — there's nothing left to stop.

### Delete Study

Permanently removes the study and everything attached to it: all interviews, transcripts, recordings, reports, and participant records.

<Warning>
  **Deletion cannot be undone.** Export anything you need first — transcripts, reports, or a generated presentation.
</Warning>

Before deleting, consider whether you'd rather **pause** it (if you might collect more later), **sync it to the Intelligence Hub** (if you want the findings to outlive the study), or just **export the report** (if you only need the conclusions).

Deleting is the right call for genuine test studies, duplicates created by mistake, and studies that never launched.

***

## Studies where you bring your own participants

### Enable Rewards

Pay your participants for completing an interview. This option only appears on bring-your-own studies — on panel studies, User Intuition handles incentives.

<Steps>
  <Step title="Open Enable Rewards">
    From the **Actions** menu. Once set, the menu item shows the current amount.
  </Step>

  <Step title="Set the amount">
    Enter a reward per participant, between **\$5 and \$500**. It's debited from your wallet when a reward is actually sent.
  </Step>

  <Step title="Choose how rewards go out">
    Tick **Automatically send rewards after quality interviews** to have them sent for you, or leave it unticked to send each one by hand from the **Calls** tab.
  </Step>
</Steps>

Rewards are only offered for interviews rated **Excellent** or **Good**, and never for test invites.

<Note>
  You need a [payment method on file](/resources/billing-and-credits#payment-methods) to send rewards. Without one, the reward button in the Calls tab is replaced by "No Card on File."
</Note>

### What you're charged for

On bring-your-own studies you're charged for interviews rated **Excellent**, **Good**, or **Fair**. Only **Poor** is free.

Fair counts here because you control who gets the link. When a participant turns out to be a poor fit or gives thin answers, that's a recruiting outcome rather than something we selected for you — the interview still ran, and the moderator still did the work.

***

## Panel studies

### No reward setup

Panel studies don't show **Enable Rewards**. Participant incentives are set and paid by User Intuition as part of the per-participant cost, so there's nothing for you to configure.

### What you're charged for

On panel studies you're charged only for interviews rated **Excellent** or **Good**. **Fair and Poor are free.**

The bar is higher here because we chose the participants. If someone we recruited only produces a Fair conversation, that's on our sourcing, not your study — so you don't pay for it.

### Stopping a fielding panel

A study can field only one panel at a time. Setting up a new one while another is fielding prompts you to stop the existing panel first.

Pausing the study also halts a fielding panel while preserving its recruitment
progress and reward authorization hold. Resuming restarts that same panel.

Stopping is final for the current panel: it closes the recruitment cycle,
settles completed rewards, and releases any unused authorization. If you try to
edit a fielding panel, choose **Pause & Edit** to continue the panel later or
**Stop & Edit** to close it out.

***

## What you're charged for, side by side

| Quality rating | Panel studies | Your own participants |
| - | :-: | :-: |
| **Excellent** | Charged | Charged |
| **Good** | Charged | Charged |
| **Fair** | Free | Charged |
| **Poor** | Free | Free |

On panel studies the **\$30 per-participant** cost follows the same rule — you're billed only on Excellent and Good completes. See [Billing and credits](/resources/billing-and-credits).

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I edit a study that's actively fielding?">
    Bring-your-own-participant studies can be edited while fielding. For a panel study, first choose **Pause & Edit** to preserve the panel or **Stop & Edit** to close it out. Changes affect only interviews that happen afterwards, so be deliberate: your dataset can contain responses collected under different configurations.
  </Accordion>

  <Accordion title="Does duplicating a study copy its responses?">
    No. You get the configuration; the new study starts empty.
  </Accordion>

  <Accordion title="Does pausing a study lose my responses?">
    No. Everything collected stays. Pausing only stops new interviews starting.
  </Accordion>

  <Accordion title="Why am I charged for Fair interviews on my own participants but not on panel?">
    Because of who chose the participant. On panel studies we did the recruiting, so a Fair conversation is our sourcing problem. On your own studies you control who receives the link, and the interview still ran either way.
  </Accordion>

  <Accordion title="Can I recover a deleted study?">
    No. Deletion is permanent.
  </Accordion>

  <Accordion title="Who can perform these actions?">
    Anyone with permission to manage the study. **View Study** is available to everyone with access.
  </Accordion>
</AccordionGroup>


# Authentication
Source: https://docs.userintuition.ai/mcp-server/authentication

Use hosted OAuth or an organization API key, including with headless hosted clients.

## Hosted OAuth (recommended first)

The User Intuition MCP server is available at:

```text theme={null}
https://mcp.userintuition.ai/mcp
```

Compatible clients discover OAuth automatically. Complete the authorization flow before testing a tool. Seeing the tool catalog alone is not proof of authentication because a client can discover tools before an account-scoped request succeeds.

Headless clients can instead send an organization API key to the same hosted endpoint in an `Authorization: Bearer ui_sk_…` header. The server validates the key and its scopes with the backend on every request, so revocation takes effect without a separate hosted MCP login. Call `get_account` to verify the effective workspace before running tools.

## stdio clients

Claude Desktop, Cursor, Claude Code, and VS Code can launch the MCP server locally. Set `USERINTUITION_API_KEY` to a key created under **Settings → API Keys**. New keys start with read access; choose write or paid-action permissions when creating one if the local agent needs them.

Keep API keys out of source control, screenshots, prompts, and shared configuration files. Rotate a key immediately if it is exposed.

## Authorization behavior

Every backend request is scoped to the authenticated account. Resource reads, updates, and deletes also perform ownership checks. A valid OAuth session or API key can still receive `403` or `404` when the requested resource is not accessible.

Platform admins with `users.role = admin` can call `list_organizations` and read public research across organizations. Pass `organization_id` to an MCP tool to select one for account-scoped reads or changes; it is required before changing another organization's study or using its wallet. Organization owner/admin membership alone does not grant this access. An admin API key still needs the tool's scopes and paid-action spend cap. See [platform admin access](/api-reference/platform-admins).

`read` permits study and result retrieval, including search and estimates. `write` permits non-paid changes. Paid `launch_panel` requires `write` and `panel:launch`; `send_participant_reward` requires `write` and `rewards:send`. Paid API keys also require a positive lifetime USD cap. The amount reserved for an uncertain paid operation continues to count against that cap until reconciled. OAuth clients must request the corresponding scopes for hosted tools. These grants allow a call, but a human still approves the plan and each spend through the tool workflow.

## External side effects

The surface includes paid panel launches, participant invitations, rewards, and completed-interview webhooks. Authentication makes those operations available; it does not replace product decisions or user confirmation. Agents must return and obtain approval of the current persisted plan before participant creation or paid launch, and respect each tool's safety annotations before spending money, sending a reward, registering a webhook, stopping recruitment, or deleting data.


# Claude directory research connector
Source: https://docs.userintuition.ai/mcp-server/claude-directory

Connect Claude to existing User Intuition studies, transcripts, and reports with a read-only MCP endpoint.

The User Intuition connector for the Claude directory gives Claude read-only access to research already available in your User Intuition workspace. Sign in with your User Intuition account through OAuth. Claude can search findings and inspect their source interviews without changing your studies or account.

## Connect

Use this remote MCP URL when adding the directory research connector:

```text theme={null}
https://mcp.userintuition.ai/directory/mcp
```

Sign in with an account that can access the studies you want to explore. The connection uses the same User Intuition login as the full MCP server, but exposes a smaller tool catalog.

## What Claude can read

| Tool | Purpose |
| - | - |
| `list_studies` | Find studies by name, status, recruiting method, date, or report availability |
| `get_study` | Read the saved research plan, audience, screeners, and concept assets |
| `get_fielding_progress` | See completed interviews, quality counts, and fielding progress |
| `get_study_report` | Read report findings, participant responses, and source references |
| `search_research` | Search indexed research across selected studies |
| `answer_research` | Answer questions across selected studies with citations to indexed sources |
| `list_interviews` | Find interview records and their status |
| `get_interview` | Read bounded pages of spoken transcript segments |

The directory connector cannot create or change studies, start interviews or recruitment, send participant rewards, generate media, or change account data. For study creation and fieldwork, use the [full MCP server](/mcp-server/overview) as a custom connection.

## Try it

* “List my studies that have reports.”
* “What did participants say about onboarding in this study? Show the interviews behind the findings.”
* “How many interviews have completed in this study, and what does its latest report say?”

Search results depend on the studies and indexes available to your authenticated workspace. If you do not see a study, check that your User Intuition account has access to it. For connection problems, see [Troubleshooting](/mcp-server/guides/troubleshooting) or contact [support@userintuition.ai](mailto:support@userintuition.ai).


# Study-creation playbook
Source: https://docs.userintuition.ai/mcp-server/guides/playbook

Create a metadata draft, conduct the Customize Plan conversation, verify the result, and field the study safely.

The MCP server keeps a short set of critical rules in its `instructions` field so clients with small instruction limits still receive them. Step-specific rules appear in the relevant tool descriptions. This page provides the full workflow. A [User Intuition Skill](/skills/overview) adds a reusable workflow on top of it.

## 1. Collect the required setup decision

Before creation, understand the research goal and ask for the missing recruiting choice:

* `recruiting_method`: `panel`, `byop`, or `synthetic_respondents`; never guess

For Panel and BYOP, `create_study` defaults to a voice interview in English with `male` voice configuration. Synthetic respondents use chat. An explicit user choice may instead set `interview_format` to `chat` or `video` where supported, choose another supported language, or choose `female` voice configuration. Chat studies also retain voice configuration; the public choice remains `male` or `female`.

Keep the study name to 40 characters or fewer. Read `userintuition://catalog/study-types` when the user needs help choosing a study type, but do not draft a plan from its internal prompts.

## 2. Create only the metadata draft

Call `create_study` with a nonblank name, the user's recruiting choice, and ordinary metadata. The MCP schema intentionally does not accept BYOP incentive settings, a study plan, expected duration, audience targeting, screener questions, concept links, or concept images.

## 3. Start the Customize Plan conversation

Call `customize_study` with the user's natural-language research brief. Include what they want to learn, who they want to interview, requested screening, and any concept link or image they want participants to see. When the client exposes an attached image as bytes or a readable local path, base64-encode the raw bytes and pass them through `concept_image` on the same call.

Pass the user's meaning through in ordinary language. Do not construct or patch `study_plan`, `targeting_attributes`, `screener_questions`, or concept objects yourself. The backend runs the same stateful Customize Plan workflow used by the dashboard, including the study type's `chat_prompt` instructions, canonical targeting selection, validation, duration calculation, conversation-flow formatting, concept checks, and plan reconciliation.

## 4. Keep the human in the loop

One `customize_study` call represents one conversation turn. Use `decisions: "human"` unless the researcher delegates ordinary research-design choices; then set `decisions: "agent"`, report `assumptions[]`, and still relay any required `questions[]`. Keep workflow constraints such as draft-only in `execution_policy`, outside the research `message`. Inspect `response_type`:

* `question`: show `questions[]` to the user, wait for their answer, then call `customize_study` again with that answer
* `study_plan` or a completion `message`: continue to verification

In human mode, never answer a Customize Plan confirmation yourself. Agent mode covers research-design assumptions only. Client permission settings do not replace a required recruiting choice, plan approval, or paid-launch approval.

## 5. Handle audience and screening through chat

Describe audience requirements naturally. Customize Plan should use existing targeting attributes when they fit criteria such as age or household income, and create custom screener questions only when canonical targeting cannot express the requirement or the user explicitly needs one.

Never add recording-consent or willingness-to-participate screeners. The platform handles consent separately.

## 6. Handle concepts through chat

Send concept-link and concept-image requests through `customize_study`. When the client exposes an attachment's bytes or a readable local path, base64-encode the raw image and pass it through the optional `concept_image` input with its filename, MIME type, and the user's participant-facing label. Public image URLs remain supported in the conversation message. If the client exposes only an opaque attachment reference with no readable bytes, path, or public URL, explain that client limitation and offer the available upload routes. Never request login credentials.

The backend owns URL safety, embeddability, login detection, recorder compatibility, file validation, storage, deduplication, IDs, mode compatibility, and plan reconciliation.

Studies with concept links cannot use chat interviews. Relay the backend's question or validation result and let the user choose voice or video.

## 7. Verify the persisted study

Call `get_study` after customization. Return the complete persisted study plan in a readable form, together with the audience, screeners, concepts, interview settings, and `provisioning_status`. Ask the user to approve that exact plan or request revisions. Do not replace the plan with a short summary or only a dashboard link.

Send requested revisions back through `customize_study`, fetch the study again, and return the complete revised plan. Approval of an earlier version does not cover a revised plan. Client permission settings, approval to create a draft, answers to Customize Plan questions, and approval of a cost estimate do not count as study-plan approval.

Only create BYOP participants or launch a paid Panel study when `provisioning_status` is `provisioned` and the user has explicitly approved the current returned plan. If the result is incomplete, continue through `customize_study` rather than filling designed fields through another tool.

## 8. Field safely

For BYOP, call `create_participants` only after provisioning and plan approval. Poll `get_participant_job` to completion, then list the invitations.

For Panel recruitment:

1. Ask the user to choose the launch country explicitly. Each `launch_panel` call fields exactly one country; never infer a country from a broad region such as Europe or Asia.
2. Verify that country/language combination with `userintuition://catalog/panel-countries`.
3. Use `submit_feasibility_request` when incidence is below 10% or the audience requires specialist review.
4. Call the read-only `estimate_panel` with the explicit `country_code`.
5. Show the resolved country, language, cost, and heuristic timeline; retain `estimate_id`.
6. Confirm the user has approved the current returned plan.
7. Wait for explicit approval of that complete estimate before calling `launch_panel` with its `estimate_id` and the same country. Obtain a new estimate if it expires or relevant inputs change.

For multi-country research, ask the user to select one launch country or create separately reviewed and approved country-specific studies or launches. A multi-country Learning Plan does not turn one Panel launch into multi-country recruitment.

## 9. Read before metadata updates

Call `get_study` before `update_study`, and `get_participant` before `update_participant`. `update_study` is for ordinary metadata only; route designed-content changes back through `customize_study`.

A fielding Panel study must be paused or stopped before editing. Pause if recruitment should resume; stop when fieldwork is over.

## 10. Confirm external and destructive actions

Require explicit confirmation before a paid launch, reward, webhook registration, stop, study deletion, or interview deletion. Treat tool annotations as authoritative.

`create_webhook` returns its signing secret once. Tell the user to store it securely without repeating the value.


# Screening respondents
Source: https://docs.userintuition.ai/mcp-server/guides/screening

Describe audience criteria naturally and let Customize Plan choose canonical targeting or custom screeners.

## One conversation for audience design

Use `customize_study` for both Panel targeting and custom screener questions. Tell it whom the user wants to interview in ordinary language; do not translate the request into qualification IDs or question schemas in the MCP host.

The backend runs the same Customize Plan workflow as the dashboard. It can match criteria such as age or household income to existing targeting attributes, ask the user to confirm choices, and add a custom screener only when appropriate.

## Continue questions with the user

If `customize_study` returns `response_type: "question"`:

1. Relay the returned `questions[]` to the user.
2. Wait for their decision.
3. Call `customize_study` again with their answer in ordinary language.

In `decisions: "human"` mode, do not answer for the user or convert their answer into MCP-side targeting or screener fields. Use `decisions: "agent"` only when the researcher delegated ordinary research-design choices; any remaining required `questions[]` still need the researcher.

## Screening rules

* Do not add screening the user did not request.
* Never add recording-consent or willingness-to-participate questions; the platform handles consent separately.
* Explain likely recruitment tradeoffs when Customize Plan identifies restrictive criteria.
* After the conversation completes, call `get_study` and show the persisted targeting and screeners to the user.

## Safe updates

Use `customize_study` again when the user wants to add, change, or remove audience criteria or screener questions. `update_study` is for ordinary metadata and intentionally does not accept these designed fields through MCP.

A fielding Panel study must be paused or stopped before its configuration can change.


# Study setup
Source: https://docs.userintuition.ai/mcp-server/guides/study-modes

Choose recruiting method, use sensible interview defaults, and select the appropriate study type before entering Customize Plan.

## Recruiting method

| Value | Use when | Recruitment tool |
| - | - | - |
| `panel` | User Intuition should recruit respondents | `launch_panel` |
| `byop` | The user has their own participant list | `create_participants` |
| `synthetic_respondents` | The user requests AI respondents | Chat interviews; no participant recruitment |

Ask the user when the choice is not explicit. Do not infer it from the research topic.

## Interview format

For Panel and BYOP, `create_study` defaults to `voice` when the user does not specify a format. Synthetic respondents use chat. Set `interview_format` to `chat` or `video` only when the user requests it and the recruiting method supports it. Read `userintuition://catalog/modes` for discovery when needed.

Concept links are incompatible with chat interviews. Send the concept request through `customize_study` and relay its question so the user can choose voice or video.

## Language and voice

Omitted settings default to English (`en`) and `male` voice configuration. Read `userintuition://catalog/languages` when the user requests another language; the catalog includes lowercase language codes and `auto` for automatic detection. The public voice choice is `male` or `female` only, including for chat studies. `userintuition://catalog/voices` provides display names without implementation details.

## Study type and plan

Public writes accept `study_type: "in-depth-interview"`, `"concept-test"`, or `"prototype-test"`. The default is `in-depth-interview`. A prototype test cannot use chat; it uses the default voice format or an explicitly requested video format. `userintuition://catalog/study-types` and `userintuition://catalog/study-types/{slug}` can explain the available planning templates, but the MCP host must not build the plan from internal prompt fields.

Create the metadata draft, then send the user's brief to `customize_study`. The backend applies the study type's current `chat_prompt` instructions and persists the resulting plan, duration, audience, screeners, and concept material.

## Concept material

Describe links and images in the `customize_study` conversation. For an image attachment that the client exposes as bytes or a readable local path, the agent can send the base64-encoded bytes through `customize_study.concept_image`; no public URL is required. A public downloadable URL and label can still be supplied in the message.


# Troubleshooting
Source: https://docs.userintuition.ai/mcp-server/guides/troubleshooting

Resolve authentication, stale package, missing-tool, and backend-domain errors.

## 401 Unauthorized

For hosted Streamable HTTP, confirm the client is connected to `https://mcp.userintuition.ai/mcp`, then reconnect OAuth from the client.

For stdio, confirm `USERINTUITION_API_KEY` is visible to the process that launches the MCP server and starts with `ui_sk_`. Create or rotate keys under **Settings → API Keys** at [app.userintuition.ai](https://app.userintuition.ai). A valid credential can still receive `403` or `404` for a resource the account does not own.

## An older tool surface appears

The current server identifies itself as **User Intuition** and exposes 50 tools. Its queued study-design entry point is `queue_customize_study`, and its research entry points are `search_research` and `answer_research`. A connector is stale if it identifies itself as **User Intuition Human Signal**, reports 38 tools, offers `ask_humans` or retired direct-design tools such as `create_study_and_launch_panel`, `replace_study`, or `upload_concept_link`, or returns a tool-not-found error for a current name such as `list_targeting_attributes`.

In ChatGPT, remove the old custom connector, create it again with `https://mcp.userintuition.ai/mcp`, complete OAuth, and start a new chat. Confirm that `customize_study` is available and `ask_humans` is not before attempting a study. Reauthorizing without recreating the connector may leave its cached tools unchanged.

For local stdio clients, if you see legacy names such as `create_panel`, `create_invite`, or `list_calls`, restart the client and force a fresh package:

```bash theme={null}
npx -y @userintuition-ai/mcp@latest
```

Most clients load tool definitions only when a connector or session starts. Recreate the hosted connector when reauthorization alone leaves stale names, or restart the stdio client, then start a new chat or task. Do not ask for a removed tool to be restored: use the current tool named in the [tool reference](/mcp-server/tools/studies).

## A tool returns a domain error

Not every non-success response is an authentication problem. Examples include:

* report generation on a study with no usable interviews
* reward delivery for an ineligible or unknown participant
* direct Panel launch below 10% incidence
* editing a fielding Panel study before pausing or stopping it

Read the returned error and use the corresponding lifecycle or feasibility action. Do not reconnect OAuth or regenerate an API key for a valid `400`, `403`, `404`, or `409` domain response.

Invalid tool inputs return `validation_error` with a `correct_input` hint. If a report has not been generated, `no_report_yet` points to `generate_report`; if the study has no completed interviews, `no_completed_interviews` points to finishing interviews first. A `404` for an interview or study means that resource could not be found or accessed. Check its public ID and account access before retrying.

## A study plan change does not appear

Use `customize_study` for the plan, expected duration, audience, screeners, and concept material. Continue the conversation whenever it returns `response_type: "question"`, then call `get_study` to verify the persisted result. `update_study` is only for ordinary metadata. If a Panel study is actively fielding, call `pause_study` or `stop_study` before editing.

## Getting help

Email [support@userintuition.ai](mailto:support@userintuition.ai) with the tool name, timestamp, response status, and a redacted error message. Never send your API key or webhook signing secret.


# User Intuition MCP Server
Source: https://docs.userintuition.ai/mcp-server/overview

Give an AI agent the tools and rules to design studies, recruit participants, manage interviews, and analyze findings.

User Intuition's MCP server exposes the complete research workflow to AI agents: **50 tools on every transport**, covering the versioned public API plus account context, catalogs, interview usage, and a read-only study review app.

## MCP tools and Skills

The MCP server gives an agent the **tools**. A User Intuition Skill gives it the **workflow**: when to ask for Panel versus BYOP recruitment, how to conduct the Customize Plan conversation, when to dry-run cost, and when confirmation is required.

<CardGroup>
  <Card title="Connect the MCP server" icon="plug" href="/mcp-server/quickstart">
    Configure Claude, Cursor, VS Code, or ChatGPT and verify the connection.
  </Card>

  <Card title="Install a research Skill" icon="wand-magic-sparkles" href="/skills/overview">
    Teach your agent a repeatable study-creation or analysis workflow.
  </Card>
</CardGroup>

## One surface on every transport

For read-only exploration in Claude's directory, use the separate [Claude directory research connector](/mcp-server/claude-directory).

* **Streamable HTTP** accepts OAuth for interactive clients and organization API keys for headless clients. Connect to `https://mcp.userintuition.ai/mcp`.
* **stdio** remains available for Claude Desktop, Cursor, Claude Code, VS Code, and other local clients. It authenticates with a `ui_sk_` API key.

Both transports expose the same 50 tools. Choose the authentication method that fits the client.

### Smaller profiles

For the common study → interview → report workflow, connect to `https://mcp.userintuition.ai/core/mcp` (33 tools). It omits webhook, feasibility, external-panel, and platform-admin administration. For existing research without write actions, connect to `https://mcp.userintuition.ai/read-only/mcp` (25 tools). The `https://mcp.userintuition.ai/compact/mcp` profile keeps the research workflow and groups less common webhook, feasibility, and external-panel operations into 41 tools. Each URL has its own OAuth protected-resource metadata, so authorize the specific URL your client uses. The full `/mcp` URL remains available for all 50 tools.

Local stdio clients can pass `--profile core`, `--profile read-only`, or `--profile compact` after the package name. The default is the full profile. Resource and prompt support remains available on these profiles.

Measured from the complete `tools/list` response in the cited-answer and cursor MCP change set:

| Profile | Tools | Payload bytes | Approx. tokens |
| - | -: | -: | -: |
| Full | 50 | 121,538 | 30,385 |
| Core | 33 | 88,649 | 22,162 |
| Read-only | 25 | 67,216 | 16,804 |
| Compact | 41 | 106,850 | 26,713 |
| Directory | 8 | 31,752 | 7,938 |

The token estimate divides bytes by four; actual model context usage varies by host and tokenizer. CI checks each profile against its payload budget.

## Tool groups

| Group | Tools | What it covers |
| - | -: | - |
| Account | 2 | Effective workspace, payment readiness, and platform-admin organization search |
| Studies | 20 | Create, customize, review, estimate, launch, pause, stop, report on, search, and answer questions across studies |
| External panels | 4 | Configure a customer-supplied panel bridge for a BYOP study |
| Participants | 7 | Create and manage BYOP invitations and rewards |
| Interviews | 4 | Read or delete interviews and inspect usage |
| Panel feasibility | 4 | Specialist feasibility review |
| Webhooks | 8 | Create, inspect, test, and remove event subscriptions |
| Configuration & catalogs | 1 | Targeting attributes; other catalogs are MCP resources |

The [tool reference](/mcp-server/tools/studies) documents every registered tool. The [study-creation playbook](/mcp-server/guides/playbook) documents the behavioral rules agents should follow.

The server also exposes [attachable study and report resources](/mcp-server/research-resources) for clients that show MCP resources in the conversation. These resources read the same authenticated public API as the research tools.

## Safety model

The server advertises MCP safety annotations for every tool. Agents should also follow these product rules:

1. Use `customize_study` for the plan, audience, screeners, and concept material; do not reconstruct those fields in the MCP host.
2. Return the complete persisted study plan and obtain approval of its current version before creating BYOP participants, sharing an external-panel entry link, or launching paid Panel recruitment.
3. Use `estimate_panel`, show the complete estimate, and carry its `estimate_id` into an approved paid panel launch.
4. Require explicit user confirmation before rewards, webhooks, stopping fieldwork, or deleting studies, participants, or interviews.

## Runnable developer examples

Use the [developer examples](/api-reference/developer-examples) to inspect study execution, report retrieval, and evidence search. The public repository includes fictional no-spend fixtures, a matching MCP/CLI walkthrough, and release compatibility notes.

## Agent homepage

Start at [research.userintuition.ai](https://research.userintuition.ai/) for the three research workflows, connection options, machine-readable guidance, and public examples. This documentation remains the detailed operation reference.


# Quickstart
Source: https://docs.userintuition.ai/mcp-server/quickstart

Connect with hosted OAuth first, or use the local stdio setup for Claude Desktop, Cursor, Claude Code, and VS Code.

## 1. Choose a connection

Use the hosted Streamable HTTP endpoint with OAuth when your client supports it:

```text theme={null}
https://mcp.userintuition.ai/mcp
```

The client discovers OAuth automatically. Sign in and authorize User Intuition when prompted.

For a smaller catalog, use `https://mcp.userintuition.ai/core/mcp` for the 33-tool research workflow, `https://mcp.userintuition.ai/read-only/mcp` for 25 read-only tools, or `https://mcp.userintuition.ai/compact/mcp` for 41 tools with grouped administrative operations. Authorize each endpoint separately. The full URL above retains all 50 tools. Local stdio clients can append `--profile core`, `--profile read-only`, or `--profile compact` to the server command.

To try study design and reports in staging, connect to `https://mcp.sandbox.userintuition.ai/mcp` with a staging account. Follow the [sandbox quickstart](/api-reference/staging-quickstart) for Test with AI, three synthetic responses, and the participant-link limitation.

Local stdio remains supported for clients that need a local process. Create a key under **Settings → API Keys** at [app.userintuition.ai](https://app.userintuition.ai). Keys start with `ui_sk_`.

## 2. Connect your client

<Tabs>
  <Tab title="ChatGPT">
    In ChatGPT, enable developer mode under **Settings → Apps & Connectors → Advanced**, then create a connector:

    * **MCP Server URL:** `https://mcp.userintuition.ai/mcp`
    * **Authentication:** OAuth (auto-discovered)

    If you previously connected the old **User Intuition Human Signal** server, remove that custom connector and create it again. Existing connectors can retain obsolete tools after the server is upgraded.
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add userintuition --url https://mcp.userintuition.ai/mcp
    codex mcp login userintuition
    ```

    The add command may start OAuth immediately. If it does, complete that flow; the separate login command is only needed when authorization is still pending. Restart Codex or open a new task after setup so it loads the tool catalog.
  </Tab>

  <Tab title="Claude Desktop">
    Add this server to `~/Library/Application Support/Claude/claude_desktop_config.json`, then fully restart Claude Desktop:

    ```json theme={null}
    {
      "mcpServers": {
        "userintuition": {
          "command": "npx",
          "args": ["-y", "@userintuition-ai/mcp@latest"],
          "env": {
            "USERINTUITION_API_KEY": "ui_sk_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Add the same `mcpServers` entry to `.cursor/mcp.json`, replace the example key, and restart Cursor.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add userintuition -- npx -y @userintuition-ai/mcp@latest
    ```

    Make `USERINTUITION_API_KEY` available to the environment that launches Claude Code. Do not commit the key to your repository.
  </Tab>

  <Tab title="VS Code">
    Add the server command and environment variable under `"mcp.servers"` in `.vscode/settings.json`, then reload the window.
  </Tab>
</Tabs>

## 3. Verify the connection

Ask your client:

> List my User Intuition studies.

The agent should call `get_account`. A successful account-scoped response confirms authentication; merely seeing tool names does not. The current surface contains 50 tools, including `queue_customize_study`, `review_study`, `search_research`, and `answer_research`, and excluding `ask_humans`.

## 4. Give the agent a workflow

Connection proves the tools work. A Skill tells the agent how to use them reliably.

Install the [create-study-from-brief Skill](/skills/create-study-from-brief), then ask the agent to use it. The Skill adds the question order, readiness checks, plan review, and approval gates needed for a safe study-creation flow.

<CardGroup>
  <Card title="Install the Skill" icon="wand-magic-sparkles" href="/skills/create-study-from-brief">
    Add the reusable study-design workflow to your AI client.
  </Card>

  <Card title="Read the MCP playbook" icon="list-check" href="/mcp-server/guides/playbook">
    Understand the workflow rules already advertised by the server.
  </Card>
</CardGroup>

After installing the Skill, try:

> Use the create-study-from-brief Skill to help me design a Panel study about why trial users do not activate. Dry-run the panel cost, but do not launch without my confirmation.

For a healthy end-to-end run, the agent should keep the study name to 40 characters, ask you to choose the recruiting method when it is missing, create a metadata draft, and pass your research brief to `queue_customize_study`. Poll `get_customize_study_job` until it succeeds and read its `result`; use synchronous `customize_study` for a native concept image. Omitted interview settings default to an English voice interview with Elliot. The default `decisions: "human"` relays `questions[]` to you. If you delegate research-design choices, `decisions: "agent"` lets the planner proceed with assumptions and report them back; remaining required questions still come back in `questions[]`. The agent must then call `get_study`, return the complete persisted plan for review, and obtain approval of that exact version before creating BYOP participants or launching paid Panel recruitment. A Panel launch also requires an explicit single country and separate approval of its estimate.

Public API MCP tools return full JSON in `structuredContent.result`; supplemental tools use `structuredContent` directly. Text content is a short summary. Clients that cannot read structured results can set `MCP_FULL_TEXT_RESULTS=true` in their local server environment.

## Troubleshooting

If the tools are missing after hosted OAuth setup, restart the client or start a new chat/task. For stdio, restart the client and force a fresh package download with `npx -y @userintuition-ai/mcp@latest`. See [Troubleshooting](/mcp-server/guides/troubleshooting) for authentication and cache checks.


# Attach studies and reports
Source: https://docs.userintuition.ai/mcp-server/research-resources

Use authenticated MCP resources to bring saved research into a conversation.

Clients that support MCP resource attachments can add a saved study or its latest report to a conversation. The server lists the 20 most recently updated studies and the 20 most recently updated studies with reports that the current credential can access. Use a resource URI directly for an older study.

| Resource URI | Contents |
| - | - |
| `userintuition://study/{study_id}` | Saved study settings, plan, screeners, and targeting |
| `userintuition://report/{study_id}` | Latest report overview |
| `userintuition://report/{study_id}/{view}` | One named section of the latest report |
| `userintuition://events/{study_id}` | Recent `study.completed` and `report.ready` event envelopes, when live events are enabled |

For `{view}`, use `overview`, `study_findings`, `participant_profiles`, `participant_responses`, `evidence_coverage`, `recommended_next_steps`, or `references`. The `full` report view is not offered as an attachment. Use `get_study_report` when you need the entire report or when a section is too large to attach.

Resources use the same authorization and workspace checks as the public study and report endpoints. Hosted OAuth access requires the `read` scope. An unavailable or ungenerated report returns the public API error. Attachments are capped at 64 KiB; a larger response contains a `resource_too_large` pointer instead of partial research data.

If your client does not expose resource attachments, call `get_study` or `get_study_report` with the same study ID.

## Listen for study and report changes

Clients that support the MCP 2026-07-28 `subscriptions/listen` method can subscribe to a study, report, or events URI above. The hosted server checks access to the study before opening the stream. When a study completes or its report becomes ready, the server sends `notifications/resources/updated` for the affected study or report and for the events resource. Read `userintuition://events/{study_id}` to see the event ID, type, study ID, and data. The event envelope matches the webhook payload, so an integration can use webhooks while a chat client listens for the same milestones.

The events resource retains the latest 100 envelopes for 24 hours. A listen stream closes after 25 minutes by default; reconnect to keep receiving updates. Set `MCP_EVENT_REDIS_URL` on the backend to the same Redis instance as the MCP service's existing `REDIS_URL`. Webhooks continue to deliver independently. Clients without listen support can use the existing polling tools and webhooks.


# Account context
Source: https://docs.userintuition.ai/mcp-server/tools/account-context

Check the active workspace and payment readiness before account-scoped or paid work.

| Tool | Description |
| - | - |
| `get_account` | Read the effective organization or personal workspace, role, available credits, payment method readiness, and incentive limits |
| `list_organizations` | Platform admins: search by organization name, active owner name, or owner email; return IDs, names, and owner contacts |

Call `get_account` when the agent needs to know which workspace its credential can access. The returned `app_id` and `organization_id` describe the scope applied by the backend. An ordinary API key is scoped to its organization; a session uses the active account context.

Platform admins can use `list_organizations` with optional `search` and pass an `organization_id` to `get_account` or another public API tool. The search runs before pagination. The `owners` list can contain multiple active owners or be empty. Confirm the matched organization with the human before using its ID for a consequential action. Use the selected organization for writes and paid actions in another organization; the key's scopes and spend cap still apply. Organization owner/admin membership does not grant platform-wide access.

`billing.available_credits` is a count of credit units after pending transactions, not an amount of USD. `billing.available_balance_usd` is their value at the account's current conversion rate when the wallet is denominated in USD; it is `null` when no reliable conversion is available. `payment_method_on_file` says only whether a method is saved. None of these fields approves a paid action or guarantees that a particular launch can be funded. Show the current estimate and obtain the user's approval before spending.


# Panels and external-panel integrations
Source: https://docs.userintuition.ai/mcp-server/tools/integrations-panels

Feasibility tools, paid panel guidance, and a customer-supplied panel bridge for BYOP studies.

| Tool | Description |
| - | - |
| `submit_feasibility_request` | Submit a low-incidence or specialized audience for manual review |
| `list_feasibility_requests` | List the account's feasibility requests newest-first |
| `get_feasibility_request` | Fetch one request and its status or estimate |
| `cancel_feasibility_request` | Withdraw a request that is still pending |

## Bring Your Own Panel

This is a provider integration for a **BYOP study**, distinct from adding individual participants with `create_participants`. The external provider sends respondents through an entry URL with its respondent ID. User Intuition records each session and redirects the respondent to the provider's completion or screen-out URL when the interview ends. It does not launch or charge for User Intuition's paid panel.

| Tool | Description |
| - | - |
| `get_external_panel` | Read the configured entry URL, ID parameter mapping, and outcome redirects |
| `configure_external_panel` | Create or replace the configuration for one BYOP study |
| `regenerate_external_panel_token` | Issue a new entry URL and immediately invalidate the old one |
| `delete_external_panel` | Disable the entry URL; existing interviews remain |

Create and customize a study with `recruiting_method: "byop"`, then use `get_study` to confirm it is provisioned and review the current plan. `configure_external_panel` requires absolute HTTP(S) completion and screen-out redirect URLs. You can also set the provider's respondent ID query parameter and placeholder, session and external study ID mappings, and quota-full or technical-failure redirects. The response includes `entry_url`; have the human verify the plan, parameter mapping, and redirects before giving that link to the provider. Changing the configuration with the same PUT keeps the entry token. Token regeneration changes the URL, so the provider must receive the replacement link before the old one is used again. Use a fresh `idempotency_key` for each regeneration and reuse it if its result is uncertain.

For the same operations over REST, see [External panels](/api-reference/external-panels).

## Before a panel launch

1. Call `get_study` and confirm `recruiting_method` is `panel`.
2. Return the complete persisted plan, audience, and screeners from `get_study`; obtain explicit approval of that exact version.
3. Ask the user to choose the launch country explicitly. One `launch_panel` call fields exactly one country; it cannot field a region or a list of countries.
4. Read `userintuition://catalog/panel-countries` and verify that the country supports the study's language. If your client cannot read MCP resources, use the authenticated `GET /api/public/v1/panel-countries/` endpoint.
5. Call `estimate_panel` with that `country_code`; show the resolved country, language, cost, and heuristic timeline.
6. Call `launch_panel` with the returned `estimate_id` and the same country to review the saved plan and current estimate. This first call does not spend. In clients advertising MCP Apps support, the human approves with the App button. In other clients, show the complete saved plan as Markdown and the estimate as readable amounts, ask for explicit human confirmation, then call `launch_panel` again with the same inputs, returned `chat_approval_nonce` and `human_confirmed: true`.
7. The review is short-lived and single-use, bound to the credential, organization, study version and estimate. Changed inputs, an expired quote or a changed saved plan require fresh review and human confirmation. After an uncertain response, read `get_study` before any further action; do not automatically create a new approval to retry. Client tool permissions and approval of an earlier plan do not count.

The chat fallback relies on the model obtaining genuine human confirmation; the server cannot independently prove who supplied it. Clients advertising App support must use the human button. No dashboard approval is involved.

For a brief that names multiple countries, ask the user to select one country or create separately approved country-specific studies or launches. Never allow an omitted country to silently become a different market.

Direct launch requires `incident_rate >= 10`. Use `submit_feasibility_request` for lower-incidence or specialized audiences. A feasibility request is a persistent manual-review record; use `cancel_feasibility_request` to withdraw it while pending.

Feasibility request status is `received`, `responded`, or `cancelled`. Only a pending request can be cancelled. Panel country responses use uppercase country codes and lowercase language codes; use a lowercase code such as `en` to filter by language.

Describe audience criteria in ordinary language through `customize_study`. The backend matches suitable criteria such as age or household income to canonical targeting attributes and decides when a custom screener is needed. Targeting attributes are not accepted by `launch_panel` through MCP.


# Interviews
Source: https://docs.userintuition.ai/mcp-server/tools/interviews

4 MCP tools for reading and administering interview records.

Use product terminology in user-facing conversation: an interview is the completed or in-progress research session. Some supplemental responses may retain legacy backend field names.

| Tool | Description |
| - | - |
| `list_interviews` | List lightweight interviews by study, participant, status, or quality |
| `get_interview` | Fetch metadata, a page of spoken messages, recording links, and screener responses |
| `delete_interview` | Soft-delete an interview owned by the authenticated user |
| `get_interview_usage_stats` | Aggregate interview counts and units over a date range |

All four tools use the versioned public API; use `daily`, `weekly`, or `monthly` for its cadence. It reports eligible non-test interview counts and billed units for the selected app, not every interview or interview duration. If `app_id` is omitted, the backend resolves the default app. Missing dates use the 30-day range ending today. The response's `scope` records the applied app, dates, and cadence, including when totals are zero.

Use `total_interviews` and each bucket's `interviews`, `audio_interviews`, `video_interviews`, and `chat_interviews` fields. The older count aliases are no longer returned.

## Working with results

Use `list_interviews` for discovery and `get_interview` for evidence. Filter `list_interviews` by `participant_id` to see one participant's interviews; this is the BYOP invitation ID, not a legacy call identifier. You can combine it with `study_id`. Status accepts `pending`, `started`, `live`, `completed`, `ended`, `failed`, or `cancelled`. Quality accepts `Excellent`, `Good`, `Fair`, or `Poor` case-insensitively. Invalid filters return an error. List rows omit transcripts and exclude test or hidden interviews before counting and paging.

`participant_source` is `byop`, `panel`, `external_panel`, `link`, or `unknown`. Anonymous sources have `participant: null`, so fabricated addresses are not presented as contactable people. For BYOP, `participant.id` is the invitation ID, not a unique person ID. `ended_because` uses `completed`, `participant_left`, `time_limit`, `technical_error`, or `screened_out`; it is null when the stored reason cannot be classified.

`get_interview` requires the public `interview_id`. It returns up to 100 spoken transcript segments per request, stopping near 20 KB of transcript text. Start with `message_offset: 0` and follow `next_message_offset` until it is null; `message_limit` accepts 1–100 and defaults to 50. Each segment is at most 1,500 characters and includes its original turn `id`, speaker role, and `text_offset`. When the source has recording timing, segments include `start_s` and `end_s` in seconds from the interview start. Historical untimed messages omit these fields. The response includes `total_message_segments`. System prompts and tool messages are excluded.

Use `generate_report` and `get_study_report` from the Studies group for cross-interview analysis.

## Deletion

`delete_interview` is destructive and should only be called when the user explicitly asks to delete a specific interview. There is no public `update_interview` or quality-override tool. Do not imply that an agent can hide, relabel, or bulk-delete interviews.


# Participants
Source: https://docs.userintuition.ai/mcp-server/tools/participants

7 MCP tools for creating and managing BYOP invitations and rewards.

The public participant resource represents a BYOP invitation and its progress, not a deduplicated person. One person can take more than one interview. Panel, external-panel, and open-link respondents are anonymous interviews rather than public participant records.

`list_participants` applies an exact, case-insensitive email filter. An exact `external_id` filter is also available when `study_id` is supplied. Test and panel invitations are excluded before `total_count` and pagination are calculated. Each record has a personal `interview_link`, `status`, and `interview_count` of visible non-test sessions. Status is `created` when no email was sent, then `invited`, `started`, `completed`, or `screened_out`. A silent invitation starts as `created` but still has a personal link. Use the returned participant ID as `list_interviews.participant_id` to page through its interviews; the count is sessions, not unique people.

| Tool | Description |
| - | - |
| `list_participants` | List participants by study, exact email, or study-scoped customer ID |
| `create_participants` | Queue 1–100 unique participants for one BYOP study |
| `get_participant_job` | Poll batch status before listing invitations |
| `get_participant` | Read invitation status, personal link, interview count, and reward state |
| `update_participant` | PATCH the email, customer ID, or metadata after verifying the invitation |
| `delete_participant` | Soft-delete a BYOP invitation, with a separate guard for linked interviews |
| `send_participant_reward` | Send the configured BYOP incentive |

## Creating participants

`create_participants` accepts a `study_id` and a `participants` array. Email addresses must be unique case-insensitively. Each participant supports `silent: true` to create the record without sending an invitation email. The call returns a durable job ID; poll `get_participant_job` until it succeeds, then use `list_participants` to retrieve the invitations. If a worker stops mid-batch, the job retries missing participants without resending existing invitations.

Each participant may also carry an `external_id` from your CRM and a `metadata` object. An external ID is unique among active BYOP invitations **within the study**; the same ID may be used in another study. A batch cannot repeat an external ID. Metadata accepts at most 20 keys, scalar values only, keys up to 64 characters, strings up to 256 characters, and 4 KiB total. These fields are returned by participant reads and lists. An existing email with different CRM fields produces a conflict during a retry; inspect the invitation before changing it. Do not put secrets in metadata.

Create and finish the study first. Call `get_study`, return the complete persisted plan to the user, and obtain explicit approval of that exact version. Only call `create_participants` after the study is provisioned and the current plan is approved. Approval to create a draft or answer Customize Plan questions is not plan approval.

## Updates and rewards

Call `get_participant` before `update_participant`. Supply only fields to change: `email`, `external_id`, or `metadata`. Send `email: null` only when the user wants to clear the email; `external_id: null` clears the customer ID. Metadata replaces the whole metadata object. Rewards are BYOP-only and can have a real financial side effect. Call `send_participant_reward` only after the user explicitly asks and after confirming the participant is the intended recipient. The backend prevents duplicate payment for an already-paid participant. Pass `idempotency_key` and reuse the same key and participant ID after an uncertain response; check the participant reward state before starting a separate operation.

`delete_participant` requires an explicit user request. If the invitation has interviews, deletion returns a conflict. Only set `cascade_interviews: true` after the user separately approves deletion of those interviews; the database soft-deletes them with the invitation.


# Studies
Source: https://docs.userintuition.ai/mcp-server/tools/studies

20 MCP tools for creating, customizing, reviewing, fielding, reporting on, and searching studies.

Studies are the central research object. The 20 tools below use the public API for study data; `review_study` presents that data as a read-only MCP App in supported clients.

| Tool | Description |
| - | - |
| `list_studies` | List study summaries with filters and report availability; use `get_study` before a write |
| `create_study` | Create a Panel, BYOP, or synthetic respondent metadata draft |
| `customize_study` | Send one natural-language turn to the dashboard's stateful Customize Plan conversation |
| `queue_customize_study` | Queue a planning turn and return a durable job ID; use this for text and public image URLs |
| `get_customize_study_job` | Poll the queued planning turn until it succeeds or fails |
| `get_study` | Fetch the complete study plan, screeners, and targeting |
| `review_study` | Open the saved plan and fielding progress in a read-only MCP App; other clients receive the study data as text |
| `update_study` | PATCH ordinary metadata only; use `customize_study` for designed content |
| `delete_study` | Soft-delete a study and linked records from normal reads; no public restore endpoint |
| `estimate_panel` | Get a read-only panel cost and timing estimate with an expiring estimate ID |
| `launch_panel` | Review a saved plan and current panel quote; approve through the App or explicit human chat confirmation in clients without Apps |
| `pause_study` | Pause recruitment while preserving progress and the reward hold |
| `resume_study` | Resume preserved panel recruitment |
| `stop_study` | End recruitment and settle or release its hold |
| `generate_report` | Queue analysis of completed interviews and return a job ID |
| `get_report_job` | Poll report generation status before fetching the result |
| `get_fielding_progress` | Compare qualifying completions with target, quality mix, and estimated finish |
| `get_study_report` | Fetch the latest report, canonical JSON sections, call-linked citations, interview count, and stale status |
| `search_research` | Search indexed study/report content and return only canonical API JSON |
| `answer_research` | Answer across selected studies with numbered citations to accessible canonical research records |

## Review study

`review_study` cannot approve a plan or start recruitment. Review the persisted study version and obtain explicit approval before any participant creation or paid launch.

## Structured reports and search

`generate_report` returns a durable job. Poll `get_report_job` until it succeeds, then call `get_study_report`. `get_fielding_progress` reports current target-cycle completions and quality counts; expected finish is null until a rate estimate is supportable.

Reports use schema `report-v2`. The default `view: "overview"` returns report identity, freshness, counts, a short summary, and `available_sections`. Set `view` to `study_findings`, `participant_profiles`, `participant_responses`, `evidence_coverage`, `recommended_next_steps`, or `references` to fetch one section; use `full` only when all sections are needed. `included_sections` distinguishes omitted sections from sections that are present but empty. The complete saved interview-ID list is included only in `full`.

`study_findings.learning_goals` nests each finding under its Learning Goal and gives it a stable `finding_id`. Explicit frequency becomes `prevalence: { n, of }`, and resolvable source quotes become `quotes[]` with `reference_id`, `interview_id`, `turn_id`, and `start_s` when timing was stored. Missing evidence stays null or empty on older reports. `participant_profiles` is an array keyed by a stable `question_id` derived from the question heading; its `content` is an array of `{ answer, participants, percentage }`. Use `references` and public `interview_id` to inspect source evidence.

`search_research` searches 1–20 study IDs and optionally filters by content type or research date. It can retrieve `study_plan`, `study_finding`, `participant_profile`, `participant_response`, and `recommended_next_step` objects. Search ranks candidates, but the tool discards generated prose and returns the exact canonical JSON stored by the Study/Report APIs. Results are grouped in `studies[]` under each requested study; check its `index_status`, `latest_report_id`, and `indexed_report_id` for freshness. Follow `next_cursor` with unchanged query, filters, and limit until null; an empty final page is possible. Participant-response matches include a public `interview_id` to use with `get_interview`.

`answer_research` takes a question and the same study/date/content filters. It returns generated prose with numbered citations whose content IDs were verified against accessible canonical search results. `citations[]` identifies each source's study, content type, report, and interview when available; `studies[]` reports index freshness without repeating the full search payload. `insufficient_evidence` means the indexed sources did not support an answer. Use `search_research`, `get_study_report`, or `get_interview` to inspect source content and verify exact quotations.

When the primary ranking service is unavailable, search falls back to bounded keyword matching over current indexed research for the same authorized study IDs and filters. Keyword ranking can differ from the primary semantic ranking; results still come from the canonical stored records.

## Finding studies

`list_studies` defaults to 20 rows per page and accepts at most 100. Filter by `name`, provisioning `status` (`draft`, `ready`, or `provisioned`), `recruiting_method`, ISO date-time `created_after`, or `has_report`. Filters apply before the count and page. Results are ordered by `updated_at` descending, then study ID descending, so pages have a stable order. Each row's `interview_count` uses the same completed, visible, non-test, quality-filtered set as `list_interviews(status=completed)`; `get_study` returns that count too. `report_status` is `available` or `not_generated`. `study_link` is the live participant interview link when the interviewer is provisioned and the study is not paused; it is not a researcher preview link.

Study detail also returns `invitation_count` (invitation records), `interview_attempt_count` (all attempts), and `quality_interview_count` (interviews that passed quality checks). A panel launch can have one invitation record and many interviews. The older count aliases are no longer returned.

`study_plan.learning_goals_structured` gives each enriched Learning Goal a stable `id`, `question`, and `evidence_needed`. Report `learning_goal_id` values use those IDs. The markdown `learning_goals` field remains for existing clients. Historical study labels appear in `use_case`; `study_type` is always one of the current creation types.

## Study decisions and defaults

Before creating a study, ask for the required recruiting decision:

* `recruiting_method`: `panel`, `byop`, or `synthetic_respondents`

For Panel and BYOP studies, omitted interview settings default to `interview_format: "voice"`, `language: "en"`, and `voice: "male"`. Synthetic respondents use chat. Use explicit alternatives only when the user requests them. Voice configuration remains required for chat studies and accepts only `male` or `female`. `create_study` requires a nonblank `name` and an explicit recruiting method; it does not accept `byop_config` or designed content. Prototype tests cannot use chat.

The study `name` has a maximum length of 40 characters.

`study_type` accepts `in-depth-interview`, `concept-test`, and `prototype-test`; the default is `in-depth-interview`. Prototype tests cannot use chat. Catalog tools may help explain the available template, but the MCP host must not turn catalog prompts into a plan. `customize_study` loads and applies the selected study type's instructions on the backend.

## Customize Plan conversation

`create_study`, `customize_study`, `queue_customize_study`, `create_participants`, `generate_report`, and `launch_panel` accept an optional `idempotency_key`. Use a new key for each approved paid launch. For panel approval, check `get_study` after a timeout before taking any further action. The MCP review nonce is single-use; do not create a new approval merely to retry a launch. Backend idempotency protects the submitted paid request. The planning conversation is stored on the study; continue it with `study_id`, without passing a separate conversation identifier.

For a text planning turn, call `queue_customize_study`. It returns a job ID promptly. Poll `get_customize_study_job` until `status` is `succeeded` or `failed`; a successful job includes the next planning response in `result`. Call `get_study` after success to inspect the persisted plan. The synchronous `customize_study` remains available for native concept images, which the queue does not accept. A public image URL may be included in the queued message.

After creating the metadata draft, call `customize_study` with the user's ordinary-language brief. Use the same tool for all later changes to:

* the study plan and expected duration
* canonical audience targeting and custom screeners
* concept links and concept images

Do not translate the user's request into MCP-side `study_plan`, `targeting_attributes`, `screener_questions`, or concept schemas. The backend owns those fields and performs the same checks and reconciliation as Customize Plan in the dashboard.

Use `decisions: "human"` by default: relay `questions[]` to the researcher and call `customize_study` again with their answer. When the researcher delegates ordinary research-design choices, use `decisions: "agent"`; report `assumptions[]`, and relay only questions still returned as required. This never authorizes the agent to choose an unspecified recruiting method, send invitations, or approve a paid launch. Put a draft-only workflow instruction in `execution_policy: "draft_only"`, not in the research `message`; direct launch or invitation commands in `message` return 422. The policy is returned with this turn, and this endpoint never starts recruitment. It does not replace approval checks on later fieldwork calls. When the response contains a plan or completion message, call `get_study` to verify what was persisted.

Return the complete persisted plan in a readable form and ask the user to approve that exact version or request revisions. Do not substitute a summary or dashboard link. Route revisions through `customize_study`, fetch the result again, and repeat review. Approval to create a draft, client tool permissions, and approval of a Panel estimate do not count as approval of the current study plan.

For an attached concept image, include `concept_image` with the raw bytes encoded as base64, filename, MIME type, and the user's participant-facing label. This works when the client exposes attachment bytes or a readable local path and does not require public hosting. Public downloadable image URLs remain supported in the message. Never ask for login credentials.

## Drafts and provisioning

`create_study` supports incremental setup and may return a draft. Every study response includes:

| Field | Meaning |
| - | - |
| **provisioning\_status** | `draft`, `ready`, or `provisioned` |
| **fielding\_status** | Recruitment lifecycle: `not_started`, `starting`, `fielding`, `paused`, `complete`, `partial`, `failed`, `stopped`, `unavailable`, `not_applicable`, or `unknown` |
| **missing\_requirements** | The fields still needed before the interviewer can be provisioned |

When the Customize Plan conversation completes the last missing requirement, provisioning happens automatically. Only create BYOP participants or launch a paid Panel study after `get_study` says `provisioning_status: "provisioned"` and the user has approved the current returned plan.

Treat `fielding_status` as distinct from provisioning. Panel studies expose their persisted recruitment state. BYOP returns `unavailable` because progress is tracked on invitations and interviews, while synthetic respondents return `not_applicable`.

## Read before write

Call `get_study` before `update_study`.

* `update_study` changes ordinary metadata such as name, recruiting method, interview format, language, voice, and BYOP incentives.
* `customize_study` changes the plan, expected duration, targeting, screeners, and concept material.

A fielding Panel study must be paused or stopped before it can be edited. Pause when recruitment should continue later; stop when recruitment is finished.

The raw REST API may expose additional structured study fields. The MCP intentionally routes designed content through Customize Plan so dashboard and agent-created studies follow the same planning behavior.


# Configuration resources & targeting
Source: https://docs.userintuition.ai/mcp-server/tools/voice-reports

Live MCP resources for languages, modes, voices, and study types, plus one targeting tool.

Read these resources for valid public study settings. `list_targeting_attributes` remains a tool because it searches a potentially large targeting catalog.

These resources read the same versioned public reference endpoints available to REST integrations. They contain no internal planning prompts or voice implementation fields.

| Resource URI | Description |
| - | - |
| `userintuition://catalog/languages` | Supported interview language codes |
| `userintuition://catalog/modes` | Voice, chat, and video modes |
| `userintuition://catalog/study-types` | Public study-type planning templates |
| `userintuition://catalog/study-types/{slug}` | One template's public details |
| `userintuition://catalog/voices` | Usable interviewer voice choices |
| `userintuition://catalog/panel-countries` | Supported panel countries and languages |

| Tool | Description |
| - | - |
| `list_targeting_attributes` | Search panel targeting attributes and options by name or category |

## Planning versus public write fields

The study-type catalog returns current planning templates in `study_types[]`. These templates describe use cases; `create_study.study_type` describes the research method and accepts `in-depth-interview`, `concept-test`, or `prototype-test`. Historical use-case labels on existing studies may not be selectable templates. Do not use catalog prompts to draft a moderator guide in the MCP host. `customize_study` applies the selected template instructions.

The voices resource returns `{ voice, name }` choices. Pass only the `voice` value, `male` or `female`, to public study tools; the name is a display label. No external preview URLs are exposed by this catalog.

`list_targeting_attributes` gives readable panel targeting labels and their IDs. Saved study targeting also resolves to readable labels; check approximation notes before describing who qualifies. Panel targeting does not apply to BYOP studies.

Concept links and images are managed through `customize_study`, not separate MCP tools.


# Webhooks
Source: https://docs.userintuition.ai/mcp-server/tools/webhooks

Create, inspect, test, rotate, and remove webhooks and view delivery attempts.

| Tool | Description |
| - | - |
| `create_webhook` | Register an account or study-scoped webhook with event subscriptions |
| `list_webhooks` | List webhook registrations without signing secrets |
| `get_webhook` | Inspect one registration without its signing secret |
| `rotate_webhook_secret` | Replace its signing secret; the new value is shown once |
| `test_webhook` | Send a signed, data-free test event to the registered URL |
| `list_webhook_deliveries` | Page through delivery attempts and coarse failure reasons |
| `delete_webhook_by_id` | Remove one registration by ID |
| `delete_webhook` | Deprecated URL form; use `delete_webhook_by_id` |

Webhooks can cover an account or one study. Subscribe to `interview.completed`, `study.completed`, `report.ready`, `study.paused`, `study.resumed`, `study.stopped`, `participant.screened`, `participant.started`,
`participant.quality_scored`, or `study.quota_reached`. See the [event coverage and payloads](/api-reference/webhooks/overview#participant-lifecycle-events) before relying on a runtime-specific start event. The three lifecycle events currently cover public API pause, resume, and stop calls. `create_webhook` returns an HMAC signing secret once; `rotate_webhook_secret` returns the replacement once. Store it securely and never repeat it in logs or ordinary chat output. List and get responses never include a secret.

Use `test_webhook` to verify the destination and `list_webhook_deliveries` to inspect recent attempts. The test event contains no participant or study data. Delivery history contains status and coarse errors, not request bodies.

Creating a webhook changes an external integration and should require user confirmation. If a temporary webhook is created for testing, delete it before finishing.


# Embed the AI Widget
Source: https://docs.userintuition.ai/recruiting/embed-widget

Drop a User Intuition study directly into your web app with an embeddable on-site interview widget. Install in minutes with HTML, JavaScript, or React.

The User Intuition AI widget is an embeddable on-site interview surface. Drop it into any web app and participants can start a voice or chat interview without leaving your product. The widget triggers a live Study from inside your page, captures the response, and feeds it back into your dashboard like any other interview.

Use it for in-app feedback, post-purchase surveys, churn intercepts, or always-on listening from inside your product.

***

## What you need

The easiest way to get a working embed is to request its generated HTML with your Study ID:

```http theme={null}
GET /api/public/v1/studies/{study_id}/embed-code?type=widget
```

Copy the returned `code` into your page. The study must be provisioned. For a simple link instead, use `type=button`; that response also includes `study_link`.

If you build the widget markup yourself, it needs these values:

| Prop | Description |
| - | - |
| `public-key` | The public widget key returned in the generated code. |
| `assistant-id` | The widget's provisioned interviewer ID returned in the generated code. This can differ from the Study ID used in the API path. |
| `invite-id` | The interview invitation ID returned in the generated code. |

<Note>
  Use the API Study ID to request the embed code. Use the generated widget values as returned; the widget's `assistant-id` is not necessarily the API Study ID.
</Note>

***

## Quickstart

<Steps>
  <Step title="Grab your keys">
    Copy the Study ID, then call `GET /api/public/v1/studies/{study_id}/embed-code?type=widget` to get the widget values.
  </Step>

  <Step title="Install or include the widget">
    Run `npm install @userintuition-ai/web` for React, or drop in the UMD `<script>` tag for plain HTML.
  </Step>

  <Step title="Mount it">
    Add the generated `<userintuition-widget>` element and script, or pass its values to `<UserIntuitionWidget />`.
  </Step>

  <Step title="Style and scope">
    Set `theme`, `position`, `size`, and brand colors. Use `show-based-on-url` and `delay-interval` so the widget only appears where it should.
  </Step>

  <Step title="Test the interview">
    Open the page, trigger the widget, and complete a test interview. The response will appear in your Study Dashboard alongside link and invite responses.
  </Step>
</Steps>

***

## Install

The package is published as `@userintuition-ai/web`.

<CodeGroup>
  ```bash npm theme={null}
  npm install @userintuition-ai/web
  ```

  ```html CDN theme={null}
  <script src="https://unpkg.com/@userintuition-ai/web@1.0.41/dist/embed/widget.umd.min.js" integrity="sha384-rXrrVbv7DSEZt7u+cwihOD3auuEJ5L8sTIepy8gMKtrlsYPdPlc2uXAAFfMbWHek" crossorigin="anonymous"></script>
  ```
</CodeGroup>

***

## Embedding methods

There are four ways to mount the widget. Pick the one that matches your stack.

### 1. HTML custom element

The simplest option. Drop in the script tag and a `<userintuition-widget>` element anywhere in your HTML.

```html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@userintuition-ai/web@1.0.41/dist/embed/widget.umd.min.js" integrity="sha384-rXrrVbv7DSEZt7u+cwihOD3auuEJ5L8sTIepy8gMKtrlsYPdPlc2uXAAFfMbWHek" crossorigin="anonymous"></script>
  </head>
  <body>
    <userintuition-widget
      public-key="your-public-key"
      assistant-id="your-generated-widget-interviewer-id"
      invite-id="your-generated-invitation-id"
      mode="voice"
      theme="dark"
      position="bottom-right"
    ></userintuition-widget>
  </body>
</html>
```

### 2. JavaScript loader

If you need to mount programmatically (for example, after a route change or user action), create the same custom element after the widget script loads.

```javascript theme={null}
const container = document.getElementById('widget-container');
const widget = document.createElement('userintuition-widget');
widget.setAttribute('public-key', 'your-public-key');
widget.setAttribute('assistant-id', 'your-generated-widget-interviewer-id');
widget.setAttribute('invite-id', 'your-generated-invitation-id');
widget.setAttribute('mode', 'voice');
widget.setAttribute('theme', 'dark');
widget.setAttribute('position', 'bottom-right');
container.append(widget);
```

### 3. React component

For React apps, install the npm package and import the component.

<CodeGroup>
  ```tsx React theme={null}
  import { UserIntuitionWidget } from '@userintuition-ai/web';

  export default function App() {
    return (
      <UserIntuitionWidget
        publicKey="your-public-key"
        assistantId="your-generated-widget-interviewer-id"
        mode="voice"
        theme="dark"
        position="bottom-right"
      />
    );
  }
  ```

  ```tsx TypeScript theme={null}
  import { UserIntuitionWidget, type UserIntuitionWidgetProps } from '@userintuition-ai/web';

  const props: UserIntuitionWidgetProps = {
    publicKey: 'your-public-key',
    assistantId: 'your-generated-widget-interviewer-id',
    mode: 'voice',
    theme: 'dark',
  };

  export default function App() {
    return <UserIntuitionWidget {...props} />;
  }
  ```
</CodeGroup>

### 4. Web component variant

For React apps that prefer a thin wrapper around the underlying custom element, use `UserIntuitionWidgetWebComponent`. It is the package's default export and the recommended React surface.

```tsx theme={null}
import { UserIntuitionWidgetWebComponent } from '@userintuition-ai/web';
// or use the default export
import UserIntuitionWidget from '@userintuition-ai/web';

export default function App() {
  return (
    <UserIntuitionWidgetWebComponent
      publicKey="your-public-key"
      assistantId="your-generated-widget-interviewer-id"
      mode="voice"
      theme="dark"
    />
  );
}
```

***

## Modes

The widget supports three interview modes. Set the mode that fits your audience and the depth of feedback you want.

| Mode | When to use it |
| - | - |
| `voice` | Spoken interviews. Best for richer, longer-form feedback and natural conversation. Default mode. |
| `chat` | Text-only interviews. Best for quiet environments, accessibility, or users who prefer typing. |
| `hybrid` | Lets the participant choose voice or chat at the start. Best when you don't know the context the widget will load in. |

```html theme={null}
<userintuition-widget
  public-key="your-public-key"
  assistant-id="your-generated-widget-interviewer-id"
  mode="hybrid"
></userintuition-widget>
```

***

## Position and size

Control where the widget anchors and how much room it takes up on screen.

### Position

| Value | Description |
| - | - |
| `bottom-right` | Default. Anchored bottom-right, ideal for chat-style launchers. |
| `bottom-left` | Bottom-left corner. |
| `top-right` | Top-right corner. |
| `top-left` | Top-left corner. |
| `center` | Centered on screen. Use for full-screen takeovers or modal-style interviews. |

### Size

| Value | Description |
| - | - |
| `compact` | Default. Small launcher that expands when opened. |
| `full` | Full launcher panel — more visible, larger surface for the interview. |
| `minimal` | Smallest footprint. Good for unobtrusive, always-on placement. |

```html theme={null}
<userintuition-widget
  public-key="your-public-key"
  assistant-id="your-generated-widget-interviewer-id"
  position="bottom-right"
  size="full"
></userintuition-widget>
```

***

## Theme and branding

The widget ships with `light` and `dark` presets. You can override individual colors to match your brand.

| React prop | HTML attribute | Description |
| - | - | - |
| `theme` | `theme` | Preset — `light` or `dark`. Default: `light`. |
| `baseBgColor` | `base-bg-color` | Base background color (hex). |
| `baseColor` | `base-color` | Base color (hex). |
| `accentColor` | `accent-color` | Accent color used across the interview UI (hex). |
| `ctaButtonColor` | `cta-button-color` | Background color of the call-to-action button (hex). |
| `ctaButtonTextColor` | `cta-button-text-color` | Text color of the call-to-action button (hex). |
| `buttonBaseColor` | `button-base-color` | Base color for buttons (hex). |
| `buttonAccentColor` | `button-accent-color` | Accent color for buttons (hex). |
| `borderRadius` | `border-radius` | One of `none`, `small`, `medium`, `large`. Default: `medium`. |

```html theme={null}
<userintuition-widget
  public-key="your-public-key"
  assistant-id="your-generated-widget-interviewer-id"
  theme="dark"
  base-bg-color="#000000"
  accent-color="#14B8A6"
  cta-button-color="#000000"
  cta-button-text-color="#ffffff"
  border-radius="large"
></userintuition-widget>
```

You can also customize widget copy with `title`, `cta-title`, `cta-subtitle`, `start-button-text`, `end-button-text`, and mode-specific empty-state messages (`voice-empty-message`, `chat-empty-message`, `chat-placeholder`, `hybrid-empty-message`, and others).

***

## Consent flow

When `consent-required` is enabled, the widget shows a consent dialog before the interview can start. The participant's choice is stored in `localStorage` so they only see the dialog once per device.

| React prop | HTML attribute | Description |
| - | - | - |
| `consentRequired` | `consent-required` | Show a consent dialog before the interview begins. Default: `false`. |
| `consentTitle` | `consent-title` | Title of the consent dialog. |
| `consentContent` | `consent-content` | Body text of the consent dialog. |
| `consentStorageKey` | `consent-storage-key` | LocalStorage key used to persist consent. |
| `termsContent` | `terms-content` | Optional terms-and-conditions text. |

```html theme={null}
<userintuition-widget
  public-key="your-public-key"
  assistant-id="your-generated-widget-interviewer-id"
  consent-required="true"
  consent-title="Terms and conditions"
  consent-content='By clicking "Agree," and each time I interact with this AI agent, I consent to the recording, storage, and sharing of my communications with third-party service providers, and as otherwise described in our Terms of Service.'
  consent-storage-key="userintuition_widget_consent"
></userintuition-widget>
```

<Note>
  Consent state is keyed by `consent-storage-key`. If you change the key, the widget will treat returning participants as new and prompt them again.
</Note>

***

## Smart display

You usually don't want the widget to appear on every page or fire instantly. Use these props to scope when and where it shows.

| React prop | HTML attribute | Description |
| - | - | - |
| `showWidget` | `show-widget` | Hard on/off switch. Default: `true`. |
| `showBasedOnUrl` | `show-based-on-url` | Array of URL paths where the widget should appear. Pass a JSON array string in HTML. |
| `delayInterval` | `delay-interval` | Milliseconds to wait before showing the widget. Default: `0`. Useful when you want to give the page a moment to settle before interrupting the user. |

<CodeGroup>
  ```html HTML theme={null}
  <userintuition-widget
    public-key="your-public-key"
    assistant-id="your-generated-widget-interviewer-id"
    show-based-on-url='["/feedback", "/contact"]'
    delay-interval="3000"
  ></userintuition-widget>
  ```

  ```tsx React theme={null}
  <UserIntuitionWidget
    publicKey="your-public-key"
    assistantId="your-generated-widget-interviewer-id"
    showBasedOnUrl={['/feedback', '/contact']}
    delayInterval={3000}
  />
  ```
</CodeGroup>

***

## Voice and reconnect options

Voice mode has a few extra knobs for transcript display and reconnection.

| React prop | HTML attribute | Description |
| - | - | - |
| `voiceShowTranscript` | `voice-show-transcript` | Display a live transcript during voice interviews. Default: `false`. |
| `voiceAutoReconnect` | `voice-auto-reconnect` | Reconnect automatically if the audio connection drops. Default: `false`. |
| `reconnectStorageKey` | `reconnect-storage-key` | LocalStorage key used to persist reconnect state. |
| `showTranscript` | `show-transcript` | Show the transcript surface generally. Default: `false`. |

***

## Where to find your keys

Use your Study ID to request the generated embed code. Copy `public-key`, `assistant-id`, and `invite-id` from that response when configuring the widget yourself.

<CardGroup>
  <Card title="Public key" icon="key" href="/resources/account-settings">
    Find this in your account settings under API keys. Safe to ship in client-side code.
  </Card>

  <Card title="Widget values" icon="flask" href="/api-reference/study-lifecycle">
    Request `GET /api/public/v1/studies/{study_id}/embed-code?type=widget` with your Study ID and copy the generated widget values.
  </Card>
</CardGroup>

***

## Browser support

The widget runs in any modern browser that supports:

* ES6+
* The Custom Elements API
* Microphone access (for voice and hybrid modes)

For React installs, React 16.8+ is required as a peer dependency.

***

## Next.js and React Server Components

The widget is a client-only component — it touches `window`, `localStorage`, and the microphone. In Next.js 13+ with the App Router, mark the file as a client component.

```tsx theme={null}
'use client';

import UserIntuitionWidget from '@userintuition-ai/web';

export default function FeedbackWidget() {
  return (
    <UserIntuitionWidget
      publicKey="your-public-key"
      assistantId="your-generated-widget-interviewer-id"
      mode="voice"
    />
  );
}
```

<Warning>
  Don't import the widget into a server component or render it during SSR. The bundle assumes a browser environment and will throw if it loads on the server.
</Warning>

***

## Next steps

<CardGroup>
  <Card title="Share a study link" icon="link" href="/recruiting/share-link">
    The simpler alternative — a hosted URL anyone can open in a browser.
  </Card>

  <Card title="Account settings" icon="gear" href="/resources/account-settings">
    Request generated embed code for your Study ID.
  </Card>
</CardGroup>


# Send Email Invites
Source: https://docs.userintuition.ai/recruiting/invite-customers

Add a list of email addresses and User Intuition sends the invitations, tracking who was invited and who completed.

Add email addresses and User Intuition sends the invitations for you, tracking who was invited and who has completed.

Use this when your list is long enough that sending by hand is impractical, or when you want delivery and completion status tracked in one place. If you'd rather the invitation came from you directly — which usually lifts response rates — [share a study link](/recruiting/share-link) instead.

***

## Why interview your own participants

Talking to people who actually use your product beats a general panel when the question is about *your* product:

* **Authentic feedback:** Every insight comes from people who genuinely use your product
* **Higher relevance:** Feedback directly tied to real experiences with your brand
* **Better response rates:** Customers are more willing to share with brands they engage with
* **Actionable insights:** Real user feedback translates directly to product and marketing decisions

***

## How to send email invites

From your Study Dashboard:

1. Navigate to the **Invites** tab
2. Click **Invite Participants**
3. Select **Send Email Invites**
4. Choose your input method (Manual, Contacts, or Segments)

***

## Input Methods

### Manual Entry

Add participants one at a time or in bulk by entering email addresses directly.

<Steps>
  <Step title="Open email invites">
    Click **Invite Participants** → **Send Email Invites**
  </Step>

  <Step title="Select Manual tab">
    The Manual tab should be selected by default
  </Step>

  <Step title="Enter email addresses">
    Type or paste email addresses into the text field
  </Step>

  <Step title="Add to list">
    Click the **+** button to add each address
  </Step>
</Steps>

**Best for:**

* Quick invites to a small number of participants
* One-off invitations to specific customers
* Testing with internal team members

<Tip>
  You can also upload a CSV file with email addresses for bulk invitations.
</Tip>

***

### Contacts (CRM Integration)

If you've connected your CRM, you can invite participants directly from your synced contact list.

<Steps>
  <Step title="Open email invites">
    Click **Invite Participants** → **Send Email Invites**
  </Step>

  <Step title="Select Contacts tab">
    Click the **Contacts** tab
  </Step>

  <Step title="Search or browse">
    Find contacts using search or browse your synced list
  </Step>

  <Step title="Select contacts">
    Check the contacts you want to invite
  </Step>
</Steps>

**Best for:**

* Inviting specific customers from your database
* Targeting based on CRM attributes
* Maintaining consistent participant records across studies

<Note>
  Contacts require CRM integration. Contact support to set up your integration.
</Note>

***

### Segments

Invite pre-defined customer segments from your connected data sources.

<Steps>
  <Step title="Open email invites">
    Click **Invite Participants** → **Send Email Invites**
  </Step>

  <Step title="Select Segments tab">
    Click the **Segments** tab
  </Step>

  <Step title="Choose a segment">
    Select from available segments (e.g., "Loyal Customers," "Recently Churned")
  </Step>

  <Step title="Confirm">
    Review and confirm the invitation
  </Step>
</Steps>

**Best for:**

* Targeting specific customer groups
* Systematic research across customer segments
* Recurring studies with consistent audience criteria

**Example segments:**

* Recently churned customers
* High-value customers
* New users (signed up in last 30 days)
* Customers who contacted support
* Customers by subscription tier

<Note>
  Segments require integration with your CRM or customer data platform. Contact support to configure segments.
</Note>

***

## Managing Invitations

### Viewing Invite Status

The Invites tab shows all invitations with their current status:

| Status | Meaning |
| - | - |
| **Sent on \[date]** | Invitation email was delivered |
| **N/A** | No email sent (widget or link participants) |
| **Taken on \[date/time]** | Participant completed the interview |

### Invite Actions

For each invitation, you can:

| Action | Description |
| - | - |
| **Resend** | Send another invitation email |
| **Delete** | Remove the invitation |
| **Copy** (icon) | Copy the unique invite link for this participant |

### Searching and Filtering

* Use the **Search** box to find specific participants by email, company, or other attributes
* Use the **Show** dropdown to control how many invitations are displayed per page

***

## Best Practices

<AccordionGroup>
  <Accordion title="Personalize when possible">
    Direct email invitations tend to have higher response rates than generic links. Participants appreciate being asked by name.
  </Accordion>

  <Accordion title="Set expectations">
    Let participants know how long the interview will take (typically 10-20 minutes). Clear expectations improve completion rates.
  </Accordion>

  <Accordion title="Time your invitations">
    Send invitations when participants are likely to have time to respond. Avoid holidays and weekends for B2B research.
  </Accordion>

  <Accordion title="Send reminders">
    Use the Resend action for participants who haven't responded after a few days. A gentle reminder can significantly improve response rates.
  </Accordion>

  <Accordion title="Mention incentives">
    If you're offering incentives, highlight them in your invitation. Even small incentives can meaningfully improve participation.
  </Accordion>
</AccordionGroup>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How many participants can I invite?">
    There's no limit to manual invitations. Invite as many customers as you need.
  </Accordion>

  <Accordion title="Can I invite the same person to multiple studies?">
    Yes, but be mindful of research fatigue. We recommend spacing out invitations to the same participants.
  </Accordion>

  <Accordion title="What email do participants receive?">
    Participants receive a branded email invitation with your study details and a unique link to begin the interview.
  </Accordion>

  <Accordion title="Can I customize the invitation email?">
    Contact support to discuss email customization options for enterprise customers.
  </Accordion>

  <Accordion title="Can I close invitations after reaching my target?">
    Yes. You can delete pending invitations to prevent additional responses.
  </Accordion>

  <Accordion title="How do I set up CRM integration?">
    Contact support to configure integration with your CRM (Salesforce, HubSpot, etc.) or customer data platform.
  </Accordion>
</AccordionGroup>


# Recruiting Participants
Source: https://docs.userintuition.ai/recruiting/overview

Two ways to reach participants: bring your own, or recruit from our research panel. How to choose, and what each costs.

There are two ways to get participants into a study: **bring your own** — shortened to **BYOP** in the product and in this sidebar — or **recruit from our research panel**.

You choose which in [Step 4](/creating-a-study/setup-interview#recruiting-method), and it determines your invite options once the study is live.

<Note>
  A study is one or the other. If you want responses from both your own participants and the panel, run two studies — you'll get cleaner analysis from each anyway, since you can compare them.
</Note>

***

## Bring your own participants (BYOP)

You already know who you want to talk to — your customers, your users, people on a list you control. You handle the recruiting; we run the interviews.

Three ways to get them in:

| Method | How it works | Best for |
| - | - | - |
| [**Share a study link**](/recruiting/share-link) | You get a URL and send it however you like | **Most bring-your-own studies — start here** |
| [**Send email invites**](/recruiting/invite-customers) | You add addresses and we email them | Larger lists, when you want delivery tracked |
| [**Embed a widget**](/recruiting/embed-widget) | Put the study inside your product | Catching people mid-experience |

### Why the study link is the default here

A study link keeps the invitation coming from **you**. It arrives in your voice, in the channel your customer already knows you from, alongside whatever context makes them want to help — an account manager's note, a line in your newsletter, a reply in an existing thread.

That matters twice over. Response rates are better when the ask comes from someone the person already has a relationship with. And you keep control of that relationship, rather than handing a slice of it to a vendor they've never heard of.

Use email invites when the list is long enough that sending by hand is impractical, or when you want the invited-and-completed status tracked for you.

***

## Research panel

You don't have the people, or you need people who aren't your customers. Two options here, and the right one comes down to how common your target is.

The panel fields in **58 countries** across the Americas, Europe, Asia-Pacific, the Middle East, and Africa — see [Where we recruit](/recruiting/research-panel#where-we-recruit) for the list. Niche recruiting isn't limited to that list; a hard-to-reach geography is one of the things it's for.

| How common your audience is | Use | Turnaround |
| - | - | - |
| More than **1 in 5** people qualify | [Recruit from our panel](/recruiting/research-panel#recruit-from-our-panel) | Usually within 24 hours |
| Between **1 in 10 and 1 in 5** | [Recruit from our panel](/recruiting/research-panel#recruit-from-our-panel) | Longer than 24 hours |
| Fewer than **1 in 10** — B2B roles, executives, low-incidence consumers | [Recruit a niche audience](/recruiting/research-panel#recruit-a-niche-audience) | Quote within 24 hours, then a recruiting lead time in days |

The number in that first column is your audience's *incidence rate* — the share of the general population who'd qualify for your study.

You don't need to calculate it precisely. The question to ask is: **if I stopped 100 random people, how many would qualify?** "People who've bought running shoes in the last year" is a lot of them. "People who own a drone" is a few. "VPs of Finance at companies over 500 people" is approximately none, and that's a niche recruit.

<Tip>
  Screeners narrow an audience; they don't create one. If your screener would disqualify 95 out of 100 panel members, you're not screening — you're looking for a niche audience, and asking the panel for it will just take a long time and return thin results.
</Tip>

***

## What it costs

| | Cost |
| - | - |
| **Your own participants** | Nothing beyond credits. Optionally [pay them a reward](/managing-your-study/study-actions#enable-rewards), \$5–\$500, your choice |
| **Our panel** | **\$30 per participant**, billed only on quality completes |
| **Niche audience** | Quoted individually — most land between \$50 and \$500 per complete |

Credits are charged for every interview regardless of how the participant got there. See [Billing and credits](/resources/billing-and-credits).

***

## How many participants do you need?

Whichever lane you're in, the number comes from the same place: how common the thing you're looking for is, and how confident you need to be that you'd have heard about it.

<SampleSizeCalculator />

Most studies are smaller than the confidence people want from them. Ten interviews feels thorough — and for anything affecting fewer than 1 in 5 participants, it isn't.

<Card title="How this is calculated" icon="calculator" href="/resources/sample-size">
  The reasoning, the reference tables, and what to do when you need a proportion rather than a discovery.
</Card>

***

## Screening participants

Whichever lane you're in, [screener questions](/creating-a-study/setup-interview#screener-questions-and-targeting-attributes) qualify people before they reach the interview. Standard attributes — age, gender, location, household income — are one click, and you can write custom questions with disqualifying answers.

For panel studies, screeners are what the panel matches against. For your own participants, they're a safety net against the wrong person following a forwarded link.

***

## Best practices

<AccordionGroup>
  <Accordion title="Say how long it takes">
    People abandon an interview that runs longer than they were told. Put the real number in the invitation.
  </Accordion>

  <Accordion title="Say why them">
    "We're talking to customers who switched plans this year" outperforms "we'd value your feedback." Specific asks feel less like spam and more like being asked to help.
  </Accordion>

  <Accordion title="Watch your response rate, not just your count">
    Compare invites sent against calls completed on the dashboard. A low rate is usually the invitation, not the study.
  </Accordion>

  <Accordion title="Consider a reward for your own participants">
    Not always necessary for engaged customers, but it moves response rates on longer studies and with busy audiences.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup>
  <Card title="Share a study link" icon="link" href="/recruiting/share-link">
    The recommended way to reach your own participants
  </Card>

  <Card title="Research panel" icon="users" href="/recruiting/research-panel">
    Panel recruiting and niche audiences
  </Card>
</CardGroup>


# Research Panel
Source: https://docs.userintuition.ai/recruiting/research-panel

Recruit from our consumer panel of 4 million+ verified respondents across 58 countries, or commission a niche audience for people the panel can't reach.

When you don't have the participants yourself, we recruit them. There are two routes: our **consumer panel** for audiences that exist in reasonable numbers, and **niche audience** recruiting for people the panel can't reach.

Both are available on studies where you chose **Panel** as the recruiting method in [Step 4](/creating-a-study/setup-interview#recruiting-method).

***

## Recruit from our panel

Our consumer panel is 4 million+ verified respondents across [58 countries](#where-we-recruit). You set a target, we field it, and completed interviews flow into your dashboard as they happen.

### Setting up a panel

<Steps>
  <Step title="Open Invite Participants">
    On your study dashboard, click **Invite Participants** → **Recruit from Our Panel**.
  </Step>

  <Step title="Set how many interviews you want">
    The default is 20. Minimum is 1. See [How many participants do you need?](#how-many-participants-do-you-need) if you're not sure.
  </Step>

  <Step title="Choose a frequency">
    **One-time** fields your target once. **Weekly** or **Monthly** recruits that many interviews on repeat — see [Recurring panels](#recurring-panels) below.
  </Step>

  <Step title="Choose a country">
    Participants are recruited from the country you select — see [Where we recruit](#where-we-recruit) for the full list. The interview language comes from your study settings.
  </Step>

  <Step title="Launch">
    Confirm, and the study moves to **Fielding**. Watch progress on the dashboard.
  </Step>
</Steps>

Your screener questions and targeting attributes from Step 4 are what the panel matches against, so get those right before you field.

### Where we recruit

The panel fields in **58 countries** across the Americas, Europe, Asia-Pacific, the Middle East, and Africa. You pick one country per panel — for a multi-market study, see [Running the same study in several countries](#running-the-same-study-in-several-countries).

| Region | Countries |
| - | - |
| **Americas** | United States, Canada, Mexico, Argentina, Bolivia, Brazil, Chile, Colombia, Costa Rica, Dominican Republic, Ecuador, Peru |
| **Europe** | United Kingdom, Ireland, France, Germany, Spain, Portugal, Italy, Netherlands, Belgium, Luxembourg, Switzerland, Austria, Denmark, Finland, Norway, Sweden, Poland, Czechia, Slovakia, Hungary, Romania, Greece, Russia |
| **Asia-Pacific** | Australia, New Zealand, China, Hong Kong, Taiwan, Japan, South Korea, Singapore, Malaysia, Indonesia, Philippines, Thailand, Vietnam, India, Pakistan |
| **Middle East & Africa** | United Arab Emirates, Saudi Arabia, Egypt, Turkey, South Africa, Nigeria, Kenya, Uganda |

A few appear in the dropdown under their official names — Korea (Republic of), Viet Nam, Bolivia (Plurinational State of), and United Kingdom of Great Britain and Northern Ireland. Type the first few letters and they'll surface.

<Note>
  **Language narrows the list.** The country picker only shows countries where your study's interview language is available, so set the language first if you have a specific market in mind. English is available in most of these countries; a language like Swedish or Thai is available in its own. If your country isn't showing, that's usually why.
</Note>

<Tip>
  Working through the API? [List Panel Countries](/api-reference/public-panel-countries/list-panel-countries) returns the current countries with the languages each supports, and takes a `language` or `country` filter.
</Tip>

### Running the same study in several countries

A study fields one panel at a time, so multi-market work is two shapes:

| You want | Do this |
| - | - |
| One combined read across markets | Field a panel in the first country, let it finish, then launch the next country on the same study. All the interviews sit in one dashboard and one report. |
| A per-market read you can compare | [Duplicate the study](/managing-your-study/study-actions#duplicate-study) per country and field each separately. Same questions, separate reports, clean market-by-market comparison. |

Set the interview language for each one before you field it — the language is a study setting, not a panel setting, so a study duplicated for Japan wants its language switched before launch.

### Recurring panels

Setting a frequency of **Weekly** or **Monthly** recruits your target number of interviews on that cadence, rather than once.

This is how you run a tracking study — the same questions to a fresh sample every month, so you can see a trend rather than a snapshot. Each wave lands in the same study, so the comparison is like-for-like.

<Note>
  A study can only field one panel at a time. If you set up a new panel while one is already fielding, you'll be asked to stop the existing one first.
</Note>

### What it costs

**\$30 per participant**, on top of credits for the interviews themselves. You're billed **only for interviews rated Excellent or Good** — Fair and Poor conversations cost you nothing, neither the participant fee nor the credits.

When you launch a panel, a hold is placed on your card for the participant rewards. You're charged against it as quality interviews come in, not up front. Enterprise customers are invoiced under their agreement instead.

If your credit balance won't cover the number of interviews you've asked for, you'll be prompted to top up before the panel launches.

### Quality

Panel participants are multi-layer verified before they reach your study, and every completed interview is rated the same way your own participants' interviews are — Excellent, Good, Fair, or Poor.

You pay only for **Excellent** and **Good**. That's a higher bar than we apply when you bring your own participants, where Fair is also charged — the difference being that here we chose the participant, so a thin conversation is our problem to absorb.

***

## Recruit a niche audience

<Info>
  **Beta.** Available from **Invite Participants** → **Recruit a Niche Audience**.
</Info>

Our standard panel covers general consumers. A niche audience is anyone that panel can't reach: specific job titles and seniority, decision-makers, low-incidence consumers such as drone owners or crypto traders, or hard-to-reach geographies.

### How it differs from the panel

**Sourced for you, not sampled.** We recruit these participants directly for your study. That means a real lead time — usually days, not hours.

**Every participant is verified.** We confirm people are who they say they are before they reach your study — role and employer, ID, or product proof, depending on who you're after.

**Priced above standard consumer.** One all-in price per completed interview, covering the participant's incentive plus the recruiting work. No setup fees, no minimums, and you're billed only on approved completes.

### What it costs

Most niche audiences land between **\$50 and \$500 per complete**.

| Audience | Why it prices where it does | All-in, per complete |
| - | - | - |
| Drone owners (US) | Consumer, but low incidence — needs product proof | \~\$50 |
| Ad managers | B2B role, employer verified | \~\$140 |
| IT decision-makers | Seniority plus buying authority | \~\$185 |
| CFOs / VPs of Finance | Executive time is expensive | \~\$280+ |

**These are examples, not a rate card.** Your quote depends on how rare the audience is, session length, country, and how fast you need it.

### Requesting a quote

Say how many completes you want as well as who — see [How many participants do you need?](#how-many-participants-do-you-need). Beyond that, the more specific you are about who, the faster and tighter the quote. Role, seniority, company size, industry, geography, and any product or behaviour that has to be true of them.

You'll have a quote **within 24 hours**. Recruiting itself starts once you accept.

<Tip>
  Say what you'd accept as well as what you want. "VP Finance or above at 500+ employee US companies, but Director-level is fine if they own the budget" gets you a workable quote; "finance leaders" gets you a clarifying question and another day's delay.
</Tip>

***

## Which one do I need?

Ask how many of 100 random people would qualify for your study.

| Roughly how many qualify | Route | Turnaround |
| - | - | - |
| More than 20 | Recruit from our panel | Usually within 24 hours |
| 10 to 20 | Recruit from our panel | Longer than 24 hours |
| Fewer than 10 | Recruit a niche audience | Quote in 24 hours, then a recruiting lead time |

Any B2B audience defined by job title is almost always a niche recruit, however large the companies are.

***

## How many participants do you need?

This applies whichever route you take. The number comes from how common the thing you're looking for is, and how confident you need to be that you'd have heard about it.

<SampleSizeCalculator />

The panel dialog defaults to 20. That's a reasonable starting point, not an answer.

Getting it wrong costs in both directions, and the size of that cost depends on the route:

| Route | Per complete | What a bad estimate costs |
| - | - | - |
| **Our panel** | \$30 | Under-fielding wastes the study; over-fielding pays for interviews that told you nothing new |
| **Niche audience** | \$50–\$500 | The same mistake, ten times the price — worth getting right before you accept a quote |

<Note>
  Size **per segment**, not per study. If you're comparing four groups, a target of 20 gives you five interviews each — treat it as four studies of five, and size accordingly.
</Note>

<Card title="How this is calculated" icon="calculator" href="/resources/sample-size">
  The reasoning, the reference tables, and why this differs from a survey sample size.
</Card>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Which countries can you recruit in?">
    58, spanning the Americas, Europe, Asia-Pacific, the Middle East, and Africa — the full list is in [Where we recruit](#where-we-recruit). One country per panel, and the picker is filtered by your study's interview language.
  </Accordion>

  <Accordion title="Can I run the same study in more than one country?">
    Yes, one country at a time — a study fields one panel at a time. Run them back to back on the same study for a combined read, or duplicate the study per country for separate reports. See [Running the same study in several countries](#running-the-same-study-in-several-countries).
  </Accordion>

  <Accordion title="Can I use the panel and my own participants in the same study?">
    No — a study is either panel or bring-your-own. Run two studies if you want both; you'll get a cleaner comparison out of it.
  </Accordion>

  <Accordion title="Can I test the study myself before fielding a panel?">
    Yes. **Copy Test Link** from the Invite Participants menu gives you a link to run through it yourself. Test conversations are free.
  </Accordion>

  <Accordion title="What happens if the panel can't hit my target?">
    You're only billed for the completes you get. If an audience is proving harder to reach than expected, we'll tell you rather than let it field indefinitely.
  </Accordion>

  <Accordion title="Can I pause a fielding panel?">
    Yes — **Actions** → **Pause Study**. See [Study actions](/managing-your-study/study-actions#pause-and-resume).
  </Accordion>

  <Accordion title="Do panel participants get paid?">
    Yes, and User Intuition handles it. The \$30 is a pass-through to the participant. You don't set or send rewards on panel studies — that option only appears for your own participants.
  </Accordion>
</AccordionGroup>


# Share a Study Link
Source: https://docs.userintuition.ai/recruiting/share-link

Get a link to your study and send it however you like. The recommended way to reach your own participants.

A study link is a URL you send however you like — in an email you write yourself, a Slack message, a newsletter, a reply in an existing thread.

**When you're bringing in your own participants, this is the method we recommend.** It keeps the invitation coming from *you*: in your voice, in a channel the person already associates with you, alongside whatever context makes them want to help.

That matters twice over. Response rates are better when the ask comes from someone the person already has a relationship with. And you keep control of that relationship rather than handing a slice of it to a vendor your customer has never heard of.

Reach for [email invites](/recruiting/invite-customers) instead when your list is long enough that sending by hand is impractical, or when you want invited-and-completed status tracked for you.

***

## When to Use a Study Link

Study links are ideal for:

* **Always-on feedback:** Let customers reach you whenever they have something to share
* **Social media distribution:** Share on Twitter, LinkedIn, or community forums
* **Email newsletters:** Include in regular customer communications
* **Website placement:** Add a permanent "Share Feedback" link
* **Customer communities:** Post in Slack channels, Discord, or forums
* **QR codes:** Print on receipts, packaging, or in-store displays

***

## How to Copy Your Study Link

From your Study Dashboard:

<Steps>
  <Step title="Open Actions menu">
    Navigate to the **Invites** tab and click **Actions**
  </Step>

  <Step title="Select Copy Study Link">
    Click **Copy Study Link** from the dropdown
  </Step>

  <Step title="Use the link">
    The link is copied to your clipboard—paste it anywhere you want to share
  </Step>
</Steps>

***

## Link Characteristics

### Universal Access

* Anyone with the link can participate
* No email address required
* No account creation needed
* Works on any device with a browser

### Unlimited Uses

* The same link can be used by unlimited participants
* Each participant gets a unique session
* All responses are tracked separately

### Persistent

* Links stay active as long as the study is live, with no expiry by default
* Pausing the study closes the link — anyone who follows it sees "This study is no longer active"
* A study that reaches its target closes the same way
* Resuming the study reopens the same link; you don't need to redistribute it

***

## Link vs. Direct Invites

| Factor | Study Link | Direct Invites |
| - | - | - |
| **Tracking** | Anonymous unless they provide email | Tied to specific email |
| **Targeting** | Anyone who has the link | Specific individuals |
| **Response rate** | Lower (self-selecting) | Higher (invited directly) |
| **Reach** | Unlimited | Limited to your list |
| **Control** | Less control over who participates | Full control |

***

## Tracking Link Participants

Participants who use the study link appear in your Invites tab with:

* Their email (if provided during the interview)
* Invite Status: "N/A" (no email invitation sent)
* Call Status: When they completed the interview

To track where participants came from, consider:

* Creating separate studies for different channels
* Asking a channel identification question in your research plan
* Using UTM parameters if your landing page supports them

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I create different links for different channels?">
    Currently, each study has one link. To track channels separately, create separate studies for each channel.
  </Accordion>

  <Accordion title="Can I limit who can use the link?">
    No. Study links are open to anyone. For controlled access, use direct invites instead.
  </Accordion>

  <Accordion title="Will I know where participants came from?">
    Not automatically. Consider adding a question to your research plan asking how they found the study.
  </Accordion>

  <Accordion title="Can I deactivate the link?">
    You can stop the study or delete it to deactivate the link. There's no way to deactivate the link while keeping the study active.
  </Accordion>

  <Accordion title="Do link participants count against my response limits?">
    Yes. All responses count toward your plan limits regardless of how participants were invited.
  </Accordion>

  <Accordion title="Can I use the link for QR codes?">
    Yes. Simply convert the URL to a QR code using any QR code generator.
  </Accordion>
</AccordionGroup>


# Account settings
Source: https://docs.userintuition.ai/resources/account-settings

Manage your profile, company information, API keys, and authentication tokens from your account settings.

Manage your profile information, company details, API keys, and authentication tokens from the account menu. Access these settings by clicking your avatar in the bottom-left corner of the sidebar.

***

## Profile settings

Update your personal information and company details.

<Steps>
  <Step title="Open the menu">
    Click your avatar in the sidebar to open the account dropdown.
  </Step>

  <Step title="Select Profile Settings">
    Click **Profile Settings** to open the settings panel.
  </Step>

  <Step title="Edit your information">
    Update your first name, last name, and company name. Email is read-only and managed through your account provider.
  </Step>

  <Step title="Save">
    Click **Save Changes** to apply your updates.
  </Step>
</Steps>

### Company name

Your company name appears in your profile and is used across the platform.

* If you are a **member of an organization**, your company name is managed by your organization admin and cannot be edited directly.
* If you are an **individual user**, company name is required and must be set before you can use the platform.

<Note>
  First-time users who haven't set a company name will be prompted to complete their profile automatically.
</Note>

***

## Account management

Click **Manage Account** in the account dropdown to access advanced account settings, including:

* Email and password management
* Connected accounts and security settings
* API token access

***

## API keys

API keys provide persistent, organization-scoped credentials for programmatic access to the User Intuition API and the [MCP server](/integrations/mcp-server). Unlike session tokens, API keys do not expire automatically — they remain valid until you revoke them.

A key also stops working if the account that created it no longer belongs to the organization.

### Creating an API key

<Steps>
  <Step title="Open Manage Account">
    Click your avatar, then select **Manage Account**.
  </Step>

  <Step title="Go to the API Keys tab">
    In the account management dialog, click **API Keys** in the sidebar.
  </Step>

  <Step title="Name your key">
    Enter a descriptive name for the key (e.g., "Production" or "MCP Server"). If you leave the name blank, it defaults to "Default".
  </Step>

  <Step title="Choose access and a cap">
    New keys start with read access. Select write access for changes. Select paid panel launch or participant rewards only when needed, and enter a positive lifetime USD spend cap for those permissions.
  </Step>

  <Step title="Click Create Key">
    Click **Create Key**. Your new API key is displayed in a banner at the top of the page.
  </Step>

  <Step title="Copy the key immediately">
    Click **Copy Key** to copy it to your clipboard. The full key is only shown once — after you dismiss the banner or navigate away, only the key prefix is visible.
  </Step>
</Steps>

<Warning>
  Copy your API key as soon as it is created. You will not be able to view the full key again. If you lose it, revoke the old key and create a new one.
</Warning>

### Managing API keys

The API Keys page lists all active keys for your organization with the following details:

| Column | Description |
| - | - |
| **Name** | The label you gave the key |
| **Prefix** | The first characters of the key for identification |
| **Created** | When the key was created |
| **Last used** | When the key was last used to make an API call |
| **Access and cap** | Granted scopes and the amount reserved or spent against a lifetime cap |

Existing keys created before scopes were introduced retain broad access to the public API and may show no cap. API keys no longer access dashboard and billing routes. Revoke and replace a legacy key to set a cap. A cap is fixed for the lifetime of its key; create a new key when it is exhausted.

### Revoking an API key

To revoke a key, click the trash icon next to it and then click **Confirm**. Revoked keys stop working immediately and cannot be restored.

### Using an API key

Include the key in the `Authorization` header when making API requests:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.userintuition.ai/api/public/v1/studies/
```

For details on available endpoints, see the [API reference](/api-reference/introduction).

***

## API tokens

You can also retrieve a short-lived session token for programmatic access. Unlike API keys, session tokens expire periodically and are regenerated automatically when you sign in.

<Steps>
  <Step title="Open Manage Account">
    Click your avatar, then select **Manage Account**.
  </Step>

  <Step title="Go to API Token">
    In the account management dialog, click the **API Token** tab in the sidebar.
  </Step>

  <Step title="Reveal your token">
    Click **Reveal Token** to display your current JWT authentication token.
  </Step>

  <Step title="Copy the token">
    Click **Copy Token** to copy it to your clipboard.
  </Step>
</Steps>

<Warning>
  Your API token provides full access to your account. Keep it secure and do not share it publicly. Tokens expire periodically and a new one is generated automatically when you sign in.
</Warning>

<Note>
  For most use cases, [API keys](#api-keys) are recommended over session tokens because they do not expire and are easier to manage across services.
</Note>

***

## Quick reference

| Setting | Location | Editable |
| - | - | - |
| First name | Profile Settings | Yes |
| Last name | Profile Settings | Yes |
| Email | Profile Settings | No (read-only) |
| Company name | Profile Settings | Yes (individual users only) |
| Password | Manage Account | Yes |
| API keys | Manage Account > API Keys | Create / revoke |
| API token | Manage Account > API Token | View/copy only |


# Best Practices
Source: https://docs.userintuition.ai/resources/best-practices

Maximize the value of your customer research with these proven best practices for study design, participant recruitment, and insight activation.

Maximize the value of your customer research with these proven best practices. These recommendations come from extensive experience conducting thousands of AI-moderated interviews.

***

## Study Design

### Start with Clear Objectives

Before creating a study, articulate:

* **The core question:** What must this research answer?
* **The decisions:** What will you do differently based on what you learn?
* **The stakeholders:** Who needs to act on these insights?

<Tip>
  If you can't articulate what decision will change based on the research, consider whether you need the study at all.
</Tip>

### Focus on Depth, Not Breadth

**Don't try to cover everything.** Studies that go deep on 4-6 topics deliver more actionable insights than broad studies that skim 15 topics.

| ❌ Too Broad | ✅ Focused |
| - | - |
| "Tell us about your entire experience" | "Walk me through your checkout process" |
| 15 topics, 2 questions each | 5 topics, 6 questions each |
| Surface-level across everything | Deep understanding of key areas |

### Write for Your Participants

Use language your participants actually use, avoid internal jargon and acronyms, and frame questions from their perspective rather than your org chart's.

Good questions invite a story rather than a yes or no:

| Avoid | Better |
| - | - |
| "Did you have a good experience?" | "Walk me through your most recent experience." |
| "Is our pricing fair?" | "How did you feel about the pricing when you were deciding?" |
| "Would you recommend us?" | "If a colleague asked you about us, what would you say?" |

The pattern: ask about what happened, not what someone thinks or would do. People are poor at predicting themselves and good at recounting what they did.

### Trust the AI to Probe

You don't need to script every follow-up question. The AI interviewer naturally:

* Asks "tell me more" when responses are brief
* Probes deeper when participants mention something interesting
* Requests specific examples to ground abstract statements
* Follows unexpected threads that may reveal insights

***

## Participant Recruitment

### Match the audience to the question

When the question is about **your** product — why they churned, what confused them in onboarding, whether the new pricing lands — interview your own participants. They bring real experience with the thing you're asking about, and their feedback is specific rather than hypothetical.

Use the [research panel](/recruiting/research-panel) when you need people who *aren't* your customers: category research, competitive work, or testing a concept with a market you haven't reached yet.

<Tip>
  A study link shared by someone the participant already knows outperforms an invitation from a name they don't recognise. Where you can, send the ask yourself.
</Tip>

### Set Clear Expectations

In your invitation, communicate:

* How long the interview will take (be accurate)
* What topics you'll cover (high level)
* Why their feedback matters
* Any incentives offered

### Time Your Invitations

| Context | Best Timing |
| - | - |
| Post-purchase | Within 24-48 hours |
| Churn research | Shortly after cancellation |
| Onboarding feedback | End of first week |
| General feedback | Avoid Mondays and Fridays |
| B2B research | Mid-week, business hours |

### Send Reminders

A single reminder 3-5 days after the initial invitation can significantly improve response rates. Keep it brief and friendly.

### Watch for self-selection

Anyone can follow an open study link, and the people who volunteer are rarely a neutral sample — they tend to be your most enthusiastic or most annoyed customers, with the quiet middle missing. That's fine when you want strong opinions; it's a problem when you want a representative read. Use screeners to keep the wrong people out, and reach for the panel when representativeness matters.

***

## During Data Collection

### Monitor Early Responses

Listen to your first 3-5 interviews to:

* Confirm questions are understood correctly
* Verify the conversation flows naturally
* Catch any issues before scaling recruitment
* Validate your research hypotheses (or adjust them)

### Don't Edit Mid-Study

Once participants have started completing interviews:

* **Avoid changing questions** (compromises comparability)
* **Don't adjust the flow** (earlier and later responses won't match)
* **Note issues for next time** instead of fixing mid-stream

If changes are truly necessary, document when they occurred and consider separating analysis into pre/post change periods.

### Check Quality Distribution

Monitor your Quality count relative to total responses. If too many interviews come back Fair or Poor:

* Review if questions are confusing
* Check if you're reaching the right participants
* Consider whether the topic engages participants

***

## Analysis and Reporting

### Look for Patterns, Not Just Quotes

Individual quotes are powerful, but patterns matter more:

* What do multiple participants mention?
* Where do responses contradict each other?
* What's notably absent from conversations?

### Separate strong signals from weak ones

**Strong** — mentioned by several participants, consistent across segments, and backed by specific examples rather than generalities.

**Weak** — one participant, contradicted elsewhere, or asserted without an example behind it. Weak signals aren't worthless; they're hypotheses for the next study rather than findings for this one.

### Treat contradictions as information

When participants disagree, the disagreement is usually the finding. Look for a segment difference behind it — new versus long-term, one plan versus another, one market versus another. A contradiction that splits cleanly along a segment line is a discovery. One that doesn't usually means you need more interviews.

### Spot-check before you share

Follow a few quotes back to their transcripts before a report goes to stakeholders. It takes minutes, it catches the occasional quote that reads differently in context, and it means you can answer "where did this come from?" in the meeting.

### Consider Sample Size

How much your sample supports depends on how common the thing you're looking for is. Five interviews is plenty for something half your users hit and close to a coin flip for anything affecting 1 in 10.

Work out what your number actually buys — and how many you'd need for the confidence you want — with the [sample size calculator](/resources/sample-size).

Always state your sample size when sharing findings, and state it **per segment** if you split the sample.

### Connect Insights to Actions

Every insight should connect to potential action:

| Insight | Action |
| - | - |
| "Checkout feels slow" | Investigate performance; A/B test improvements |
| "Confused about pricing tiers" | Revise pricing page; test clearer copy |
| "Love the mobile app" | Double down on mobile investment |

If an insight doesn't connect to a potential action, consider whether it was worth learning.

### Share Widely, But Appropriately

| Audience | What to Share |
| - | - |
| Executives | Executive Summary + Top Insights |
| Product teams | Detailed findings + specific quotes |
| Marketing | Customer language + perception insights |
| Sales | Objection patterns + competitive intelligence |

***

## Building a Research Practice

### Create Recurring Studies

For ongoing intelligence, establish:

* **Quarterly brand tracking** — the same questions to a fresh sample each quarter
* **Monthly churn research** — talk to people shortly after they leave
* **Continuous onboarding feedback** — via the [embed widget](/recruiting/embed-widget)
* **Post-launch research** for each major release

Panel studies can do this for you: set a [recurring panel](/recruiting/research-panel#recurring-panels) to weekly or monthly and each wave lands in the same study, so the comparison stays like-for-like.

### Build Institutional Knowledge

User Intuition's Intelligence Hub becomes more valuable over time:

* Query across historical studies
* Identify long-term trends
* Preserve knowledge through team changes
* Accelerate onboarding for new team members

### Close the Loop

After each study:

1. Share findings with stakeholders
2. Identify 2-3 concrete actions
3. Track whether actions were taken
4. Measure impact where possible
5. Document learnings for future studies

***

## Common Mistakes to Avoid

<AccordionGroup>
  <Accordion title="Asking leading questions">
    **❌** "Don't you think our checkout is confusing?"\
    **✅** "Walk me through your experience with checkout."
  </Accordion>

  <Accordion title="Covering too many topics">
    **❌** 20 topics in a 15-minute interview\
    **✅** 5-6 topics explored deeply
  </Accordion>

  <Accordion title="Ignoring low-quality responses">
    Low-quality responses often reveal confusion or disengagement—which is itself a finding worth investigating.
  </Accordion>

  <Accordion title="Over-indexing on single responses">
    One passionate participant doesn't make a pattern. Wait for consistent themes across multiple interviews.
  </Accordion>

  <Accordion title="Researching without acting">
    Research that doesn't lead to action wastes resources and erodes organizational trust in research value.
  </Accordion>

  <Accordion title="Editing studies mid-collection">
    Resist the urge to tweak questions once interviews have begun. Note improvements for next time instead.
  </Accordion>
</AccordionGroup>

***

## Quick Reference

### Study Setup Checklist

* [ ] Clear research objective defined
* [ ] 4-6 focused topics identified
* [ ] Questions written in participant language
* [ ] Decision/action identified for insights
* [ ] Study tested before launch

### Recruitment Checklist

* [ ] Target participants identified
* [ ] Invitation includes time estimate
* [ ] Incentive communicated (if applicable)
* [ ] Reminder plan in place
* [ ] Early responses monitored

### Analysis Checklist

* [ ] Listened to sample of interviews (not just read transcripts)
* [ ] Patterns identified across multiple participants
* [ ] Sample size noted with findings
* [ ] Insights connected to actions
* [ ] Appropriate sharing with stakeholders


# Billing and credits
Source: https://docs.userintuition.ai/resources/billing-and-credits

Manage your plan, buy credits, track usage, and configure payment methods.

User Intuition runs on credits. Every interview consumes credits based on its format, and you manage your balance, plan, and payment methods from the **Billing** page.

***

## Accessing billing

Click **Billing** in the left navigation, or go to [app.userintuition.ai/wallet](https://app.userintuition.ai/wallet).

***

## Plans

| Plan | Price | Credits included | Per additional credit |
| - | - | - | - |
| **Starter** | Free, pay as you go | — | **\$30** |
| **Professional** | **\$2,499/month** | **100 credits/month** | **\$25** |
| **Enterprise** | Custom | Custom | Custom |

Included credits don't roll over between billing periods.

### What Professional adds

* Intelligence Hub, including cross-study analysis and unlimited queries
* Report and PowerPoint generation from the Intelligence Hub
* Slack support

### Subscribing to a plan

<Steps>
  <Step title="Choose a plan">
    On the Billing page, select **Starter**, **Professional**, or **Enterprise**.
  </Step>

  <Step title="Add a payment method">
    If you don't have a card on file, you'll be prompted for one.
  </Step>

  <Step title="Confirm">
    Click **Subscribe**. For Enterprise, click **Contact Sales** instead.
  </Step>
</Steps>

To cancel a subscription, email [support@userintuition.ai](mailto:support@userintuition.ai). Your plan stays active until the end of the current billing period.

***

## Credits

Credits are the currency for running interviews. How many an interview costs depends on its format:

| Interview format | Credits per interview |
| - | - |
| **Chat** | 0.5 |
| **Voice** | 1 |
| **Video** | 2 |

On Starter, that works out to \$15 for a chat interview, \$30 for voice, and \$60 for video. On Professional, \$12.50, \$25, and \$50.

### Which interviews you're charged for

Not every completed interview costs you credits. It depends on its [quality rating](/results/calls-and-transcripts#quality-ratings) and which lane the study is in:

| Quality rating | Panel studies | Your own participants |
| - | :-: | :-: |
| **Excellent** | Charged | Charged |
| **Good** | Charged | Charged |
| **Fair** | Free | Charged |
| **Poor** | Free | Free |

Panel studies hold to the higher bar because we chose the participants — if our sourcing produces a thin conversation, you don't pay for it. The **\$30 per-participant** panel cost follows the same rule.

Your balance is shown on the Billing page. A low-balance warning appears when you drop below 3 credits.

<Note>
  Test conversations are free and never consume credits.
</Note>

### Buying credits

<Steps>
  <Step title="Click Buy more credits">
    On the Billing page, click **Buy more credits** in the Credit Balance card.
  </Step>

  <Step title="Enter how many credits you want">
    Enter a number of credits — minimum 1. The dialog shows the dollar total at your plan's rate before you confirm.
  </Step>

  <Step title="Confirm">
    Click **Add Credits** to charge the card on file. Credits land in your balance immediately.
  </Step>
</Steps>

### Redeeming a coupon

Click **Apply coupon** on the Credit Balance card, enter your code, and click **Redeem**. Credits are added immediately and a confirmation shows how many were applied.

### Auto-reload

Auto-reload tops up your balance automatically when it runs low, so an active study doesn't stall.

1. Toggle **Enable auto reload** on
2. Set how many credits to add each time it triggers

Changes save automatically.

<Warning>
  Auto-reload stops working if there's no payment method on file.
</Warning>

***

## Payment methods

You need a card on file to buy credits, subscribe to a plan, or send participant rewards.

<Steps>
  <Step title="Find the payment method card">
    On the Billing page, locate the **Payment Method** section.
  </Step>

  <Step title="Click Add or Edit">
    Click **Add** if you have no card on file, or **Edit** to replace one.
  </Step>

  <Step title="Enter card details">
    Fill in your card number, expiry, and CVC. Card details are handled by our payment processor and never stored by User Intuition.
  </Step>

  <Step title="Save">
    Submit. Your card brand and last four digits appear as confirmation.
  </Step>
</Steps>

### Billing email

You can set a billing email separate from your account email. Update it on the Billing page under **Billing Email**.

***

## Research panel pricing

Recruiting from the research panel costs **\$30 per participant** on top of credits. That's a pass-through cost covering the participant's incentive, screening, and fraud prevention, and you're billed only on quality completes.

Niche audiences — B2B roles, executives, and other people the consumer panel can't reach — are quoted individually. See [Research panel](/recruiting/research-panel).

Interviewing your own participants costs nothing beyond credits.

***

## Usage stats

The **Usage stats** tab shows your interview activity over time:

* Total completed interviews for the period
* Total credits used
* A bar chart of credit consumption

Toggle between **Daily** and **Weekly**, and use the dropdown to pick a month.

***

## Transaction history

The **Transactions** tab lists all billing activity in reverse-chronological order.

| Type | Description |
| - | - |
| **Deposit** | Credits added to your wallet |
| **Payment** | Credits charged for interview usage |
| **Reward** | Participant incentive sent as a digital gift card |
| **Refund** | Credits returned to your wallet |
| **Subscription** | Recurring plan charges |

| Status | Indicator |
| - | - |
| **Completed** | Green dot |
| **Pending** | Yellow dot |
| **Processing** | Gray dot |
| **Deferred** | Blue dot |
| **Failed** | Red dot |

<Note>
  Enterprise customers see **deferred** reward transactions. These are billed at the end of the billing cycle rather than debited from the wallet immediately.
</Note>

Each row shows the description, timestamp, amount (green for deposits, red for charges), and status. Click **Load More** for older transactions.

***

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do test conversations cost credits?">
    No. Test conversations are free and unlimited.
  </Accordion>

  <Accordion title="What happens when I run out of credits?">
    Your studies can't run new interviews until you add more. Enable auto-reload to avoid the interruption.
  </Accordion>

  <Accordion title="Do included credits roll over?">
    No. Professional's 100 monthly credits reset each billing period.
  </Accordion>

  <Accordion title="Can I get a refund on unused credits?">
    Email [support@userintuition.ai](mailto:support@userintuition.ai) to discuss refund options.
  </Accordion>

  <Accordion title="How do I cancel my subscription?">
    Email [support@userintuition.ai](mailto:support@userintuition.ai). Your plan remains active until the end of the current billing period.
  </Accordion>
</AccordionGroup>


# Frequently Asked Questions
Source: https://docs.userintuition.ai/resources/faq

Answers to commonly asked questions about User Intuition, from getting started to advanced features.

Answers to commonly asked questions about User Intuition. Can't find what you're looking for? [Contact support](/resources/support).

***

## Getting Started

<AccordionGroup>
  <Accordion title="What is User Intuition?">
    User Intuition is an AI-powered customer intelligence platform that conducts natural voice interviews to uncover the "why" behind customer decisions. Our AI interviewer has deep conversations with your customers, and the platform synthesizes findings into actionable insights.
  </Accordion>

  <Accordion title="How is User Intuition different from surveys?">
    Traditional surveys collect structured, quantitative data. User Intuition conducts actual conversations—asking follow-up questions, probing deeper on interesting responses, and adapting to each participant. This reveals motivations, emotions, and context that surveys miss.
  </Accordion>

  <Accordion title="Do I need technical skills to use User Intuition?">
    No. Creating a study is as simple as having a conversation with Charles, our AI researcher. The only technical requirement is implementing the widget if you want to embed it in your app (and even that's just copying provided code).
  </Accordion>

  <Accordion title="How long does it take to set up a study?">
    Most users complete setup in 10-15 minutes. You'll work with Charles to customize your research plan, configure your interviewer, and launch.
  </Accordion>
</AccordionGroup>

***

## Studies and Interviews

<AccordionGroup>
  <Accordion title="What types of research can I do with User Intuition?">
    There are three study types: **In-depth Interview** (a conversation, no stimulus), **Concept Test** (reactions to an image or video), and **Prototype Test** (watching people work through a prototype or live site). Whatever the topic — why deals are won or lost, why customers leave, what's breaking in onboarding — it's one of these three. See [Study types](/study-types/overview).
  </Accordion>

  <Accordion title="How long are the interviews?">
    Most interviews run 10-20 minutes, depending on your research plan. You can adjust the depth and number of topics to control interview length.
  </Accordion>

  <Accordion title="Can I edit my study after launching?">
    Yes, but we recommend against making changes after participants have completed interviews. Changing methodology mid-study compromises data comparability.
  </Accordion>

  <Accordion title="What happens if a participant drops off mid-interview?">
    Partial responses are recorded and marked accordingly. You'll have access to whatever portion of the conversation was completed.
  </Accordion>

  <Accordion title="Can I run multiple studies at once?">
    Yes. You can have multiple active studies running simultaneously. Each study has its own dashboard.
  </Accordion>
</AccordionGroup>

***

## Participants and Recruiting

<AccordionGroup>
  <Accordion title="Can I interview my own customers?">
    Yes—and we recommend it. User Intuition is designed for interviewing your actual customers, which produces more relevant and actionable insights than panel participants.
  </Accordion>

  <Accordion title="What if I don't have customer email addresses?">
    You have several options: use our research panel of 4M+ participants, share a study link on social media or your website, or embed the widget in your app.
  </Accordion>

  <Accordion title="How does the research panel work?">
    Our panel includes over 4 million verified participants across 58 countries and diverse demographics. You specify how many responses you need, and we recruit qualified participants.
  </Accordion>

  <Accordion title="Which countries can you recruit in?">
    58, across the Americas, Europe, Asia-Pacific, the Middle East, and Africa — the United States, Canada, Mexico, the UK, most of Western and Central Europe, Australia and New Zealand, Japan, South Korea, China, India, Southeast Asia, Brazil and much of Latin America, the UAE, Saudi Arabia, South Africa, Nigeria, Kenya and more. See [Where we recruit](/recruiting/research-panel#where-we-recruit) for the full list. You pick one country per panel, and the picker is filtered by your study's interview language. For a country that isn't on the list, [niche audience recruiting](/recruiting/research-panel#recruit-a-niche-audience) can usually source it.
  </Accordion>

  <Accordion title="Can I offer incentives to participants?">
    Yes, for studies where you bring your own participants. Set an amount between **\$5 and \$500** per completed interview from the dashboard **Actions** menu. Rewards are sent as digital gift cards and debited from your wallet, and only offered for interviews rated Excellent or Good. You need a [payment method on file](/resources/billing-and-credits#payment-methods). User Intuition manages incentives for panel participants.
  </Accordion>

  <Accordion title="How do I improve response rates?">
    Send personalized invitations, set clear time expectations, mention any incentives, send reminders to non-responders, and time invitations appropriately.
  </Accordion>
</AccordionGroup>

***

## AI Interviewer

<AccordionGroup>
  <Accordion title="Who are Elliot and Clara?">
    Elliot and Clara are our AI interviewer voices. Elliot is a male voice with an American accent, known for a soothing, friendly tone. Clara is a female voice with an American accent, known for a calming, professional demeanor.
  </Accordion>

  <Accordion title="How does the AI know what to ask?">
    The AI follows your research plan but adapts dynamically to each conversation. It uses laddering techniques to probe deeper when participants say something interesting, much like a skilled human interviewer would.
  </Accordion>

  <Accordion title="Can participants tell they're talking to an AI?">
    Participants are informed they're speaking with an AI moderator. However, our conversational quality is so natural that many participants report feeling like a genuine conversation—leading to our 98% participant satisfaction rate.
  </Accordion>

  <Accordion title="What languages are supported?">
    User Intuition supports 82 interview languages, plus auto-detect. English is the default. When you select a specific non-English language, the moderator's participant-facing messages and screener questions are localized automatically. See [Setup Interview](/creating-a-study/setup-interview#interview-language) for the complete language and ISO-code list.
  </Accordion>
</AccordionGroup>

***

## Data and Analysis

<AccordionGroup>
  <Accordion title="How do I access interview transcripts?">
    Transcripts are available as soon as an interview finishes processing. Open the Calls tab on your study dashboard to read them and play back the recording.
  </Accordion>

  <Accordion title="How are reports generated?">
    Reports are generated on-demand after you have at least 2 completed interviews. Click "Generate Report" in the Reports tab to create your analysis.
  </Accordion>

  <Accordion title="Will reports update automatically?">
    Currently, you need to manually regenerate reports to include new responses. Automatic updates are on our roadmap.
  </Accordion>

  <Accordion title="How is interview quality rated?">
    Every completed interview is rated **Excellent**, **Good**, **Fair**, or **Poor**, based on how long the conversation ran, how substantive the answers were, and how much of your research plan it covered.
  </Accordion>

  <Accordion title="Can I export my data?">
    Yes. Transcripts and reports can be exported for external analysis or sharing. Professional and Enterprise customers can also generate PowerPoint presentations from the [Intelligence Hub](/results/intelligence-hub).
  </Accordion>

  <Accordion title="What is the Intelligence Hub?">
    The Intelligence Hub is an AI-powered workspace where you can aggregate data from multiple studies and external documents, ask questions across all your research, and generate reports and presentations. It is available on the Pro plan and above. See [Intelligence Hub](/results/intelligence-hub) for details.
  </Accordion>
</AccordionGroup>

***

## Privacy and Security

<AccordionGroup>
  <Accordion title="Is participant data secure?">
    Yes. We follow industry-standard security practices to protect all participant data. Contact us for detailed security documentation.
  </Accordion>

  <Accordion title="How long is data retained?">
    Data retention varies by plan. Contact support for specific retention policies.
  </Accordion>

  <Accordion title="Can I delete participant data?">
    You can delete individual invitations. Deleting a study removes all associated data permanently.
  </Accordion>

  <Accordion title="Is User Intuition GDPR compliant?">
    Contact our team for detailed compliance documentation and data processing agreements.
  </Accordion>
</AccordionGroup>

***

## Billing and Plans

<AccordionGroup>
  <Accordion title="How is User Intuition priced?">
    Three: **Starter** (free, pay as you go at \$30/credit), **Professional** (\$2,499/month including 100 credits, then \$25/credit), and **Enterprise** (custom). See [Billing and credits](/resources/billing-and-credits).
  </Accordion>

  <Accordion title="How do credits work?">
    Credits are consumed by interview format: chat 0.5, voice 1, video 2. Buy more credits or enable auto-reload from the [Billing page](/resources/billing-and-credits).
  </Accordion>

  <Accordion title="Do test conversations count against my limits?">
    No. Test conversations are free and unlimited. Only real participant interviews count toward your usage.
  </Accordion>

  <Accordion title="Can I use a coupon or promo code?">
    Yes. On the Billing page, click **Apply coupon** and enter your code. Credits are added to your balance immediately.
  </Accordion>

  <Accordion title="What payment methods are accepted?">
    User Intuition accepts credit and debit cards. Card details are handled by our payment processor and never stored by User Intuition.
  </Accordion>

  <Accordion title="What happens if I run out of credits?">
    You won't be able to launch new studies or process new interviews until you add more credits. You can buy credits anytime from the [Billing page](https://app.userintuition.ai/wallet), or enable auto-reload to top up automatically.
  </Accordion>

  <Accordion title="How much does the research panel cost?">
    Research panel participants cost **\$30 each**, billed only on quality completes. That's a pass-through cost covering the incentive, screening, and fraud prevention. Niche audiences are quoted individually. Interviewing your own participants costs nothing beyond credits.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="My participant couldn't connect to the interview">
    Ensure participants have a stable internet connection and a compatible browser. Voice interviews need microphone permission; video needs camera and microphone.
  </Accordion>

  <Accordion title="The transcript seems inaccurate">
    Transcription accuracy is typically 95%+. Background noise or strong accents may reduce accuracy. Reference the audio recording for verification.
  </Accordion>

  <Accordion title="My report seems incomplete">
    Reports require substantive data. Ensure you have at least 2 completed interviews with high-quality responses. More interviews produce richer reports.
  </Accordion>
</AccordionGroup>

***

## Still Have Questions?

<Card title="Contact Support" icon="envelope" href="/resources/support">
  Our team is here to help. Reach out for personalized assistance.
</Card>


# Referrals
Source: https://docs.userintuition.ai/resources/referrals

Invite friends to User Intuition and earn credits when they sign up and make their first payment.

User Intuition's referral program rewards you for introducing other researchers to the platform. Send an invitation by email, and once your friend signs up and makes their first payment, you earn credits toward your own studies.

***

## How it works

<CardGroup>
  <Card title="1. Invite" icon="paper-plane">
    Enter a friend's email from the **Refer a Friend** dialog.
  </Card>

  <Card title="2. They sign up" icon="user-plus">
    Your friend receives an email invitation with a link to create their account.
  </Card>

  <Card title="3. You earn credits" icon="coins">
    Once they make their first payment, your referral is credited and bonus credits are added to your wallet.
  </Card>
</CardGroup>

<Note>
  Credits earned through referrals can be spent on any interview mode (Chat, Voice, or Video) just like purchased credits. See [Billing and credits](/resources/billing-and-credits) for credit consumption rates.
</Note>

***

## Inviting a friend

The referral dialog is reachable from your profile menu in the top-right of the dashboard.

<Steps>
  <Step title="Open your profile menu">
    Click your avatar in the top-right of the dashboard, then choose **Refer a Friend**.
  </Step>

  <Step title="Enter your friend's email">
    Type the email address of the person you'd like to invite. Press **Enter** or click **Invite**.
  </Step>

  <Step title="Confirmation">
    You'll see a "Invitation sent!" toast, and your friend appears in **Your referrals** with a **Pending** status.
  </Step>
</Steps>

### What your friend receives

Your friend gets an email with the subject line:

> **\<Your name> invited you to User Intuition**

The email contains a link to the User Intuition sign-up page. The display name is taken from your account profile; if you haven't set one, the part of your email before the `@` is used instead.

<Warning>
  Email invitations are sent only from the production environment. If you're testing on a staging or local instance, the referral record will still be created, but the email won't be delivered.
</Warning>

***

## Tracking your referrals

The same **Refer a Friend** dialog shows the full list of people you've invited under **Your referrals**, along with each referral's current status.

| Status | Meaning |
| - | - |
| **Pending** | Your friend has been invited but has not yet signed up and made their first payment. |
| **Credited** | Your friend signed up and paid; bonus credits have been added to your wallet. |

Credited entries display the bonus amount inline (e.g., **Credited (+10)**) so you can see exactly what each conversion earned.

***

## Resending an invitation

If a friend hasn't acted on your invite yet, you can re-send the email without creating a duplicate referral.

<Steps>
  <Step title="Open Refer a Friend">
    Find the pending referral in **Your referrals**.
  </Step>

  <Step title="Click Resend">
    Click the **Resend** button next to the friend's email. A "Sending..." indicator appears while the email is dispatched.
  </Step>

  <Step title="Confirmation">
    A "Invitation resent!" toast confirms delivery.
  </Step>
</Steps>

<Note>
  The **Resend** button only appears on referrals with a **Pending** status. Once a referral has been credited, or if your friend has already created an account through some other path, resend is no longer available.
</Note>

***

## Rules and limits

A few constraints apply to keep the program fair:

<CardGroup>
  <Card title="No self-referrals" icon="ban">
    You cannot enter your own account email as a referral.
  </Card>

  <Card title="One referral per email" icon="shield-check">
    You can only have one active referral per email address. Trying to invite the same person twice returns "You've already invited this person."
  </Card>

  <Card title="New users only" icon="user-check">
    If the email already belongs to a registered User Intuition user, the invite is rejected with "This person already has an account."
  </Card>

  <Card title="Payment required to credit" icon="credit-card">
    A referral moves from **Pending** to **Credited** only after the invited user makes their first payment, not at sign-up.
  </Card>
</CardGroup>

***

## Frequently asked questions

<AccordionGroup>
  <Accordion title="When do I get my credits?">
    Credits land in your wallet automatically when your friend makes their first payment in User Intuition. You don't need to claim anything; the referral entry flips to **Credited** and the bonus appears in your balance.
  </Accordion>

  <Accordion title="Can I refer someone in my own organization?">
    The referral check is based on email address. If a teammate already has a User Intuition account under any organization, you'll get the "This person already has an account" error and won't be able to refer them.
  </Accordion>

  <Accordion title="What if my friend never signs up?">
    The referral simply stays in **Pending**. There's no expiry that removes it from your list, and you can resend the invitation email at any time while it remains pending.
  </Accordion>

  <Accordion title="Are referral credits any different from purchased credits?">
    No. Referral credits are added to the same wallet balance and behave identically. They can be used for any [interview mode](/resources/billing-and-credits#credits) and never expire while your wallet is active.
  </Accordion>
</AccordionGroup>


# How many interviews do you need?
Source: https://docs.userintuition.ai/resources/sample-size

One question — how common the thing you're looking for is — and the number of interviews you need to be confident you'd hear about it.

Most studies are smaller than the confidence people want from them. Ten interviews feels thorough, so ten gets run — and then a finding gets treated as settled when the sample never had the power to settle it.

One question gets you the number you actually need.

<SampleSizeCalculator />

***

## What it's calculating

The question here is **discovery**: if something is true of a share of your participants, how likely are you to hear about it at least once?

If a problem affects a proportion `p` of the people you interview, the chance that `n` interviews surface it at least once is:

```
P = 1 − (1 − p)ⁿ
```

Turn that around and you get the number of interviews needed for a given confidence:

```
n = ln(1 − C) / ln(1 − p)
```

Nothing exotic — it's the same reasoning behind the usability-testing rules of thumb you may have run into, stated properly instead of as "five users is enough."

### Why "five users is enough" isn't

That rule assumes every problem is common. It falls apart quickly when they aren't:

| Interviews | 50 in 100 | 33 in 100 | 20 in 100 | 10 in 100 | 5 in 100 |
| -: | -: | -: | -: | -: | -: |
| **5** | 97% | 86% | 67% | 41% | 23% |
| **8** | 100% | 96% | 83% | 57% | 34% |
| **10** | 100% | 98% | 89% | 65% | 40% |
| **15** | 100% | 100% | 96% | 79% | 54% |
| **20** | 100% | 100% | 99% | 88% | 64% |
| **30** | 100% | 100% | 100% | 96% | 79% |

Five interviews is genuinely fine for something 50 in 100 people would mention. For anything only 10 in 100 would mention, it's a coin flip — and the issues that quietly cost you customers are usually the uncommon ones.

### Interviews needed, by target confidence

| Confidence | 50 in 100 | 33 in 100 | 20 in 100 | 10 in 100 | 5 in 100 |
| -: | -: | -: | -: | -: | -: |
| **80%** | 3 | 5 | 8 | 16 | 32 |
| **90%** | 4 | 6 | 11 | 22 | 45 |
| **95%** | 5 | 8 | 14 | 29 | 59 |
| **99%** | 7 | 12 | 21 | 44 | 90 |

***

## Using it well

### Count per segment, not per study

The maths applies to the group you're actually talking to. If your study covers four personas and you run 20 interviews, that's **five per persona** — so treat it as four studies of five, not one study of twenty.

Splitting a sample across segments is the most common way a study that looked adequately sized turns out not to be.

### Be honest about how common it is

You're estimating prevalence among **the people you interview**, not your whole user base. If your screener selects for people who've hit a specific problem, prevalence inside the study is much higher than in the wild — and you need fewer interviews, not more.

### Hearing it once isn't the same as sizing it

This tells you whether a theme is likely to *appear*. It doesn't tell you how big it is. One participant mentioning something means it exists; it doesn't tell you what share of your customers feel the same. If the decision depends on the size of the number rather than the existence of the problem, see below.

### More interviews still buy something

Past the point where coverage is settled, extra interviews buy depth: more ways of describing the same problem, more edge cases, better quotes, and enough repetition that you can tell a real pattern from a vivid anecdote.

***

## When you need a proportion, not a discovery

If your question is "**what percentage** of customers prefer A over B?" rather than "is there a problem here?", this calculator is the wrong tool. Estimating a proportion to within a margin of error takes far larger samples — typically several hundred — and is survey work rather than interview work.

You can still run it here: field a [panel study](/recruiting/research-panel) with a large target and structured screener questions, which come back as clean tabulated [responses](/results/calls-and-transcripts). Just size it as a survey, and budget accordingly.

<Tip>
  A common pattern is to run both: a small interview study to find out *what* the issues are, then a larger one to size the ones that matter. Discovery first is usually cheaper, because it stops you sizing the wrong thing.
</Tip>

***

## Setting your target

Once you've got a number, set it as your study target — for [panel studies](/recruiting/research-panel#recruit-from-our-panel) that's the interview count you enter when you field. Progress against it shows on your [dashboard](/managing-your-study/dashboard).

Remember that on panel studies you're only charged for interviews rated Excellent or Good, so your target is a target for *usable* interviews rather than attempts. See [Billing and credits](/resources/billing-and-credits).

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Is this the same calculation as a survey sample size calculator?">
    No, and the difference matters. Survey calculators size a sample to estimate a proportion within a margin of error, which for a large population usually lands somewhere north of 380 responses. This sizes for **discovery** — whether you'd hear about something at all — which is what interview research is for and typically lands between 20 and 50.
  </Accordion>

  <Accordion title="What confidence level should I pick?">
    This sizes at 99% by default — strict enough that finding nothing actually tells you something. Drop to 95% for most work, or 90% and 80% for exploratory studies where you're forming hypotheses rather than settling a question. Lowering it is the fastest way to cut a target that's come back bigger than your budget.
  </Accordion>

  <Accordion title="What if I don't know how common the thing is?">
    That's normal — you're doing the research to find out. Pick the rarest thing you'd be unhappy to miss and size for that. If it would be a problem to miss something only 10 in 100 people would mention, size for 10.
  </Accordion>

  <Accordion title="Does this apply to concept and prototype tests too?">
    Yes. "Would you hear about this reaction, or this point where people get stuck?" is the same question. Usability issues in particular tend to be less common than people expect, which is why prototype tests are so often under-sized.
  </Accordion>

  <Accordion title="I ran fewer interviews than this. Is my research worthless?">
    No. It means you should treat what you found as real and what you *didn't* find as unproven. A small study that surfaces a problem has surfaced a problem. What it can't support is "we looked and there's nothing there."
  </Accordion>
</AccordionGroup>


# Contact Support
Source: https://docs.userintuition.ai/resources/support

Get help with User Intuition. Contact our team, access resources, and find answers to your questions.

Need help with User Intuition? Our team is here to assist you.

***

## Contact Us

### Email Support

For general questions, technical issues, or account assistance:

<Card title="Email Support" icon="envelope">
  **[support@userintuition.ai](mailto:support@userintuition.ai)**

  Typical response time: Within 24 hours on business days
</Card>

### Sales Inquiries

For pricing, enterprise features, or custom solutions:

<Card title="Sales" icon="handshake">
  **[sales@userintuition.ai](mailto:sales@userintuition.ai)**
</Card>

***

## Before Contacting Support

To help us assist you faster, please have ready:

1. **Your account email** associated with User Intuition
2. **Study name** (if the issue is study-specific)
3. **Description of the issue** including steps to reproduce
4. **Screenshots** if applicable
5. **Browser and device** you're using

***

## Self-Service Resources

<CardGroup>
  <Card title="Documentation" icon="book" href="/introduction/welcome">
    Browse our complete documentation for step-by-step guides
  </Card>

  <Card title="FAQ" icon="circle-question" href="/resources/faq">
    Find answers to commonly asked questions
  </Card>

  <Card title="Best Practices" icon="star" href="/resources/best-practices">
    Learn tips for maximizing research value
  </Card>

  <Card title="Key Concepts" icon="lightbulb" href="/getting-started/key-concepts">
    Understand platform fundamentals
  </Card>
</CardGroup>

***

## Common Support Topics

### Account Issues

* Login problems
* Password reset
* Team member access
* Account settings

### Study Issues

* Study creation problems
* Interview issues
* Transcript access
* Report generation

### Technical Issues

* Widget implementation
* Browser compatibility
* Audio/video problems
* Integration setup

### Billing

* Plan questions
* Usage limits
* Invoice requests
* Plan upgrades

***

## Feature Requests

Have an idea for improving User Intuition? We love hearing from our users.

Share your feature requests by emailing **[feedback@userintuition.ai](mailto:feedback@userintuition.ai)** with:

* Description of the feature
* Use case or problem it would solve
* How important it is for your workflow

We review all feedback and use it to inform our roadmap.

***

## Report an Issue

If you've encountered a bug or unexpected behavior:

1. **Check if it's a known issue** by reviewing recent communications
2. **Document the problem** with screenshots and steps to reproduce
3. **Email support** with your findings
4. **Include browser/device info** for technical issues

***

## Service Status

If you're experiencing widespread issues, check the [service status page](https://status.userintuition.ai/) for current API, MCP, dashboard, and documentation checks. A failed automated check signals a possible issue; contact support if your workflow is affected.

***

## Enterprise Support

Enterprise customers have access to enhanced support options including:

* Dedicated Customer Success Manager
* Priority response times
* Custom training and onboarding
* Integration assistance
* Custom report requirements

Contact your account manager or email **[enterprise@userintuition.ai](mailto:enterprise@userintuition.ai)** for enterprise support.


# Calls & Transcripts
Source: https://docs.userintuition.ai/results/calls-and-transcripts

Review completed interviews: the calls list, quality ratings, and the transcript, responses, and summary for every conversation.

As participants complete interviews, you can review each conversation in detail. The **Calls** tab on your study dashboard gives you every completed interview, with its transcript, its screener answers, and a summary of what it produced.

***

## The calls list

Open the **Calls** tab on your study dashboard. Each row is one interview.

| Column | Description |
| - | - |
| **Email** | The participant |
| **Status** | Where the interview got to |
| **Date & Time** | When it happened |
| **Duration** | How long it ran |
| **Quality** | Excellent, Good, Fair, or Poor |
| **End Reason** | How the conversation ended |
| **Reward** | Only shown when rewards are enabled |

Click any row to expand it.

### Status

Most rows read **Completed** or **Ended** — the interview happened and the data is in. **Active** means someone is in the conversation right now. **Pending** and **Processing** are transient: the interview is queued, or it's finished and the transcript and analysis are still being prepared. Give processing rows a few minutes.

### Quality ratings

Every completed interview is rated on three things: how long the conversation ran, how substantive the answers were, and how much of your research plan it actually covered.

| Rating | Meaning | Charged on panel | Charged on your own participants |
| - | - | :-: | :-: |
| **Excellent** | Rich, detailed responses across the full plan | Yes | Yes |
| **Good** | Solid responses with good coverage | Yes | Yes |
| **Fair** | Usable, but thin in places | No | Yes |
| **Poor** | Minimal answers, or the conversation ended early | No | No |

The difference on **Fair** comes down to who picked the participant. On panel studies we did the recruiting, so a thin conversation is our sourcing problem and you aren't charged. On your own studies you control who gets the link. See [Study actions](/managing-your-study/study-actions#what-youre-charged-for-side-by-side).

### Filtering by quality

Use the filter above the table to choose which ratings you want to see. Excellent, Good, and Fair are shown by default.

**Poor is hidden once you have enough responses** for it not to matter — on a study with only a handful of interviews it stays visible, so you're never looking at an empty table. Tick it any time to bring those rows back.

### End reasons

| End reason | What happened |
| - | - |
| **Customer Ended Call** | The participant ended the conversation |
| **Assistant Ended Call** | The moderator wrapped up after covering everything |
| Anything else | The system ended it — a connection problem, a long silence, or the maximum call length |

An interview that ended early isn't automatically a bad one. Check the quality rating and the transcript before discounting it.

***

## Reviewing a single interview

Expanding a row gives you three tabs.

### Transcript

The full conversation as a chat-style transcript, with the moderator's turns on one side and the participant's on the other, timestamped throughout.

Above it are playback controls for the recording — audio for voice studies, video or screen replay where the study captured them. Click any transcript segment to jump to that moment in the recording.

<Tip>
  Read the transcript, but listen to at least a few. Tone, hesitation, and emphasis don't survive the transcription.
</Tip>

### Responses

Every answer the participant gave to your screener questions, so you can see who you were actually talking to.

### Summary

What this specific interview produced:

* **Overall takeaways** — the headline points from the conversation
* **Each key question from your research plan**, with what this participant said in response and a supporting quote where there is one

Questions the conversation never got to are shown as unanswered, so you can see coverage gaps at a glance rather than reading the whole transcript to find them.

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I download transcripts?">
    Yes. Use the export options to download individual transcripts or export in bulk.
  </Accordion>

  <Accordion title="Are transcripts generated automatically?">
    Yes, and they're available as soon as the interview finishes processing.
  </Accordion>

  <Accordion title="How accurate are the transcripts?">
    Generally 95%+ on clear audio. Background noise and strong accents reduce that. The recording is always there to check against.
  </Accordion>

  <Accordion title="Can I edit a transcript?">
    No. Transcripts are read-only so the record stays faithful to what was said.
  </Accordion>

  <Accordion title="Can I share one interview with a colleague?">
    Anyone with access to the study can see all of its interviews. For sharing outside your team, use the export options.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup>
  <Card title="Reports" icon="chart-bar" href="/results/reports">
    Synthesis across every interview in the study
  </Card>

  <Card title="Intelligence Hub" icon="brain" href="/results/intelligence-hub">
    Analysis across every study you've run
  </Card>
</CardGroup>


# Intelligence Hub
Source: https://docs.userintuition.ai/results/intelligence-hub

Combine data from every study into one searchable workspace, ask questions in plain language, and generate reports and presentations from the answers.

The Intelligence Hub is a workspace where you combine data from multiple studies, ask questions in plain language, and generate structured outputs like reports and presentations. Every completed interview can feed into the hub, so your searchable repository of customer knowledge grows with each study you run.

<Info>
  The Intelligence Hub is included on the **Professional** and **Enterprise** plans.
</Info>

***

## What you can do

| Capability | Description |
| - | - |
| **Cross-study analysis** | Ask questions that span several studies at once |
| **Document upload** | Add external files alongside your study data |
| **Chat** | Get cited answers drawn from your entire research library |
| **Report generation** | Create structured written analysis from your sources |
| **PowerPoint export** | Generate presentation-ready slide decks |
| **Sessions** | Organize work into separate workspaces with their own sources and history |

***

## Getting started

Click **Intelligence Hub** in the left navigation. Work is organized into **sessions** — independent workspaces, each with its own sources, chat history, and generated outputs.

<Steps>
  <Step title="Create a session">
    Click **New Session** and give it a name, such as "Q1 churn deep-dive."
  </Step>

  <Step title="Add sources">
    Use the **Sources** panel to sync completed studies or upload files.
  </Step>

  <Step title="Ask a question">
    Type into the **Chat** panel. The answer is drawn from every source in the session.
  </Step>
</Steps>

### Page layout

| Panel | Position | Purpose |
| - | - | - |
| **Sources** | Left | Add studies and upload files |
| **Chat** | Center | Ask questions about your data |
| **Studio** | Right | Generate reports and presentations |

***

## Adding sources

Sources are the data behind every answer and every generated output.

### Sync a study

Syncing a study pulls in its interview transcripts and its report.

<Steps>
  <Step title="Select a study">
    In the **Sources** panel, open the study dropdown. It lists completed studies not yet synced to this session.
  </Step>

  <Step title="Sync">
    Confirm the sync. A message shows how many transcripts came across and whether a report was included.
  </Step>
</Steps>

Use **Re-sync** on a source to pull in interviews that have completed since you first added it.

### Upload external files

Click **Add external sources** to upload documents alongside your study data.

| Category | Formats |
| - | - |
| Documents | `.pdf`, `.doc`, `.docx`, `.txt`, `.md`, `.html` |
| Spreadsheets and data | `.csv`, `.xlsx`, `.xls`, `.json` |
| Presentations | `.pptx` |

Files are indexed automatically; the status changes from **Uploading** to **Completed** when a file is ready to query. Deleting a source removes it from the session permanently.

<Tip>
  Upload competitor research, survey exports, or internal strategy documents to get answers that combine your interview data with the wider context.
</Tip>

***

## Asking questions

Type a question into the **Chat** panel. Answers are drawn from every source in the current session and stream in as they're written, with full formatting — tables, lists, and headings.

**Questions that work well:**

* **Patterns** — "What are the most common complaints across all onboarding interviews?"
* **Comparisons** — "How does satisfaction differ between new and returning customers?"
* **Specific topics** — "What did participants say about pricing?"
* **Cross-study** — "Compare what churned customers said with what current customers said."
* **Documents** — "Summarize the key findings from the PDF I uploaded."

Chat history saves automatically and persists between visits.

### Citations

Answers carry numbered references back to the source material. Click a citation to see the transcript or document it came from, so you can check any claim against what the participant actually said.

<Note>
  Answers can occasionally be inaccurate. For decisions that matter, follow the citations back to the source.
</Note>

***

## Generating outputs in Studio

The **Studio** panel turns your sources into deliverables. Both output types run in the background — you can keep chatting while they build.

### Reports

<Steps>
  <Step title="Click Reports">
    In the Studio panel, click **Reports**, then **Generate Report**.
  </Step>

  <Step title="Add a prompt">
    Describe what the report should focus on — for example, "Analyze satisfaction trends across all onboarding interviews and highlight the top three pain points, with supporting quotes."
  </Step>

  <Step title="Generate">
    Optionally name the report, then click **Generate**. Click the report name when it's ready to open it with its formatted content, associated interviews, and source references.
  </Step>
</Steps>

### PowerPoint presentations

<Steps>
  <Step title="Click PowerPoint">
    In the Studio panel, click **PowerPoint**, then **Generate PowerPoint**.
  </Step>

  <Step title="Add a prompt">
    Describe the focus — for example, "Cover the top three issues participants raised, one slide each, written for an executive audience."
  </Step>

  <Step title="Generate">
    Click **Generate**. View or download the deck once it completes.
  </Step>
</Steps>

### Managing outputs

Everything you generate appears in the Studio panel with its name, type, and creation date.

| Action | Description |
| - | - |
| **View** | Open the full output |
| **View prompt** | See the exact prompt used to generate it |
| **Rename** | Change the output name |
| **Delete** | Permanently remove the output |

***

## Managing sessions

Sessions keep separate projects from bleeding into each other.

| Action | How |
| - | - |
| **Create** | Click **New Session** and enter a name |
| **Switch** | Select a session from the session list |
| **Rename** | Click the session name to edit it |
| **Delete** | Open the session menu and select **Delete** |

Each session has its own sources, chat history, and generated outputs.

***

## Example workflow

1. **Create a session** — "Q4 customer insights."
2. **Sync studies** — add the three studies you ran last quarter.
3. **Upload supplementary data** — a competitor analysis PDF, a survey export.
4. **Ask questions** — "What are the top three reasons customers leave?"
5. **Generate a report** — "Synthesize findings across all three studies, focusing on what we should change first."
6. **Generate a presentation** — a stakeholder-ready deck from the same sources.

***

## Tips

<CardGroup>
  <Card title="Start narrow">
    Specific questions beat broad ones. "What did users say about the checkout flow?" outperforms "Tell me about the user experience."
  </Card>

  <Card title="Combine studies">
    The hub earns its keep when several studies are in one session and it can compare across them.
  </Card>

  <Card title="Write the prompt for the audience">
    A report for your product team should ask for different things than one for your board. Say which in the prompt.
  </Card>

  <Card title="Build over time">
    Each study you sync makes every future question richer.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="Reports" icon="chart-bar" href="/results/reports">
    Per-study report generation
  </Card>

  <Card title="Create a study" icon="plus" href="/creating-a-study/overview">
    Run more studies to feed the hub
  </Card>
</CardGroup>


# Understanding Reports
Source: https://docs.userintuition.ai/results/reports

User Intuition automatically synthesizes your interview data into actionable reports. Learn how to generate, interpret, and use AI-powered insights.

User Intuition automatically synthesizes your interview data into actionable reports. Reports transform hours of conversations into clear insights, recommendations, and supporting evidence.

***

## Accessing Reports

From your Study Dashboard:

1. Click the **Reports** tab
2. View the AI-generated analysis

<Note>
  A report needs usable interview evidence. Interview count alone does not establish whether the evidence is adequate for your research purpose.
</Note>

***

## Report Structure

Reports are organized into several sections designed to take you from high-level findings to supporting detail:

### Executive Summary

A one- or two-paragraph overview of the most important findings, followed by a compact set of within-sample metrics. It communicates what the study found without mixing in the separate assessment of evidence adequacy.

### Total Participants

A clear count of how many interviews contributed to this report (e.g., "Total Participants (N): 1"). This helps you and your stakeholders understand the sample size behind the insights.

### Key Insights

A short list of the most significant, source-linked findings and material exceptions. Key Insights are synthesized from the same full cross-participant review used for Detailed Findings; they are not generated from a separate evidence source.

### Detailed Findings

Each Learning Goal contains numbered findings. Every finding separates its main point, within-sample prevalence, verbatims, observed impact, variation and exceptions, interpretation and limits, and decision relevance. Counts always include both the count and percentage—for example, `2 of 5 participants (40%)`. These percentages describe only the report sample; they are not population estimates.

**Example:**

> * **Value is Price-Driven, Not Actively Tracked:** The participant defines value as getting "bargains" and low prices, trusting the overall basket total reflects savings rather than performing explicit ROI calculations.
>
> * **Pharmacy Lacks Credibility:** Despite using the pharmacy for convenience, the participant feels it lacks a "real health care experience" and desires more proactive counsel from staff.

### Detailed Analysis

In-depth exploration of findings organized by research objective or theme. Each section includes:

* **Key observations:** What the data shows
* **Supporting evidence:** Quotes and examples from interviews
* **Implications:** What this means for your business

### Recommendations

Zero to two justified next steps, each linked to an important evidence gap in the same report. If a material research gap is surfaced, the report must provide at least one linked next step. A valid empty list means the assessment found no actionable, decision-relevant research gap. An unavailable assessment is a different state. Recommendations require your existing review and launch approvals.

### Evidence Coverage

Evidence Coverage appraises the evidence behind Detailed Findings rather than repeating the findings. It describes the evidence available for each Learning Goal, coverage limitations, and the resulting decision boundary.

The study-level sample-adequacy assessment explains what the included interviews can and cannot support and whether additional interviews would materially help. It considers the research purpose, participant specificity, depth, variation, alternatives and missing perspectives instead of applying a universal sample-size threshold.

One prioritized gap list explains what remains unresolved and why it matters. Generic qualitative boundaries—such as not being able to estimate population prevalence or prove causal impact—remain decision boundaries unless the study purpose explicitly requires that decision. When report inputs are unchanged, regenerated reports reuse the last validated gap and linked recommendations. New interviews, plan edits, or generation-contract changes trigger a fresh assessment. Per-interview analysis remains available in Participant Responses and call evaluation, but is not aggregated into a separate study-level metric. Missing analysis does not automatically imply a need to recruit.

These assessments are interpretations, not adequacy scores. You decide whether the evidence is sufficient for the intended decision. Older or revised plans explicitly identify inferred requirements or uncertain timing.

***

## Generating Reports

### Initial Report Generation

Reports can be generated on demand when usable interviews are available:

1. Navigate to the **Reports** tab
2. Click **Generate Report** (if no report exists yet)
3. Wait for the AI to analyze your interviews and produce the report

### Updating Reports

As more responses come in, you'll need to regenerate the report to include new data:

1. Navigate to the **Reports** tab
2. Click **Regenerate Report**
3. The updated report will incorporate all completed interviews

<Info>
  **Coming Soon:** Automatic report regeneration after each new response.
</Info>

***

## Working with Reports

### Public API structure

`GET /api/public/v1/studies/{study_id}/report` returns a small `report-v2` overview by default. It includes identity, freshness, counts, a short `summary`, and `available_sections`. Pass `?view=study_findings`, `participant_profiles`, `participant_responses`, `evidence_coverage`, `recommended_next_steps`, or `references` to fetch one section; pass `?view=full` when the complete report is needed. `included_sections` identifies which sections were requested. `based_on_interview_ids_included` says whether the complete interview-ID list is present.

The selectable sections contain:

* `study_findings`: executive summary and metrics plus `learning_goals`, each containing stable `finding_id` values that Evidence Coverage can reference
* `participant_profiles`: an array of profile questions with stable, heading-derived `question_id` values
* `participant_responses`: every report-eligible call's `overall_takeaways` and `learning_goal_responses`
* `recommended_next_steps`
* `evidence_coverage`, containing its introductory `text`, `sample_adequacy`, per-goal `learning_goal_evaluations`, and prioritized `evidence_gaps`; recommendations link to these gaps through `gap_ids`

The public response intentionally omits the rendered report, Key Insights, duplicate open-question text, internal assessment fields, empty rendering wrappers, and presentation metadata such as Markdown, heading level, and display order. `evidence_gaps.learning_goal_ids` identifies the affected Learning Goal, and its `finding_ids` resolve directly to findings nested under that goal. New reports preserve the interview count, response analysis, evidence coverage, and recommendations from their generation snapshot. Later evidence or plan changes mark a report stale; reading it does not silently refresh its assessment. Legacy reports need regeneration to obtain evidence coverage.

Each finding has a stable ID, `reference_ids`, and structured `prevalence: { n, of }` when the saved report states an explicit within-sample frequency. Its `quotes[]` identifies source references, public interview IDs, transcript turn IDs, and stored start times when available. Older findings can have null prevalence or empty quotes; the API does not infer missing evidence. Fetch `?view=references` to resolve citation IDs, then `get_interview` for the source turn. Public report responses use `interview_id` as their interview join key.

New reports are indexed for research search and cited answers. `POST /api/public/v1/research/search/` searches canonical study plans and report objects across authorized studies. Search ranks candidates, but its `content` values are loaded from persisted Study/Report JSON. Results and index freshness are grouped under each entry in `studies`; check `index_status` separately from that study's `results` array. Follow `next_cursor` with the same request to continue. `POST /api/public/v1/research/answer/` generates an answer from accessible indexed evidence and returns validated source citations; inspect the cited records before using an exact quote.

### Sharing with Stakeholders

Reports are designed to be presentation-ready:

* **Executive Summary** for leadership and quick reviews
* **Top Insights** for team meetings and discussions
* **Detailed Analysis** for deep dives and planning sessions

### Using Quotes and Evidence

The report includes verbatim quotes from participants. Use these to:

* Build credibility for your findings
* Illustrate points in presentations
* Create empathy for customer perspectives

### Connecting to Transcripts

If you want to explore a finding more deeply:

1. Note the relevant insight from the report
2. Switch to the **Calls** tab
3. Review the source transcripts for additional context

***

## Report Quality

### Factors Affecting Report Quality

| Factor | Impact |
| - | - |
| **Number of responses** | More responses = more robust patterns |
| **Response quality** | High-quality interviews provide richer insights |
| **Research plan clarity** | Well-defined objectives lead to focused analysis |
| **Topic coverage** | Consistent coverage across interviews strengthens findings |

### How many interviews a report needs

Reports can generate from **2 interviews**, but a report does not make a small sample broadly representative. Sample adequacy depends on the research purpose, how specific and relevant the participants are, interview depth, observed variation, unresolved alternatives, and whether the intended decision requires segment comparison or prevalence estimates. Evidence Coverage makes that boundary explicit and explains when additional interviews would materially help.

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I edit the report?">
    Reports are generated by AI and are read-only. You can copy content to edit externally.
  </Accordion>

  <Accordion title="How often should I regenerate the report?">
    Regenerate when you've collected a meaningful batch of new responses (e.g., 5-10 more interviews). Frequent regeneration with small increments may not show significant changes.
  </Accordion>

  <Accordion title="Can I generate different types of reports?">
    Currently, one standard report format is generated. Custom report formats may be available for enterprise customers—contact support for details.
  </Accordion>

  <Accordion title="Why does my report look thin?">
    Reports require substantive interview data. If your report seems thin, review interview depth and quality, participant relevance and variation, and whether the research plan has clear Learning Goals and evidence requirements. There is no universal recommended interview count.
  </Accordion>

  <Accordion title="Can I export the report?">
    Yes. Use the export options to download the report in various formats for sharing or archiving.
  </Accordion>

  <Accordion title="Will the report update automatically?">
    Not currently. You must manually regenerate reports to include new responses. Automatic updates are on our roadmap.
  </Accordion>
</AccordionGroup>


# Analyze completed study
Source: https://docs.userintuition.ai/skills/analyze-completed-study

Use when the user wants findings, themes, evidence, or a report from completed User Intuition interviews.

Use when the user wants findings, themes, evidence, or a report from completed User Intuition interviews.

[Fetch raw SKILL.md](https://raw.githubusercontent.com/user-intuition/skills/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/analyze-completed-study/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/analyze-completed-study/SKILL.md) · [All skills](/skills/library)

Requires an authenticated [User Intuition MCP connection](/mcp-server/quickstart). Install the raw file as `analyze-completed-study/SKILL.md` inside your agent client's supported skills directory. The raw file is the installable artifact; this page is its documentation wrapper.

SHA-256: `b9b69e4a5b37990b791ac5a5e77ce8cf20c9ec555fdf171663503cb5ff054184`

## Instructions

```markdown theme={null}
---
name: analyze-completed-study
description: Use when the user wants findings, themes, evidence, or a report from completed User Intuition interviews.
---

When the user asks for analysis:

1. Identify the study with `list_studies`; disambiguate similar names. Call `get_study` for full context.
2. Call `list_interviews` with the `study_id` to inspect available evidence. Do not use a universal sample-size threshold as an adequacy rule.
3. Call `get_study_report`. If no report exists or it is stale and the user asked for fresh analysis, call `generate_report`, then fetch the report again.
4. For load-bearing findings, call `get_interview` on the supporting interview IDs and verify evidence in the returned messages. Never invent quotes or attribute a claim to an interview you did not fetch.
5. Summarize findings separately from evidence appraisal: give the concise headline, key metrics, 3–5 themes, within-sample prevalence, impact, verbatims, contradictions, interpretation limits, and decision relevance. Never present an observed sample count as population prevalence.
6. Interpret Evidence Coverage as an appraisal of the evidence behind those findings, not another findings summary. Report the saved sample-adequacy boundary, evidence available per Learning Goal, coverage limitations, decision boundaries, and prioritized gaps. Use the saved sample size for report scope; do not aggregate per-interview explored/answered states into a separate study-level metric. There is no universal minimum-N rule. Present only the report's valid gap-linked recommendations, including a valid empty list; distinguish unavailable assessment from no additional research proposed. Missing analysis does not by itself justify recruitment. The researcher or calling agent decides whether the evidence is adequate for the intended decision.
```


# Create study from brief
Source: https://docs.userintuition.ai/skills/create-study-from-brief

Use when the user wants to create a User Intuition interview study from a brief, goal, problem, or research idea.

Use when the user wants to create a User Intuition interview study from a brief, goal, problem, or research idea.

[Fetch raw SKILL.md](https://raw.githubusercontent.com/user-intuition/skills/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/create-study-from-brief/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/create-study-from-brief/SKILL.md) · [All skills](/skills/library)

Requires an authenticated [User Intuition MCP connection](/mcp-server/quickstart). Install the raw file as `create-study-from-brief/SKILL.md` inside your agent client's supported skills directory. The raw file is the installable artifact; this page is its documentation wrapper.

SHA-256: `e5e938865d0d13fbd3aa90d6f051a771cf639945c6366b1439b14e71d019a66b`

## Instructions

```markdown theme={null}
---
name: create-study-from-brief
description: Use when the user wants to create a User Intuition interview study from a brief, goal, problem, or research idea.
---

When the user asks to create a study:

Apply the shared [approval and workflow continuity policy](../../references/approval-continuity.md).

1. Ask Panel versus BYOP when unstated. Set `recruiting_method` to `panel` when User Intuition should recruit, or `byop` when the user supplies participants. Never guess.
2. Keep the name to 40 characters. Unless the user requests an override, omit `interview_format`, `language`, and `voice` so `create_study` applies the current defaults: a voice interview in English with Elliot. If the user requests another mode or language, read `userintuition://catalog/modes` or `userintuition://catalog/languages` for discovery. The public voice override is `male` (Elliot) or `female` (Clara), including for chat; implementation IDs are not accepted. If the client cannot read MCP resources, use the public API reference for valid settings.
3. Read `userintuition://catalog/study-types` only when the user needs help choosing a type. Do not draft a plan from its metadata; the backend applies the selected type's current Customize Plan instructions.
4. Call `create_study` with ordinary metadata only.
5. Call `customize_study` with the user's natural-language brief, including their audience, screening needs, and requested concept links or images. Do not construct a plan, targeting attributes, screeners, duration, or concept objects in the MCP host.
6. If `response_type` is `question`, relay the question to the user and call `customize_study` again with their answer. Never decide for them.
7. When customization completes, call `get_study`. Return the complete persisted study plan in a readable form together with available audience, screener, concept, and interview settings and `provisioning_status`. New plans contain Learning Goals: answerable questions with evidence requirements underneath. Do not render the derived legacy `key_questions` field as a second list. Intended perspectives remain unverified until compared with actual participant evidence; recruitment configuration is not required to finish the plan. Do not replace the plan with a summary or dashboard link.
8. Ask the user to approve that exact plan version or request revisions. On approval, retain the shared checkpoint. Send revisions through `customize_study`, fetch the study again, and repeat the complete review. If the returned marker changes, invalidate the checkpoint; approval of an earlier version does not cover a revised plan.
9. Verify `provisioning_status` is `provisioned` before fielding. Return the study ID and, when present, both `dashboard_url` and `study_link`; label `study_link` as the live participant interview link, not a preview. Never create BYOP participants or launch a paid Panel without current-plan approval. Panel launch also requires a dry-run and separate approval of its complete estimate.
```


# Curate interview quality
Source: https://docs.userintuition.ai/skills/curate-interview-quality

Use when the user wants to review interview quality or explicitly delete unusable interviews from one User Intuition study.

Use when the user wants to review interview quality or explicitly delete unusable interviews from one User Intuition study.

[Fetch raw SKILL.md](https://raw.githubusercontent.com/user-intuition/skills/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/curate-interview-quality/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/curate-interview-quality/SKILL.md) · [All skills](/skills/library)

Requires an authenticated [User Intuition MCP connection](/mcp-server/quickstart). Install the raw file as `curate-interview-quality/SKILL.md` inside your agent client's supported skills directory. The raw file is the installable artifact; this page is its documentation wrapper.

SHA-256: `59f144bc98e2ce6fa3b6228c70cac46b8781c7cf07d3392a11a4c0a99986abc5`

## Instructions

```markdown theme={null}
---
name: curate-interview-quality
description: Use when the user wants to review interview quality or explicitly delete unusable interviews from one User Intuition study.
---

When the user asks to curate quality:

1. Identify one study and call `list_interviews` with its `study_id`. Use the `quality` filter for Excellent, Good, Fair, or Poor subsets.
2. Fetch each interview under review with `get_interview`. Summarize why it may be low quality using only the returned messages and metadata.
3. Recommend an action, then wait. The current MCP surface does not provide `update_interview`, hide, or quality-override operations.
4. Call `delete_interview` only when the user explicitly confirms the exact interview ID. Never bulk-delete from a quality filter without per-study, clearly scoped confirmation.
5. Re-run `list_interviews` and report the after-state. Explain if the remaining usable sample is too small for reliable analysis.
```


# Design screeners
Source: https://docs.userintuition.ai/skills/design-screeners

Use when the user wants to screen participants, define qualification criteria, or target a Panel study.

Use when the user wants to screen participants, define qualification criteria, or target a Panel study.

[Fetch raw SKILL.md](https://raw.githubusercontent.com/user-intuition/skills/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/design-screeners/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/design-screeners/SKILL.md) · [All skills](/skills/library)

Requires an authenticated [User Intuition MCP connection](/mcp-server/quickstart). Install the raw file as `design-screeners/SKILL.md` inside your agent client's supported skills directory. The raw file is the installable artifact; this page is its documentation wrapper.

SHA-256: `f0c7da2205aadf125cf9f200ab0be6f9fb8c9290e43810404b42d790caeed5c8`

## Instructions

```markdown theme={null}
---
name: design-screeners
description: Use when the user wants to screen participants, define qualification criteria, or target a Panel study.
---

When the user asks to change screening:

Apply the shared [approval and workflow continuity policy](../../references/approval-continuity.md). A screener or targeting change invalidates the affected plan and launch checkpoint.

1. Call `get_study` before writing. If a Panel study is fielding, ask whether to `pause_study` or `stop_study` before editing.
2. Call `customize_study` with the user's audience or screening request in ordinary language. Do not create targeting IDs or screener schemas yourself.
3. Let Customize Plan match standard criteria such as age or household income to canonical targeting attributes. It should use custom screeners only where appropriate.
4. If it returns `response_type: "question"`, relay the question and send the user's answer back through `customize_study`. Never answer on their behalf.
5. Never add recording-consent or willingness-to-participate questions. Do not add screening the user did not request.
6. Call `get_study` and return the complete revised plan in a readable form together with persisted targeting, screeners, concepts, settings, and likely recruitment tradeoffs.
7. Ask the user to approve that exact revised plan version. An approval given before the screening change no longer covers the study.
8. If the study was paused and recruitment should continue, call `resume_study` only after the update is verified and the revised plan is approved.
```


# Field a panel
Source: https://docs.userintuition.ai/skills/field-a-panel

Use when the user wants to estimate, launch, pause, resume, or stop recruitment for a User Intuition Panel study.

Use when the user wants to estimate, launch, pause, resume, or stop recruitment for a User Intuition Panel study.

[Fetch raw SKILL.md](https://raw.githubusercontent.com/user-intuition/skills/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/field-a-panel/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/field-a-panel/SKILL.md) · [All skills](/skills/library)

Requires an authenticated [User Intuition MCP connection](/mcp-server/quickstart). Install the raw file as `field-a-panel/SKILL.md` inside your agent client's supported skills directory. The raw file is the installable artifact; this page is its documentation wrapper.

SHA-256: `14a4d55b542b32b6ec0df4482285d427ca4844ae8fdd9fbf29bbceeae8dd8f70`

## Instructions

```markdown theme={null}
---
name: field-a-panel
description: Use when the user wants to estimate, launch, pause, resume, or stop recruitment for a User Intuition Panel study.
---

When the user wants to field a Panel:

Apply the shared [approval and workflow continuity policy](../../references/approval-continuity.md).

1. Call `get_study` and verify `recruiting_method` is `panel` and `provisioning_status` is `provisioned`.
2. Compare the returned study with any trusted checkpoint. If it matches an already approved plan, carry that approval forward without repeating the review. Otherwise return the complete current `study_plan` with its audience, screeners, concepts, and interview settings, obtain explicit approval, and retain a new checkpoint.
3. Ask the user to choose one launch country explicitly. Never infer a country from language, location, account data, or a broad region. Each launch fields exactly one country; multi-country work requires separately reviewed country-specific studies or launches.
4. Read `userintuition://catalog/panel-countries` to verify that the chosen country supports the study language. If the client cannot read MCP resources, use the authenticated `GET /api/public/v1/panel-countries/` endpoint.
5. If targeting is requested or needs to change, use `customize_study`, complete any questions with the user, then call `get_study`, return the complete revised plan, and obtain approval of the revised version.
6. If `incident_rate` is below 10 or the audience is unusually specialized, use `submit_feasibility_request` instead of direct launch.
7. Call the read-only `estimate_panel` with the explicit `country_code` first. Show the resolved country, language, target, incident rate, estimated cost, and timeline (a heuristic). Retain its `estimate_id`.
8. Add the complete estimate and recruitment settings to the checkpoint, then wait for explicit launch approval. Never infer approval from the original request, plan approval, or client permission settings. If the estimate expires or relevant study, launch, balance, or price inputs change, get a fresh estimate and approval.
9. After approval, call `launch_panel` with the `estimate_id` and the same settings and country. Report what was launched. If the result is uncertain after a timeout, retrieve the current study state before considering another launch.
10. Use `pause_study` to preserve progress and the reward hold, `resume_study` to continue, and `stop_study` to end recruitment and settle or release the hold. Confirm before stopping.
```


# Invite your own participants
Source: https://docs.userintuition.ai/skills/invite-your-own-participants

Use when the user wants to add, invite, update, or reward their own participants in a BYOP study.

Use when the user wants to add, invite, update, or reward their own participants in a BYOP study.

[Fetch raw SKILL.md](https://raw.githubusercontent.com/user-intuition/skills/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/invite-your-own-participants/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/invite-your-own-participants/SKILL.md) · [All skills](/skills/library)

Requires an authenticated [User Intuition MCP connection](/mcp-server/quickstart). Install the raw file as `invite-your-own-participants/SKILL.md` inside your agent client's supported skills directory. The raw file is the installable artifact; this page is its documentation wrapper.

SHA-256: `db5e099170ae9dd4ed31b8bd38c47a02cb4c3551a5b92a1f69edc7528a5fccab`

## Instructions

```markdown theme={null}
---
name: invite-your-own-participants
description: Use when the user wants to add, invite, update, or reward their own participants in a BYOP study.
---

When the user supplies participants:

Apply the shared [approval and workflow continuity policy](../../references/approval-continuity.md).

1. Call `get_study` and verify `recruiting_method` is `byop` and `provisioning_status` is `provisioned`.
2. Compare the study with any trusted checkpoint. If it matches an already approved plan, carry that approval forward. Otherwise return the complete current persisted study plan with its audience, screeners, concepts, and interview settings, obtain explicit approval of that exact version, and retain a new checkpoint. Approval to create or customize the study does not count.
3. Normalize and deduplicate email addresses case-insensitively. `create_participants` accepts 1–100 participants per request.
4. Explain that invitations send by default. Use `silent: true` for each participant when the user wants records created without sending email.
5. Call `create_participants` with `study_id` and the batch only after provisioning and exact-version plan approval are confirmed.
6. Use `list_participants` to verify the batch. Call `get_participant` before `update_participant`.
7. `send_participant_reward` has a financial side effect and is BYOP-only. Confirm the exact participant and require an explicit request before sending. The backend prevents a duplicate reward for an already-paid participant.
8. Participant deletion is not available through the public MCP surface. Do not promise to delete a participant.
```


# Skills Library
Source: https://docs.userintuition.ai/skills/library

Choose a research workflow and fetch its individual, installable skill file.

The [canonical skills repository](https://github.com/user-intuition/skills) supplies these ten workflows. Select a skill from its description, then fetch only that skill. Each page links to a raw, version-pinned `SKILL.md` with a SHA-256 digest.

[Machine-readable catalog](https://raw.githubusercontent.com/user-intuition/skills/main/catalog.json) · [Connection and installation](/skills/overview)

| Skill | When to use | Primary tools |
| - | - | - |
| [analyze-completed-study](/skills/analyze-completed-study) | Use when the user wants findings, themes, evidence, or a report from completed User Intuition interviews. | `generate_report`, `get_study_report`, `get_interview` |
| [create-study-from-brief](/skills/create-study-from-brief) | Use when the user wants to create a User Intuition interview study from a brief, goal, problem, or research idea. | `create_study`, `customize_study`, `get_study` |
| [curate-interview-quality](/skills/curate-interview-quality) | Use when the user wants to review interview quality or explicitly delete unusable interviews from one User Intuition study. | `list_interviews`, `get_interview`, `delete_interview` |
| [design-screeners](/skills/design-screeners) | Use when the user wants to screen participants, define qualification criteria, or target a Panel study. | `customize_study`, `get_study` |
| [field-a-panel](/skills/field-a-panel) | Use when the user wants to estimate, launch, pause, resume, or stop recruitment for a User Intuition Panel study. | `get_study`, `launch_panel`, `submit_feasibility_request`, `pause_study`, `resume_study`, `stop_study` |
| [invite-your-own-participants](/skills/invite-your-own-participants) | Use when the user wants to add, invite, update, or reward their own participants in a BYOP study. | `get_study`, `create_participants`, `list_participants`, `get_participant`, `update_participant`, `send_participant_reward` |
| [monitor-fielding](/skills/monitor-fielding) | Use when the user wants a read-only status snapshot of User Intuition studies or interviews. | `list_studies`, `list_interviews` |
| [retrieve-study-results](/skills/retrieve-study-results) | Use when the user wants to fetch an existing User Intuition study report, inspect its evidence coverage, or follow a finding or participant response to supporting interview evidence without regenerating analysis. | `list_studies`, `get_study`, `get_study_report`, `get_interview` |
| [run-a-concept-test](/skills/run-a-concept-test) | Use when the user wants participants to react to a concept, prototype, design, or landing page during a User Intuition interview. | `create_study`, `customize_study`, `get_study` |
| [search-research](/skills/search-research) | Use when the user wants to find existing User Intuition findings or participant responses across authorized studies before deciding whether more qualitative research is needed. | `search_research`, `answer_research`, `get_study_report`, `get_interview` |

## Compatibility

Skills require the connected server's current tool schemas. The retrieval and search workflows describe B2/C1 evidence handling; their linked example adapters still need release-contract verification. Do not infer live API compatibility from fixture output.


# Monitor fielding
Source: https://docs.userintuition.ai/skills/monitor-fielding

Use when the user wants a read-only status snapshot of User Intuition studies or interviews.

Use when the user wants a read-only status snapshot of User Intuition studies or interviews.

[Fetch raw SKILL.md](https://raw.githubusercontent.com/user-intuition/skills/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/monitor-fielding/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/monitor-fielding/SKILL.md) · [All skills](/skills/library)

Requires an authenticated [User Intuition MCP connection](/mcp-server/quickstart). Install the raw file as `monitor-fielding/SKILL.md` inside your agent client's supported skills directory. The raw file is the installable artifact; this page is its documentation wrapper.

SHA-256: `b1ebc1a67fede393d63abf87bdd9600e10883895dee6d346ea92008dae32be18`

## Instructions

```markdown theme={null}
---
name: monitor-fielding
description: Use when the user wants a read-only status snapshot of User Intuition studies or interviews.
---

When the user asks for fielding status:

1. Record the snapshot time. Call `list_studies`, paginating when necessary. Use response totals rather than counting only the current page.
2. For each study in scope, call `list_interviews` with its `study_id`. Use `status` and `quality` filters when the user asks for a breakdown.
3. Present a compact table with study name, recruiting method, `fielding_status`, interview count, quality distribution, and the snapshot time. Keep `provisioning_status` separate: provisioned means interviews can run, not that recruitment started.
4. For BYOP, report `fielding_status: unavailable` as such and use participant/interview facts instead of inventing a study-level recruitment state. Flag no completions or a high Fair/Poor share as observations, not diagnoses. Zero completions alone is not proof that recruitment is stalled.
5. Keep the workflow read-only. Offer `pause_study`, `resume_study`, `stop_study`, or report generation as follow-ups, but do not mutate unless the user explicitly asks.
```


# User Intuition Skills
Source: https://docs.userintuition.ai/skills/overview

Pre-built agent workflows for using the User Intuition MCP server safely and consistently — drop in, no glue code required.

User Intuition **skills** are short, copy-pasteable instruction files that teach a compatible AI agent *how* to drive the [MCP server](/mcp-server/overview) for a specific research workflow. Connect the hosted OAuth endpoint first when the client supports it; local stdio remains available for clients that need a local process.

Where the MCP server gives an agent the *tools*, a skill gives it the *play*. The skill is the difference between "the agent can call `create_study`" and "the agent knows to ask whether you want Panel or BYOP recruitment, conduct the `customize_study` conversation, verify the saved study, and dry-run panel cost before requesting launch approval."

## When skills help

* **Repeatable workflows.** Creating a study from a brief, screening panel respondents, generating an insights report — anything you do more than twice.
* **Cross-team consistency.** Two PMs on different machines run the same workflow the same way because the skill ships the playbook.
* **Onboarding.** A new teammate installs the skills and immediately runs the team's standard research patterns.

## How skills work

A skill is a Markdown file with YAML frontmatter. The frontmatter tells the agent *when* the skill applies; the body tells it *how* to execute. Example shape:

```markdown theme={null}
---
name: field-a-panel
description: Use when the user wants to recruit respondents from the User Intuition panel for an existing Panel study.
---

When the user wants to field a panel:

1. Verify the study is a provisioned Panel study via `get_study`.
2. Return the complete persisted plan and obtain approval of that exact version.
3. Ask the user to choose one launch country; never infer it.
4. Call `estimate_panel` and show the resolved country, language, cost, and timeline.
5. Wait for explicit approval of the estimate, then launch with its `estimate_id` using the same country.
```

Agents that support skills load the frontmatter at session start, then read the body when the description matches the user's request.

## Installing skills

<Tabs>
  <Tab title="Claude Code (plugin marketplace)">
    One command installs all ten skills, with updates delivered on marketplace refresh:

    ```
    /plugin marketplace add user-intuition/skills
    /plugin install user-intuition-research@user-intuition
    ```

    Source: [github.com/user-intuition/skills](https://github.com/user-intuition/skills).
  </Tab>

  <Tab title="Agent-native">
    The [skills library](/skills/library) is a compact index. Each workflow has a separate documentation page and a raw, installable skill file. Tell your agent:

    > Fetch `https://raw.githubusercontent.com/user-intuition/skills/main/catalog.json`, select the skill matching this task, and fetch its raw `SKILL.md`. Install it in the skills directory supported by this agent client.

    Load only the selected workflow. A docs `.md` export includes explanatory page content; use its raw-file link when installing a skill.
  </Tab>

  <Tab title="Claude Code (single skill)">
    Claude Code discovers skills as one directory per skill with a `SKILL.md` entrypoint — a flat `.claude/skills/<name>.md` file is not discovered. Fetch the raw skill linked from its page in the [library](/skills/library) into `.claude/skills/<name>/SKILL.md` (project-local) or `~/.claude/skills/<name>/SKILL.md` (global):

    ```bash theme={null}
    mkdir -p ~/.claude/skills/field-a-panel
    # paste the skill into ~/.claude/skills/field-a-panel/SKILL.md
    ```

    Claude Code auto-discovers skills on next session start.
  </Tab>

  <Tab title="Cursor">
    Cursor Project Rules live in `.cursor/rules/<name>.mdc` (the `.mdc` extension matters). Translate the skill's frontmatter into rule metadata rather than dropping it — carry the skill's `description` over, and set `alwaysApply: false` so Cursor applies the rule only when the description matches the task:

    ```markdown theme={null}
    ---
    description: Use when the user wants to recruit respondents from the User Intuition panel for an existing Panel study.
    alwaysApply: false
    ---

    <paste the skill body here>
    ```

    ```bash theme={null}
    mkdir -p .cursor/rules
    # save as .cursor/rules/field-a-panel.mdc
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop doesn't natively support skill files yet — paste the body of the skill into a custom **Project** instructions field. The agent will follow it for the duration of that project's chats.
  </Tab>
</Tabs>

## What's in the library

The [skills library](/skills/library) covers the research loop. Existing workflows retain their MCP instructions; retrieval and search discover the released schemas, and illustrative B2/C1 adapters still need release verification:

<CardGroup>
  <Card title="create-study-from-brief" href="/skills/create-study-from-brief">
    Turn a research brief into a launch-ready interview study.
  </Card>

  <Card title="design-screeners" href="/skills/design-screeners">
    Recruit exactly the right respondents — panel and custom screeners, done safely.
  </Card>

  <Card title="field-a-panel" href="/skills/field-a-panel">
    Recruit N respondents from the panel, with cost approved before any spend.
  </Card>

  <Card title="invite-your-own-participants" href="/skills/invite-your-own-participants">
    Interview your own customers — invites, share links, and rewards (BYOP).
  </Card>

  <Card title="run-a-concept-test" href="/skills/run-a-concept-test">
    Put a concept, prototype, or landing page in front of participants.
  </Card>

  <Card title="monitor-fielding" href="/skills/monitor-fielding">
    Daily digest of every fielding study — progress, quality, stalls.
  </Card>

  <Card title="analyze-completed-study" href="/skills/analyze-completed-study">
    From transcripts to stakeholder-ready findings, with real quotes only.
  </Card>

  <Card title="curate-interview-quality" href="/skills/curate-interview-quality">
    Review low-quality interviews and delete only the exact interviews the user confirms.
  </Card>
</CardGroup>

## Retrieve and search existing evidence

* [Retrieve study results](/skills/retrieve-study-results): choose the report view needed and follow source references without regenerating analysis.
* [Search research](/skills/search-research): find prior findings and participant responses, inspect coverage, and retrieve sources before citing them.

## Skill vs MCP vs CLI — which goes where

| You want… | Use |
| - | - |
| An agent to *autonomously* run a research workflow from a vague prompt | **Skill** (built on MCP) |
| An agent to call User Intuition tools when you ask, with you in the loop | **MCP** alone |
| To run a tool from a shell script, CI job, or cron | **CLI** |
| To call User Intuition from your own backend code | **REST API** |

Skills sit on top of MCP, while the MCP study-design workflow intentionally routes through the same Customize Plan backend used by the dashboard. The CLI and raw REST API are separate integration surfaces and may expose lower-level fields that MCP does not. Pick the highest level that gets the job done.

## Next steps

<CardGroup>
  <Card title="Skills library" icon="book" href="/skills/library">
    Browse and copy ready-to-use skills.
  </Card>

  <Card title="MCP quickstart" icon="rocket" href="/mcp-server/quickstart">
    Skills require an MCP-connected client. Wire one up first.
  </Card>
</CardGroup>


# Retrieve study results
Source: https://docs.userintuition.ai/skills/retrieve-study-results

Use when the user wants to fetch an existing User Intuition study report, inspect its evidence coverage, or follow a finding or participant response to supporting interview evidence without regenerating analysis.

Use when the user wants to fetch an existing User Intuition study report, inspect its evidence coverage, or follow a finding or participant response to supporting interview evidence without regenerating analysis.

[Fetch raw SKILL.md](https://raw.githubusercontent.com/user-intuition/skills/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/retrieve-study-results/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/retrieve-study-results/SKILL.md) · [All skills](/skills/library)

Requires an authenticated [User Intuition MCP connection](/mcp-server/quickstart). Install the raw file as `retrieve-study-results/SKILL.md` inside your agent client's supported skills directory. The raw file is the installable artifact; this page is its documentation wrapper.

SHA-256: `8de41803e188312bc99e5cc804276eb3d809c02c217e207d826960d4b45a7ece`

## Instructions

```markdown theme={null}
---
name: retrieve-study-results
description: Use when the user wants to fetch an existing User Intuition study report, inspect its evidence coverage, or follow a finding or participant response to supporting interview evidence without regenerating analysis.
---

1. Use the supplied study ID. If only a name is supplied, resolve it with `list_studies` and disambiguate matches. Fetch `get_study` for audience and study context when needed.
2. Discover the current schema for `get_study_report`. Its default `view="overview"` is intentionally small; use `view="full"` or one of `study_findings`, `participant_profiles`, `participant_responses`, `evidence_coverage`, `recommended_next_steps`, or `references` when the task needs that section. Read `included_sections` before treating an absent section as empty. This is a read workflow: do not call `generate_report`, create a study, invite participants, or launch recruitment merely to fulfill retrieval.
3. Inspect the relevant Study Findings, Evidence Coverage, Participant Responses, Participant Profiles, Recommended Next Steps, and References sections. Learning Goals are answerable research questions with evidence requirements; legacy `key_questions` fields may carry their per-interview analysis. Preserve assessment status and whether requirements were specified before collection, revised, inferred, or of unknown timing. Profiles describe the actual sample rather than proving audience alignment.
4. Preserve study ID, report version or generation time, coverage, freshness, and source references when provided. Missing freshness is unknown, not fresh. Report-eligible interviews, completed interviews, and the target sample are different counts.
5. Resolve each reference using the returned reference map and identifiers. Keep respondent labels scoped to the study/report. Do not assume a response label is a participant ID or a reference ID is an interview ID. Follow interview references with `get_interview`; retain message or passage identifiers if present.
6. Before presenting an exact quotation or treating a finding as verified, inspect the original supporting passage. Do not invent finer citation precision than the response provides. Distinguish multiple quotes from one interview from independent participants.
7. Return supported conclusions, material limits, and their implications for the research purpose. Use the report's saved sample size and evidence assessment rather than recomputing study-level coverage from today's interviews. Missing per-interview analysis is an operational limitation. Trace recommendations through `gap_ids` to this report's `evidence_gaps`; a valid empty list is authoritative and differs from unavailable recommendations. Do not invent additional research or infer a need to recruit from small sample size alone. If new analysis is needed, explain that it is a separate operation and follow the user's scope.

The calling agent interprets the evidence in its wider context. The illustrative [results example](https://github.com/user-intuition/examples/tree/main/examples/retrieve-study-results) shows the intended B2 shape; verify it against the released schema before live use. [API reference](https://docs.userintuition.ai/api-reference/introduction).
```


# Run a concept test
Source: https://docs.userintuition.ai/skills/run-a-concept-test

Use when the user wants participants to react to a concept, prototype, design, or landing page during a User Intuition interview.

Use when the user wants participants to react to a concept, prototype, design, or landing page during a User Intuition interview.

[Fetch raw SKILL.md](https://raw.githubusercontent.com/user-intuition/skills/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/run-a-concept-test/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/run-a-concept-test/SKILL.md) · [All skills](/skills/library)

Requires an authenticated [User Intuition MCP connection](/mcp-server/quickstart). Install the raw file as `run-a-concept-test/SKILL.md` inside your agent client's supported skills directory. The raw file is the installable artifact; this page is its documentation wrapper.

SHA-256: `72703a5ce423350d2ccefb3bc8ea2e6ab3831f3cea5f294a148283e4b08922d2`

## Instructions

```markdown theme={null}
---
name: run-a-concept-test
description: Use when the user wants participants to react to a concept, prototype, design, or landing page during a User Intuition interview.
---

When the user wants a concept test:

Apply the shared [approval and workflow continuity policy](../../references/approval-continuity.md). A concept asset or plan change invalidates the affected checkpoint.

1. Follow the create-study-from-brief workflow and choose the correct metadata type. Use `study_type: "concept-test"` for a participant-facing concept image or non-interactive concept. Use `study_type: "prototype-test"` for a clickable prototype, staging site, live page, or web flow.
2. A concept image can use chat, voice, or video. A concept link cannot use chat: relay the backend's question and let the user choose voice or video rather than choosing for them. A prototype test also cannot use chat; use the default voice format or an explicitly requested video format.
3. Call `customize_study` with the user's goal and requested link or image. For a prototype include its URL, participant-facing label, intended tasks, audience, and learning goals. Let the backend structure the flow, check the asset, and reconcile it with the plan.
4. For an image whose bytes or readable local path are available, base64-encode the raw file and pass `concept_image` with its filename, MIME type, and the user's participant-facing label. Otherwise, a public downloadable URL and stable label can be sent in the message. If the client exposes only an opaque attachment reference, explain that client limitation and offer the available upload routes.
5. Relay every `response_type: "question"` to the user, including mode or asset confirmations, and send their answer back unchanged.
6. Call `get_study`, return the complete persisted plan and concept configuration, and obtain approval of that exact version. Never request credentials or promise that a login-protected URL can be used.
7. Field through the Panel or BYOP Skill only after provisioning and current-plan approval. Dry-run Panel cost and require separate confirmation before launch.
```


# Search research
Source: https://docs.userintuition.ai/skills/search-research

Use when the user wants to find existing User Intuition findings or participant responses across authorized studies before deciding whether more qualitative research is needed.

Use when the user wants to find existing User Intuition findings or participant responses across authorized studies before deciding whether more qualitative research is needed.

[Fetch raw SKILL.md](https://raw.githubusercontent.com/user-intuition/skills/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/search-research/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/2a18ba4a8f54b0ac3de2ec8a92602ec03043d699/plugins/user-intuition-research/skills/search-research/SKILL.md) · [All skills](/skills/library)

Requires an authenticated [User Intuition MCP connection](/mcp-server/quickstart). Install the raw file as `search-research/SKILL.md` inside your agent client's supported skills directory. The raw file is the installable artifact; this page is its documentation wrapper.

SHA-256: `3addb2419b316ade2e689f0bb62cbb14967d241fed130bae5c3160567216176e`

## Instructions

```markdown theme={null}
---
name: search-research
description: Use when the user wants to find existing User Intuition findings or participant responses across authorized studies before deciding whether more qualitative research is needed.
---

1. Turn the user's information need into a query and identify at least one authorized `study_id`. Preserve any supplied date or content-type constraints; do not add filters without a reason grounded in the request.
2. Call `search_research` with `filters.study_ids` and, when useful, `content_types`, `research_date_from`, or `research_date_to`. Supported content types are `study_plan`, `study_finding`, `participant_profile`, `participant_response`, and `recommended_next_step`. Use a limit from 1–50. Follow `next_cursor` with the same query, filters, and limit until it is null when the task needs broader coverage. A final page can be empty.
3. When the user asks a question across studies, call `answer_research` with the question and the same authorized study IDs. Its prose is generated from bounded indexed evidence; inspect every numbered citation's `study_id`, `content_id`, `content_type`, and `report_id` before presenting the answer. If `insufficient_evidence` is true, say so. Do not treat a cited summary as a verbatim participant quote.
4. Treat `search_research` as retrieval, not generation. Search ranks candidate content, but every returned `content` object is canonical JSON from the Study or Report API and `generated_content_returned` is always `false`. Never present ranking or a generated answer as statistical confidence or population prevalence.
5. Inspect every entry in `studies`. Check its `index_status`, `latest_report_id`, `indexed_report_id`, and grouped `results` for search, or its status fields for answers. A `not_indexed` study is different from a `ready` study with no matching results; an `updating` study may still return matches from `indexed_report_id`. Do not generate or regenerate a report unless the user separately asks for fresh analysis.
6. Interpret each search result using its parent `study_id` plus its `report_id`, `report_generated_at`, `content_type`, and `content_id`. Study findings and participant profiles match report-section objects; participant responses include a public `interview_id` to use with `get_interview`; study plans match `get_study.study_plan`.
7. Resolve a finding's `reference_ids` through `get_study_report.references` and fetch the supporting interview when the user needs source context or a verbatim quote. A summary is not a verbatim quote, and repeated matches from one interview are not independent participants.
8. Return the relevant evidence grouped by study, including source identifiers, index coverage, contradictions, and remaining uncertainty. An empty result set does not prove the topic was absent from every interview. Keep recommended next steps labeled as proposals and include them only when relevant.

Do not create studies, regenerate reports, invite people, or incur recruitment costs as a side effect of searching. The calling agent decides whether the evidence answers the question and whether a separate research task is needed.

[API reference](https://docs.userintuition.ai/api-reference/introduction).
```


# Concept Test
Source: https://docs.userintuition.ai/study-types/concept-test

Show participants an image or video and capture their reaction, with the moderator probing on what they say.

A concept test puts something in front of participants and captures what they make of it. Instead of asking someone to imagine a feature, you show them the mockup, the ad, or the pricing page, and the moderator probes on the reaction in their own words.

***

## When to use concept testing

Use a concept test when you want someone's **reaction** to something — not a record of how they used it.

That's the line between this and a [prototype test](/study-types/prototype-test). If the question is "what do people make of this?", it's a concept test. If it's "where do people get stuck?", you want a prototype test, which captures their clicks and interactions as they work through it.

<CardGroup>
  <Card title="Visual designs">
    Compare two homepage mockups, validate a new icon set, or get reactions to a redesigned dashboard before you build it.
  </Card>

  <Card title="Feature concepts">
    Show wireframes or annotated screens of a feature you're considering and learn whether participants understand the value.
  </Card>

  <Card title="Marketing copy">
    Test headlines, value propositions, or ad creative to find which framing resonates.
  </Card>

  <Card title="Packaging and pricing">
    Get unprompted reactions to packaging, a pricing page, or a plan comparison before it goes live.
  </Card>
</CardGroup>

<Note>
  When you create a study with the **Concept Test** type, the interview is configured to display images and links inline, and the moderator is briefed to show each concept at the right moment in the conversation.
</Note>

***

## What you can attach

Each Concept Test study supports two kinds of assets:

| Asset type | Use for | Example |
| - | - | - |
| **Concept image** | Static visuals you want the participant to look at | Homepage mockup, ad creative, screenshot |
| **Concept link** | A page or video the participant should open and react to | Draft landing page, demo video, hosted mockup |

You can attach as many of each as you need. Every asset has a **label** the moderator uses to refer to it during the conversation, so labels should describe what the participant is about to see.

***

## Attaching images

<Steps>
  <Step title="Open the customize step">
    From the study creation flow, navigate to the **Customize** step. If your study uses the Concept Test template, you'll see an image upload area.
  </Step>

  <Step title="Upload an image">
    Drag a file into the upload area or click to browse. Supported formats are **PNG**, **JPEG**, **GIF**, and **WebP**.
  </Step>

  <Step title="Give it a label">
    Enter a short, descriptive label such as `Homepage v2` or `Pricing page — control`. The moderator uses this label when introducing the image to the participant.
  </Step>

  <Step title="Repeat for additional images">
    Add as many concept images as your study needs. Each upload appends to the list — your previous images stay in place.
  </Step>
</Steps>

<Warning>
  Labels must be unique within a study. Uploading a new image with a label that already exists **replaces** the existing image (case-insensitive match). If you want to keep both, use distinct labels like `Homepage A` and `Homepage B`.
</Warning>

### Removing an image

Click the delete control next to any uploaded image to remove it from the study. The image is deleted from storage and the moderator will no longer reference it.

***

## Attaching shareable links

Use concept links when what you want a reaction to lives on a page rather than in an image — a draft landing page, a demo video, a hosted mockup.

<Note>
  If you want to watch someone **work through** something rather than react to it, use a [prototype test](/study-types/prototype-test) instead. That study type captures their clicks and interactions and gives you a replay; a concept test captures the conversation and what was on screen.
</Note>

<Steps>
  <Step title="Add a link">
    In the customize step, find the **Concept links** section and click to add a new link.
  </Step>

  <Step title="Enter the URL">
    Paste the full URL — a draft page, a hosted mockup, or a video.
  </Step>

  <Step title="Label it">
    Give the link a clear label such as `Pricing page — variant B` or `Launch video`. As with images, labels are unique per study and a duplicate label replaces the existing entry.
  </Step>
</Steps>

<Note>
  Make sure any link you attach is reachable by the participants you're inviting. Anything behind a login needs credentials you've given them, and anything with view permissions set needs those opened to anyone with the link.
</Note>

***

## How participants experience concepts

The moderator decides when to surface each concept based on how the conversation is going. Two things happen on the participant's side:

* **Images** appear inline as soon as the moderator chooses to show them. The participant can refer back to the image as they answer follow-ups.
* **Links** are presented through a banner prompting the participant to open the page, or to share their screen so the moderator can guide them through it. Once it's open, the conversation continues around what they're looking at.

Concept tests always capture the screen alongside the conversation, so you can see what the participant was looking at when they said what they said.

**Whether you also see their face depends on the [interview format](/getting-started/interview-modes) you chose.** A concept test in voice format records audio and screen without ever asking for the camera. Choose video format if the participant's expression is part of what you're testing.

<Note>
  Participants don't need to do anything special to reach a concept — the moderator introduces each one at the right point in the conversation and points them to it.
</Note>

***

## Setting concepts up well

A few things about how the moderator handles concepts, which shape how you should prepare them:

<CardGroup>
  <Card title="Label them for the moderator">
    The moderator reads your labels aloud and uses them to decide what to show next. `Pricing page — variant B` works; `image2` doesn't.
  </Card>

  <Card title="Order matters">
    Concepts are generally shown in the order you upload them. Put the most important one first so it gets the most attention in a short session.
  </Card>

  <Card title="Three to five is plenty">
    More than that fragments the conversation and cuts the time spent on each one.
  </Card>

  <Card title="Keep links light">
    A single page or a short video works well. If it takes thirty clicks to get through, it belongs in a prototype test.
  </Card>
</CardGroup>

Two things worth building into the plan itself: ask for **first impressions before context**, so you capture an unprompted reaction before explaining what the thing is; and if you're testing variants, attach both and have the moderator ask participants to **compare them directly** rather than rating each in isolation.

***

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does the participant need a special browser or app?">
    No. Images render inside the interview surface, and links open in a new tab in whatever browser the participant is already using.
  </Accordion>

  <Accordion title="Can I update a concept after launching the study?">
    Yes. Uploading an image or link with the same label replaces the existing entry, so you can swap a concept mid-study without recreating the assistant. Bear in mind that interviews already completed will still reflect the version of the concept that was live at that time.
  </Accordion>

  <Accordion title="Are concept reactions captured in the report?">
    Yes. The transcript records what the participant said about each concept, and the recording captures their on-screen reactions. The study report and Intelligence Hub treat that material like any other interview content.
  </Accordion>

  <Accordion title="What if a participant can't see the image or open the link?">
    The interviewer is prompted to confirm the participant can see each concept before asking detailed questions. If the participant reports a problem, encourage them to refresh or reopen the link, and keep the interview going with verbal description as a fallback.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Test your conversation" icon="message" href="/creating-a-study/test-conversation">
    Run a dry-run interview to confirm each concept appears as expected.
  </Card>

  <Card title="Set up the interviewer" icon="microphone" href="/creating-a-study/setup-interview">
    Choose the interviewer voice and mode for your concept test.
  </Card>
</CardGroup>


# In-depth Interview
Source: https://docs.userintuition.ai/study-types/in-depth-interview

A focused conversation about what someone did, why they did it, and what they would change. No stimulus required.

An in-depth interview is a conversation and nothing else — no images, no links, no prototype. The moderator works through what someone did, why they did it, and what they'd change, following up on whatever turns out to be interesting.

It's the default study type, and the right one when you're still working out what the question is.

***

## When to use it

* **Discovery** — you're exploring a space and don't yet know what matters
* **Decision moments** — how someone chose between options, what happened after a bad experience, why they left
* **Before committing to a direction** — pressure-test the assumption before you spend six months on it
* **Unmet needs** — the frustrations people have stopped complaining about because they assume nothing can be done

If you have something specific to show people, you want a [Concept Test](/study-types/concept-test). If you have something for them to use, a [Prototype Test](/study-types/prototype-test).

***

## What a session looks like

The moderator opens on something concrete — a recent experience, a specific decision — and works outward from there. Rather than accepting the first answer, it follows up: what did you do next, what were you expecting, what would have changed your mind.

That laddering is where the value is. "The pricing was too high" is a data point. Three follow-ups later you find out they'd have paid double if the onboarding hadn't looked like a three-week project, which is a different problem entirely.

The moderator follows your research plan while adapting to each conversation, so every participant covers the same ground without every interview sounding identical.

***

## Setting one up

Nothing to attach. Tell Charles in [Step 2](/creating-a-study/customize-plan) who you want to talk to, what prompted the research, and what you'd do differently depending on the answer. He'll draft answerable Learning Goals with evidence requirements and a conversation flow.

The single highest-leverage thing you can tell him is **what decision this research feeds**. A study designed to inform a specific decision asks sharper questions than one designed to "understand our customers."

<Tip>
  Share your hypotheses even when you're unsure of them. Charles can design questions that would disconfirm a belief — which is far more useful than questions that confirm it.
</Tip>

***

## Getting the most out of it

**Go narrow.** Four to six topics explored properly beats twelve skimmed. Interviews have a natural length, and every topic you add takes time from the others.

**Ask about what happened, not what people would do.** "Walk me through the last time you renewed" gets you behaviour. "Would you renew if we added X?" gets you a guess, and people are poor at predicting themselves.

**Let the unexpected run.** The most valuable moments are usually the ones nobody planned. The moderator will follow them, and your plan is a guide rather than a script.

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I show an image in an in-depth interview?">
    Yes. In-depth interviews accept concept images too, so a conversation can turn into a concept test partway through if that's where it goes.
  </Accordion>

  <Accordion title="How long do interviews run?">
    It depends on your plan's scope — most land between 10 and 25 minutes. Charles includes time estimates per section so you can see the shape before you launch.
  </Accordion>

  <Accordion title="Which interview format should I use?">
    Voice, in most cases. Spoken answers run longer and reveal more than typed ones, and it costs half what video does. See [Interview modes](/getting-started/interview-modes).
  </Accordion>

  <Accordion title="How many interviews do I need?">
    It depends on how common the thing you're looking for is. Twelve to twenty covers most discovery work, but if you're hunting something that affects 1 in 10 participants you'll want closer to 30. Work out your number with the [sample size calculator](/resources/sample-size).
  </Accordion>
</AccordionGroup>


# Study Types
Source: https://docs.userintuition.ai/study-types/overview

User Intuition offers three study types — in-depth interviews, concept tests, and prototype tests. How to pick the right one.

There are three study types. All three follow the same setup process and cost the same; what differs is whether participants react to something, and what.

***

## Picking one

The quickest way to decide is to ask what you have in your hands right now.

| You have… | Use | What participants do |
| - | - | - |
| **A question** | [In-depth Interview](/study-types/in-depth-interview) | Talk through what they did and why |
| **Something to show** — an image or video | [Concept Test](/study-types/concept-test) | React to it, and explain the reaction |
| **Something to use** — a prototype or live site | [Prototype Test](/study-types/prototype-test) | Work through it while narrating |

If you're between two, pick the simpler one. You can change study type at any point during setup, and an in-depth interview will accept a concept image later if the conversation calls for it.

***

## The three

<CardGroup>
  <Card title="In-depth Interview" icon="comments" href="/study-types/in-depth-interview">
    A conversation, no stimulus. Discovery, decision moments, unmet needs.
  </Card>

  <Card title="Concept Test" icon="image" href="/study-types/concept-test">
    Reactions to an image or video. Creative, messaging, packaging.
  </Card>

  <Card title="Prototype Test" icon="cursor-click" href="/study-types/prototype-test">
    Watching people use something. Flows, usability, old versus new.
  </Card>
</CardGroup>

***

## What's the same across all three

* **Setup** — the same six steps, whichever you choose
* **Cost** — driven by [interview format](/getting-started/interview-modes), not study type. Chat 0.5 credits, voice 1, video 2
* **Recruiting** — bring your own participants or use the research panel, either way
* **Results** — the same transcripts, per-call summaries, reports, and Intelligence Hub

The study type shapes the conversation. It doesn't change what the platform does around it.

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I change study type after I've started?">
    Yes, at any point during setup — click **Back** to Step 1. After launch, changing it means earlier and later responses aren't directly comparable, so duplicate the study instead.
  </Accordion>

  <Accordion title="Can one study do two of these?">
    Partly. In-depth interviews accept concept images, so a conversation can become a concept test mid-flow. For anything more deliberate, run two studies — you'll get cleaner analysis from each.
  </Accordion>

  <Accordion title="Do they cost different amounts?">
    No. Cost comes from the interview format and how many interviews you run.
  </Accordion>
</AccordionGroup>


# Prototype Test
Source: https://docs.userintuition.ai/study-types/prototype-test

Watch people work through your prototype or live site while they narrate their thinking, with clicks and interactions captured for replay.

In a prototype test, the participant works through your prototype or live site while narrating their thinking, and the moderator probes on what they do — where they hesitate, what they expected, what they went looking for and couldn't find.

You get the conversation *and* a record of what they actually did, which is usually the more honest of the two.

***

## When to use it

* Validating a flow before you build it
* Finding where people get stuck in an existing experience
* Comparing an old design against a new one
* A pre-launch usability check on a live page

If you want reactions to something static — an ad, a mockup, packaging — you want a [Concept Test](/study-types/concept-test) instead. Prototype tests are for things people *use*.

***

## Adding your prototype

Attach the link in [Step 2](/creating-a-study/customize-plan) by telling Charles about it. A Figma prototype, a clickable mockup, a staging environment, or a live production page all work.

Charles builds the conversation around it — where to start participants, what to ask them to attempt, and where to probe rather than rescue.

<Tip>
  Give participants a task, not a tour. "Find a jacket for a trip to Iceland and get it into your basket" tells you far more than "have a look around and tell me what you think."
</Tip>

***

## How sessions are captured

There are two capture paths, and which one you get depends on your prototype.

### With the recording snippet — clicks captured directly

If you install our recording snippet on the site, every click and interaction is captured directly, **with no screen share involved**. Participants just use the page.

This path gives you two things the screen-share path can't:

* **A clean replay** of exactly what the participant did, watchable from the Calls tab afterwards
* **A live activity digest for the moderator** — during the call it can privately check what's happening on the page and ask about it in the moment: *"you've been on the pricing step a while — what are you weighing up?"* The participant never hears this checked; it appears in your transcript afterwards as its own labelled row so you can see what the moderator was reacting to.

### With screen share — the fallback

Without the snippet, participants share their screen and the session is captured that way. You still get the recording and the conversation; you don't get the clean interaction replay or the live activity digest.

**Figma prototypes always use screen share.** Figma runs its own embedded runtime, so there's no page of yours to install the snippet on. This isn't a limitation you can configure around — if you want the richer capture, test a hosted build rather than a Figma link.

***

## Installing the recording snippet

You don't have to hunt for this. When you add a link, Charles checks whether the snippet is already there — and if it isn't, he hands you the snippet to paste into the `<head>` of the pages participants will visit.

Once your team has deployed it, say **"done"** in the chat and Charles re-checks. If it's live, the study switches to the direct-capture path automatically.

<Note>
  The snippet only needs to go on the pages participants will actually reach during the study, and it only records during an active interview session.
</Note>

***

## Reviewing the results

Open the **Calls** tab and expand any interview.

Alongside the usual [transcript, responses, and summary](/results/calls-and-transcripts), sessions captured with the snippet have a **Replay** you can open and watch — the participant's actual path through your prototype, in order.

Where the moderator checked on-site activity mid-call, you'll see that in the transcript as its own row showing what it saw at that moment. That's often the fastest way to find the interesting parts: jump to where the moderator started asking about hesitation.

<Note>
  If a session didn't close cleanly — the participant closed the tab mid-flow, say — the replay is flagged as possibly incomplete. The conversation and transcript are unaffected.
</Note>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Does this work on a site behind a login?">
    Yes, as long as your participants can get in. Give them credentials in the study invitation, or use a staging environment with a shared account.
  </Accordion>

  <Accordion title="Can I test more than one prototype in a study?">
    Yes. Add each link and Charles will structure the conversation to move between them — useful for old-versus-new comparisons.
  </Accordion>

  <Accordion title="Do participants need to install anything?">
    No. The snippet goes on your site, not on their machine. Participants just click a link.
  </Accordion>

  <Accordion title="Which interview format should I use?">
    Voice is usually right — participants can share their screen, and it's easier to narrate while clicking than to type. Video adds their face, which matters if you want to see reactions as well as actions.
  </Accordion>

  <Accordion title="What if my prototype isn't public yet?">
    Any URL your participants can reach works, including staging. It doesn't need to be indexed, linked, or live to customers.
  </Accordion>
</AccordionGroup>