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

**1. 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.

**2. 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.

**3. 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.

**4. 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.

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, [private CSV or JSONL interview exports](/api-reference/interview-exports), [editable report slide decks](/api-reference/report-slide-exports), and [saved Highlights videos](/api-reference/highlight-clips). Use the persisted report and interview endpoints for current integrations.


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

Public API resources and integration workflows

The public API is available under `/api/public/v1/`. Authenticate with an API key or session credential and use the [OpenAPI specification](/api-reference/openapi.json) to inspect request and response schemas.

* [Organizations](/api-reference/organizations): discover accessible workspaces and select one for reads, writes, usage, and billing with `X-UI-Organization-ID` or MCP `organization_id`.
* [Intelligence Hub](/api-reference/intelligence-hub): manage organization sessions and sources, chat with evidence, and create or edit reports, PowerPoints, and videos through durable jobs.
* Study planning: create a metadata draft, customize its plan, and review the saved result before recruiting participants.
* Participants and interviews: manage BYOP invitations, customer IDs and metadata; inspect interview summaries and bounded transcripts.
* Reports and exports: read saved findings, create private CSV or JSONL interview exports, export editable PowerPoints, and generate saved Highlights videos. Signed download URLs expire after 15 minutes.
* [Webhooks](/api-reference/webhooks/overview): receive signed lifecycle events, inspect deliveries, and manage subscriptions by ID.
* Reference catalogs: inspect languages, interview modes, voices, study templates, targeting attributes, and interview usage.

API-key scopes, spend caps, organization membership checks, and paid-action approval requirements apply to each operation.


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

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


# Highlights videos
Source: https://docs.userintuition.ai/api-reference/highlight-clips

Create and watch a saved video from default-report findings and original participant audio.

Highlights use the [Intelligence Hub session API](/api-reference/intelligence-hub).

1. Create an organization session and sync its study sources.
2. Call `POST /api/public/v1/intelligence-hub/sessions/{session_id}/outputs` with
   `type: "highlights"`, a descriptive `prompt`, and an `Idempotency-Key` header.
3. Poll the returned `poll_url` until the job succeeds. Read its `result.output_id`.
4. Read or download the saved output through the session's output endpoints.

One retained MP4 is generated per default-report revision. Learning goals become
chapter cards and the corresponding detailed-finding quotations become segments,
with branded opening and closing cards. Repeated requests reuse the saved video;
the prompt does not select different quotations. Original participant audio is
used where available; chat-only studies have no artificial narration.

Reads and downloads recheck source access. Downloads redirect to a short-lived
private capability URL; do not treat that URL as permanent public hosting. Audio
may contain participants' identities, so review the video before sharing it.

For MCP, use `generate_research_output` with `type: "highlights"`, poll
`inspect_research_session` with `view: "job"`, and use `download_research_output`
for a private video link. Advanced run-bound individual clips/reels are
available through `queue_research_deliverable`; these use canonical evidence IDs
and their existing explicit audio-export acknowledgement.


# Intelligence Hub API
Source: https://docs.userintuition.ai/api-reference/intelligence-hub

Organization sessions, sources, synchronous and asynchronous chat, and Studio outputs.

> [!NOTE]
>
> Use the [MCP tools](/mcp-server/tools/intelligence-hub) for the same workflow from an agent.

Base path: `/api/public/v1/intelligence-hub`. Authenticate with an
`Authorization: Bearer ui_sk_…` organization API key. GET requests require
`read`; mutations require `write`. Sessions are scoped to the authenticated
organization and application, including for administrators. Users with multiple memberships can
select an accessible organization using `X-UI-Organization-ID`;
there is no global session-list bypass. Personal sessions
are not exposed through this API. Platform admins can discover and attach studies
from other organizations within the same application, while keeping the session
in their selected workspace. Non-admins can attach only their organization’s studies.

The Hub provides durable jobs, evidence retrieval, verified references, saved
reports, and native PowerPoint output.

## Endpoints

Paths below are relative to the base path. `S` is a session UUID; `O` is an
output UUID. Request and response schemas and examples are included in the
generated public OpenAPI specification.

| Method | Path | Purpose / request |
| - | - | - |
| POST | `/sessions` | Create: `{"name":"Customer research"}` |
| GET | `/sessions` | List organization sessions |
| GET | `/sessions/S` | Read session |
| PATCH | `/sessions/S` | Rename: `{"name":"New name"}` |
| DELETE | `/sessions/S` | Soft-delete session |
| PUT | `/sessions/S/studies/{study_id}` | Add or resync an accessible study |
| POST | `/sessions/S/sources` | Upload external evidence, multipart `file` |
| GET | `/sessions/S/sources` | List study and document sources |
| DELETE | `/sessions/S/sources/{source_id}` | Remove a source using its returned opaque ID |
| POST | `/sessions/S/chat` | Synchronous chat with durable timeout recovery |
| POST | `/sessions/S/chat/jobs` | Asynchronous chat |
| GET | `/sessions/S/chat/history` | Read chat turns, including pending turns |
| GET | `/sessions/S/jobs/{job_id}` | Poll preparation, chat, generation, or edit |
| POST | `/sessions/S/outputs` | Generate report, PowerPoint, or Highlights |
| GET | `/sessions/S/outputs` | List Studio outputs, including synced default reports |
| GET | `/sessions/S/outputs/O` | Read output and verified references |
| PATCH | `/sessions/S/outputs/O` | Rename: `{"name":"New name"}` |
| POST | `/sessions/S/outputs/O/edits` | Edit in place: `{"prompt":"Shorten the executive summary"}` |
| DELETE | `/sessions/S/outputs/O` | Soft-delete output |
| GET | `/sessions/S/outputs/O/download` | Download Markdown, PPTX, PDF, or MP4 |
| POST | `/sessions/S/templates?kind=report` | Upload a report template, multipart `file` |
| POST | `/sessions/S/templates?kind=presentation` | Upload a presentation template |

Lists use `limit` (default 50, maximum 200 per page) and `after`. Pass the returned
`next_cursor` unchanged to fetch the next page. This page size does not limit the
total number of sessions, sources, or outputs. Chat history is chronological and
excludes automatic study-preparation runs.

## Analysis and exports

Advanced operations also use the same base path and session authorization.
`R` is a run UUID; `J` is a deliverable job UUID. MCP uses these canonical routes.

| Method | Path | Purpose |
| - | - | - |
| GET | `/studies` | Discover accessible studies, including other organizations for platform admins |
| POST | `/sessions/S/sources/all` | Add all accessible studies |
| DELETE | `/sessions/S/sources` | Clear selected studies (external documents remain) |
| POST | `/sessions/S/runs` | Start analysis with `Idempotency-Key` |
| GET | `/sessions/S/runs` | List analysis runs |
| GET | `/runs/R` | Read analysis status/result |
| GET | `/runs/R/chat` | Read verified chat answer |
| GET | `/runs/R/studies` | Read study coverage |
| POST | `/runs/R/resume` | Resume analysis |
| POST | `/runs/R/cancel` | Cancel analysis |
| GET | `/runs/R/events` | Stream progress events |
| GET | `/runs/R/claims` | Read verified claims |
| GET | `/evidence/{evidence_id}?run_id=R` | Read evidence within an authorized run |
| GET | `/runs/R/export` | Export analysis |
| GET | `/runs/R/sources` | Read source manifest |
| GET | `/runs/R/exclusions` | Read exclusions |
| GET, POST | `/sessions/S/report-video` | Read or generate saved highlights |
| GET, POST | `/runs/R/report-video` | Read or generate run highlights |
| GET | `/runs/R/highlights` | Read highlight candidates |
| POST | `/runs/R/deliverables` | Queue presentation, clip or reel with `Idempotency-Key` |
| GET | `/runs/R/deliverables` | List exports |
| GET | `/deliverables/J` | Poll export and obtain a fresh download URL |
| POST | `/deliverables/J/cancel` | Cancel export |

Use `/sessions/S/sources` for the canonical study/document source list and
`/sessions/S/outputs` for saved Studio outputs. There are no duplicate public
session creation, document upload, or Studio-save routes.

## Availability

Hub endpoints return `404` when Hub analysis is disabled or the selected organization is outside the enabled organization list. A valid credential alone does not enable this feature.

## Retry and async contracts

Session creation, chat, generation, edits, analysis creation, and deliverable creation require `Idempotency-Key` (1–200 characters). Reuse
the same key and body after an uncertain network response; use a new key for a
new operation. Conflicting reuse returns 409. Sync and async chat share the same
underlying job, so callers can switch between them with the original key.
Completed edits also replay the original job after the output has changed; retry
keys are matched to the submitted request, not the current model settings or output revision.

Both chat endpoints accept:

```json theme={null}
{"prompt":"What drives trust? Include verified quotations.","parent_job_id":null,"include_synthetic":false}
```

For a follow-up, set `parent_job_id` to a completed chat job in the same session.
`POST /chat` waits up to 120 seconds (`wait_seconds=0..120`). If still running,
it returns **202**, the existing `job_id`, and `poll_url`; it does not cancel or
restart the job. `/chat/jobs` returns **202** immediately. Poll until `status`
is `succeeded` or `failed`. On success, `result.answer` and `result.references`
contain the response. A partial completed analysis sets `result.partial=true`.
Failed jobs return a public-safe error, without internal exception details.

Study sync returns a `preparation_job_id` when preparation is needed. Poll it
using the same jobs endpoint. Repeated sync reuses revision-aware preparation.
External evidence supports TXT, Markdown, CSV, JSON, text PDFs, and DOCX up to
10 MB, using the same parser as the dashboard.

## Outputs and references

Example generation body:

```json theme={null}
{"type":"powerpoint","name":"Trust findings","prompt":"Summarize the saved findings for the product team.","template_id":null}
```

Generation and edits return **202** with a job. `result.output_id` identifies
the saved output when successful. PowerPoint jobs remain running until the
rendered file is ready. Edits retain the output ID and reuse the saved evidence;
default reports cannot be edited or renamed. Report and PowerPoint edits are
supported; Highlights are derived from default reports, not edited with prompts.

`type:"highlights"` requests the saved default-report video, generated once per
report revision. Its required `prompt` describes the request but does not
change quote selection. Original participant audio is used where available;
chat-only sources do not receive artificial narration.

Reads include structured `references`: display label, study/interview ID,
message index, and verified quotation. Document references include a source ID
and page when available. Provider call identifiers, evidence hashes, and hidden
dashboard reference catalogs are not part of the public content contract.

Downloads default to Markdown for reports, PPTX for PowerPoints, and MP4 for
Highlights. Use `?format=pdf` for a rendered presentation PDF. Video downloads
redirect to a short-lived download capability. Access to source evidence is
checked again when reading results or downloading files. Removing evidence can
make earlier results unavailable; it does not grant continued access through
saved output IDs.

Templates use the dashboard's existing 5 MB upload and validation rules. Pass
the returned template ID when generating the matching output type.

Report templates accept Markdown, TXT, or DOCX with placeholders such as `{{title}}`
and `{{findings}}`. Presentation templates accept 16:9 PPTX files and reuse their
theme and layouts. Templates provide formatting, not research evidence.

Expired or revoked outputs remain listable with `status: "unavailable"`; one
unavailable artifact does not prevent listing the other session outputs.

## Read a chat reference

`GET /intelligence-hub/sessions/{session_id}/jobs/{job_id}/references/{label}` resolves a verified citation from a completed chat answer. Use the exact `label` returned with that job. The response includes `reference`, `study_name`, `participant_label`, and an optional `interview` with speech around the cited turn and available playback links. Document references have no interview. Organization, session and source access are checked again; an unknown label or mismatched session does not return evidence.


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

> **[OpenAPI Specification](/api-reference/openapi.json)**
>
> View the complete OpenAPI specification

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 [API capabilities](/api-reference/changelog) for available workflows and [API versioning](/api-reference/versioning-and-deprecation) for the public contract.

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/).

## Pagination

Study, participant, and interview lists use `page` and `page_size`. Hub lists, research search, and deliverable lists return `next_cursor`; pass it unchanged as the endpoint’s `after` or `cursor` input with the same filters. Stop when it is null. An empty page can have a continuation cursor.

## 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. For Hub session creation, chat, output generation, edits, and analysis/deliverable creation, the key is required and is limited to 200 characters. Calls to other operations 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.

> **[Runnable developer examples](/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.

## 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 can belong to multiple organizations. [List accessible organizations and select one](/api-reference/organizations) for reads, writes, usage, and billing. Ordinary users can select active memberships; platform administrators retain app-wide access. API-key scopes and spend caps still apply.

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.

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

**1. 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**.

**2. Go to the API Keys tab**

In the account management dialog, click **API Keys** in the sidebar.

**3. 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.

**4. 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.

**5. Use the key**

Pass the key as a Bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer ui_sk_aBcDeFgHiJkLmNoPqRs...
```

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.

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

### JWT tokens

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

**1. Sign in to your account**

Sign in to your [User Intuition Dashboard](https://app.userintuition.ai) if you haven't already.

**2. Open your profile**

Click on your profile in the bottom-left corner of the sidebar. This will show your name and company.

**3. Select View JWT Token**

Select **"View JWT Token"** from the dropdown menu (it has a key icon).

**4. Copy your token**

A dialog will appear displaying your JWT token. Click the **"Copy Token"** button to copy the token to your clipboard.

**5. Confirmation**

You'll see a confirmation message when the token has been successfully copied.

> [!WARNING]
>
> Keep your JWT token secure and do not share it with others. This token provides authenticated access to your account.

## Available Resources

> **[Studies](/api-reference/public-studies/list-studies)**
>
> Create and manage your studies, screeners, and interview configuration.

> **[Interviews](/api-reference/public-interviews/list-interviews)**
>
> Access interview records, transcripts, recordings, and analysis data.

> **[Participants](/api-reference/public-participants/create-participants)**
>
> Invite participants, send rewards, and track their status.

> **[Webhooks](/api-reference/webhooks/overview)**
>
> Receive interview data at your own endpoint as soon as an interview completes.

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

`research_period: null` means fieldwork dates are unavailable. Date filters exclude undated documents. A saved interview evidence snapshot supplies the fieldwork dates during indexing. Generate a report with dated interview evidence to include it in date-filtered search.

## Rate Limiting

API requests are rate limited to ensure fair usage. The default budgets are 300 requests per 60 seconds per signed-in user and 120 per API key or anonymous IP; deployed configuration can change them. 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, ordinary requests continue without rate headers; paid public actions are blocked.

## Support

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


# Organizations and workspace selection
Source: https://docs.userintuition.ai/api-reference/organizations

Discover accessible organizations and choose a workspace for API and MCP operations.

A user can belong to multiple organizations. Call `GET /api/public/v1/organizations` to list accessible organizations, then select one for subsequent requests. Ordinary users see only their active memberships in the current app; platform administrators have app-wide discovery and research access. Organization owner or member roles do not grant platform-wide access.

The listing accepts `search` for an organization name, active owner name, or owner email, plus `page` and `page_size` (maximum 100). Access filtering and search happen before pagination. Results contain organization IDs, names, and an `owners` array of active owner names and emails; it may be empty.

Pass the chosen organization on each request:

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

The header works with sessions and API keys. The API checks active membership for ordinary users and rejects an unauthorized selection with `403`. Missing, deleted, or cross-app organizations are unavailable. Selection changes only this request's workspace, billing, and audit context; it does not grant an administrator role or remove API-key scope checks, spend caps, or paid-action approval requirements. Without the header, the credential's default organization is used; platform administrators have global research read access.

Use the same organization for reads, writes, usage, job polls, and billing. A selected organization that differs from the study's organization returns `404`. A platform administrator changing another organization's study without selecting its organization receives `409 organization_required`.

MCP tools accept the equivalent optional `organization_id` input. Start with `list_organizations`, show the matches to the human, then pass the chosen ID to subsequent tools. `get_account` and `get_interview_usage_stats` accept it too. Verify the selected account and show the estimate before paid recruitment or participant rewards. Organization discovery is available on the full, core, read-only, and compact MCP profiles.


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


# Get Account
Source: https://docs.userintuition.ai/api-reference/public-account/get-account

/api-reference/openapi.json get /api/public/v1/account/
Return account scope, available credits, and payment readiness.



# Get Account Identity
Source: https://docs.userintuition.ai/api-reference/public-account/get-account-identity

/api-reference/openapi.json get /api/public/v1/account/identity
Return the authenticated workspace without changing account state.



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



# Get Report Slide Export Job
Source: https://docs.userintuition.ai/api-reference/public-exports/get-report-slide-export-job

/api-reference/openapi.json get /api/public/v1/studies/{study_id}/exports/report-slides/jobs/{job_id}
Poll a slide export and receive a fresh private download URL.



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



# Queue Report Slide Export
Source: https://docs.userintuition.ai/api-reference/public-exports/queue-report-slide-export

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/exports/report-slides
Queue an editable PowerPoint deck from the latest saved study report.



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



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

/api-reference/openapi.json post /api/public/v1/feasibility-requests/{request_id}/cancel
Withdraw a pending request before a feasibility response is issued.



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



# Add All Sources
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/add-all-sources

/api-reference/openapi.json post /api/public/v1/intelligence-hub/sessions/{session_id}/sources/all
Select all accessible studies server-side without a fixed study-count cap.



# Available Studies
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/available-studies

/api-reference/openapi.json get /api/public/v1/intelligence-hub/studies
List accessible studies with cursor pagination for session source selection.



# Cancel
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/cancel

/api-reference/openapi.json post /api/public/v1/intelligence-hub/runs/{run_id}/cancel
Cancel pending or running analysis. Lease fencing prevents cancelled workers from publishing.



# Cancel Deliverable
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/cancel-deliverable

/api-reference/openapi.json post /api/public/v1/intelligence-hub/deliverables/{job_id}/cancel
Cancel a queued or running export. A cancelled worker cannot publish its file.



# Chat
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/chat

/api-reference/openapi.json post /api/public/v1/intelligence-hub/sessions/{session_id}/chat
Wait for a chat answer; return 202 with the same durable job if the wait expires. The timeout never cancels analysis. Use /chat/jobs for immediate acknowledgement.



# Chat Answer
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/chat-answer

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}/chat
Read the verified chat answer from a completed run.



# Claims
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/claims

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}/claims
Inspect paginated interview-level findings from completed tasks in this run.



# Clear Sources
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/clear-sources

/api-reference/openapi.json delete /api/public/v1/intelligence-hub/sessions/{session_id}/sources
Clear selected session studies and revoke artifacts that depend on removed sources.



# Create Report Video
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/create-report-video

/api-reference/openapi.json post /api/public/v1/intelligence-hub/runs/{run_id}/report-video
Generate once from default report Quotes; repeat requests reuse the retained video.



# Create Run
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/create-run

/api-reference/openapi.json post /api/public/v1/intelligence-hub/sessions/{session_id}/runs
Start a durable analysis of the session sources. Reuse Idempotency-Key after a timeout. Study findings are prepared on sync and reused; editorial revisions reuse the original evidence. Presentation outputs automatically queue a PowerPoint when analysis completes.



# Create Session
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/create-session

/api-reference/openapi.json post /api/public/v1/intelligence-hub/sessions
Create an organization-owned Intelligence Hub session. Reuse Idempotency-Key to recover the same session.



# Create Session Video
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/create-session-video

/api-reference/openapi.json post /api/public/v1/intelligence-hub/sessions/{session_id}/report-video
Generate the saved default-report video once per report revision.



# Delete Output
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/delete-output

/api-reference/openapi.json delete /api/public/v1/intelligence-hub/sessions/{session_id}/outputs/{output_id}
Soft-delete a Studio output without deleting its underlying study.



# Delete Session
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/delete-session

/api-reference/openapi.json delete /api/public/v1/intelligence-hub/sessions/{session_id}
Soft-delete a session, revoking access to its analysis and outputs.



# Download Output
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/download-output

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions/{session_id}/outputs/{output_id}/download
Download a report, PowerPoint/PDF, or private Highlights video. Access is rechecked on every request.



# Edit Output
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/edit-output

/api-reference/openapi.json post /api/public/v1/intelligence-hub/sessions/{session_id}/outputs/{output_id}/edits
Apply a prompt to the existing output in place; default reports are read-only.



# Events
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/events

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}/events
Stream authorized analysis progress as server-sent events. Reconnect using the event cursor.



# Evidence
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/evidence

/api-reference/openapi.json get /api/public/v1/intelligence-hub/evidence/{evidence_id}
Retrieve canonical evidence and its transcript locator within an authorized run.



# Excluded Sources
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/excluded-sources

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}/exclusions
List excluded interviews and their exclusion reasons with cursor pagination.



# Export
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/export

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}/export
Download verified run results as JSON, Markdown, CSV or editable PowerPoint. The run must be completed or partial; partial coverage remains explicit.



# Generate Output
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/generate-output

/api-reference/openapi.json post /api/public/v1/intelligence-hub/sessions/{session_id}/outputs
Generate a report, native PowerPoint, or the saved default-report Highlights video. Highlights use original audio where available and are generated once per report revision; their prompt does not select new quotations.



# Get Chat Reference
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/get-chat-reference

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions/{session_id}/jobs/{job_id}/references/{label}
Resolve only a verified citation from this answer, rechecking source access.



# Get Deliverable
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/get-deliverable

/api-reference/openapi.json get /api/public/v1/intelligence-hub/deliverables/{job_id}
Inspect an authorized export. Successful jobs return a private download URL valid for 15 minutes. Artifacts expire after seven days; source access is checked again at download.



# Get Job
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/get-job

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions/{session_id}/jobs/{job_id}
Poll a durable analysis or video job within the session. Internal errors are suppressed; completed responses include the result or output ID.



# Get Output
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/get-output

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions/{session_id}/outputs/{output_id}
Read one saved Studio output and its verified references after rechecking source access.



# Get Run
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/get-run

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}
Inspect analysis status, verified results, coverage, budget and source changes. Access to the run and underlying sources is checked on every read.



# Get Session
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/get-session

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions/{session_id}
Read a session in the authenticated organization.



# Highlight Candidates
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/highlight-candidates

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}/highlights
List cited evidence eligible for audio clipping, with exact IDs, stored timestamps and ineligibility reasons. Follow next_cursor for additional candidates.



# History
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/history

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions/{session_id}/chat/history
Read session chat turns from the durable Hub history, including pending turns.



# List Deliverables
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/list-deliverables

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}/deliverables
List recent durable exports for this run with cursor pagination. Poll an individual job for a fresh download capability.



# List Outputs
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/list-outputs

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions/{session_id}/outputs
List saved Studio outputs, including default reports and pending generations, with cursor pagination.



# List Sessions
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/list-sessions

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions
List sessions in the authenticated organization with cursor pagination.



# List Sources
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/list-sources

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions/{session_id}/sources
List study and external-document sources with a shared cursor. Source IDs can be passed to removeHubSource.



# Queue Chat
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/queue-chat

/api-reference/openapi.json post /api/public/v1/intelligence-hub/sessions/{session_id}/chat/jobs
Queue a chat turn. Reuse Idempotency-Key after an uncertain response.



# Queue Deliverable
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/queue-deliverable

/api-reference/openapi.json post /api/public/v1/intelligence-hub/runs/{run_id}/deliverables
Queue an editable presentation, a single clip or an ordered reel from a completed or partial run. Reuse Idempotency-Key after a timeout. Audio requires exact verified evidence IDs, validated recording times and explicit acknowledgement of unredacted speech.



# Remove Source
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/remove-source

/api-reference/openapi.json delete /api/public/v1/intelligence-hub/sessions/{session_id}/sources/{source_id}
Remove a source from the session and revoke dependent evidence access.



# Rename Output
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/rename-output

/api-reference/openapi.json patch /api/public/v1/intelligence-hub/sessions/{session_id}/outputs/{output_id}
Rename a Studio output. Default reports are read-only.



# Rename Session
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/rename-session

/api-reference/openapi.json patch /api/public/v1/intelligence-hub/sessions/{session_id}
Rename an existing organization session.



# Resume
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/resume

/api-reference/openapi.json post /api/public/v1/intelligence-hub/runs/{run_id}/resume
Resume a paused analysis with an explicit additional model-call budget. Completed checkpoints are retained.



# Run Studies
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/run-studies

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}/studies
List the frozen study manifest for this run with cursor pagination.



# Runs
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/runs

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions/{session_id}/runs
List this session’s durable analysis history with cursor pagination.



# Saved Report Video
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/saved-report-video

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}/report-video
Read the saved highlights video associated with a run.



# Saved Session Video
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/saved-session-video

/api-reference/openapi.json get /api/public/v1/intelligence-hub/sessions/{session_id}/report-video
Read the saved default-report video for a session.



# Source Manifest
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/source-manifest

/api-reference/openapi.json get /api/public/v1/intelligence-hub/runs/{run_id}/sources
List the run’s frozen source revisions and processing coverage with cursor pagination.



# Sync Study
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/sync-study

/api-reference/openapi.json put /api/public/v1/intelligence-hub/sessions/{session_id}/studies/{study_id}
Add or resync a study and queue revision-aware File Search preparation.



# Upload Source
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/upload-source

/api-reference/openapi.json post /api/public/v1/intelligence-hub/sessions/{session_id}/sources
Attach TXT, Markdown, CSV, JSON, text PDF or DOCX evidence (up to 10 MB).



# Upload Template
Source: https://docs.userintuition.ai/api-reference/public-intelligence-hub/upload-template

/api-reference/openapi.json post /api/public/v1/intelligence-hub/sessions/{session_id}/templates
Upload a session-owned report template (TXT, Markdown, DOCX) or 16:9 PPTX template, up to 5 MB. Use its ID during generation.



# 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 Organizations
Source: https://docs.userintuition.ai/api-reference/public-organizations/list-organizations

/api-reference/openapi.json get /api/public/v1/organizations
List accessible organizations and active owner contacts. Users may belong to multiple organizations; select one with X-UI-Organization-ID on subsequent operations. Results are limited to active memberships unless the caller has platform-wide access.



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



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

/api-reference/openapi.json delete /api/public/v1/participants/{participant_id}
Soft-delete a BYOP invitation; linked interviews require explicit cascade consent.



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



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

/api-reference/openapi.json get /api/public/v1/participants/jobs/{job_id}
Poll an asynchronous participant creation job until it succeeds or fails.



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



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



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

/api-reference/openapi.json post /api/public/v1/research/answer/
Answer from accessible indexed research with validated source citations.



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



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

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/estimate-panel
Read-only estimate of one panel recruitment cycle, including balance and card hold.



# 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 Fielding Progress
Source: https://docs.userintuition.ai/api-reference/public-studies/get-fielding-progress

/api-reference/openapi.json get /api/public/v1/studies/{study_id}/fielding-progress
Show current target progress, quality grades, and a conservative finish estimate.



# 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 Report Job
Source: https://docs.userintuition.ai/api-reference/public-studies/get-report-job

/api-reference/openapi.json get /api/public/v1/studies/{study_id}/report/jobs/{job_id}
Poll an asynchronous report job until it succeeds or fails.



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



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

/api-reference/openapi.json get /api/public/v1/studies/{study_id}/embed-code
Return copy-ready HTML that launches a study from another website.



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



# Upload Concept Image
Source: https://docs.userintuition.ai/api-reference/public-studies/upload-concept-image

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/concept-images
Upload a participant-facing image stimulus, up to 10 MB, to an owned study.



# Upload Concept Image From Url
Source: https://docs.userintuition.ai/api-reference/public-studies/upload-concept-image-from-url

/api-reference/openapi.json post /api/public/v1/studies/{study_id}/concept-images/from-url
Fetch a public image URL with redirect and private-network checks, then attach it to an owned study.



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



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

/api-reference/openapi.json get /api/public/v1/webhooks/{webhook_id}
Retrieve one registered webhook without its signing secret.



# List Webhook Deliveries
Source: https://docs.userintuition.ai/api-reference/public-webhooks/list-webhook-deliveries

/api-reference/openapi.json get /api/public/v1/webhooks/{webhook_id}/deliveries
List bounded webhook delivery attempts and status without event payloads.



# List Webhooks
Source: https://docs.userintuition.ai/api-reference/public-webhooks/list-webhooks

/api-reference/openapi.json get /api/public/v1/webhooks/
List the account's registered event webhooks without signing secrets.



# Rotate Webhook Secret
Source: https://docs.userintuition.ai/api-reference/public-webhooks/rotate-webhook-secret

/api-reference/openapi.json post /api/public/v1/webhooks/{webhook_id}/rotate-secret
Replace the signing secret; the new value is returned once.



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

/api-reference/openapi.json post /api/public/v1/webhooks/{webhook_id}/test
Send a signed test event containing no participant or study data.



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


# Report slide exports
Source: https://docs.userintuition.ai/api-reference/report-slide-exports

Download an editable presentation from a saved study report

## Create a deck

Call `POST /api/public/v1/studies/{study_id}/exports/report-slides` after the study report has been generated. 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/report-slides?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/report-slides/jobs/{job_id}` until `status` is `succeeded`. The successful response includes `slide_count` and a fresh `download_url`. Download the editable PowerPoint (`.pptx`) file from that URL.

The deck contains the saved executive summary, key metrics, findings and quotations, participant profiles, evidence coverage and gaps, next steps, and source reference IDs. It flags reports with outdated inputs or unverified evidence. It does not include raw participant response transcripts or recording URLs. Generate a new report first if you need current findings.

## Privacy and retention

Exports default to `redact_pii=true`, which masks common email, phone, and US Social Security number patterns in report text. Pattern masking cannot detect every identifier, including names and street addresses. Set `redact_pii=false` only when your use requires unmasked report text.

The file lives in the private `research-exports` bucket. The polling endpoint checks study access and job ownership before issuing a signed URL that lasts 15 minutes. The job stops issuing URLs after seven days, when the job processor deletes expired export objects. Store downloaded files according to your own retention policy.

## Export limits and errors

Files must be at most 50 MB. A missing saved report returns `404` with `no_report_yet`; generate the report and wait for its job to succeed before exporting. An expired export returns `410`; queue a new export. Download URLs use HTTPS and expire after 15 minutes.


# 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 supplied on creation or update may contain at most 40 characters. Reads can return longer saved names.

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.


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

The public API contract and client requirements

The integration API is served under `/api/public/v1/`. The [OpenAPI specification](/api-reference/openapi.json) describes its operations, authentication, request schemas, and response schemas.

Clients should ignore response fields they do not recognize and process the webhook event types they subscribe to. Optional fields and event types allow the API to support additional workflows within v1.

Use the documented public routes and schemas when building an integration. Consult the resource guides for pagination, durable jobs, idempotency, and error handling.


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

**1. 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.

**2. 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.

**3. Stop receiving data**

Delete the webhook by its `id` to stop further deliveries. The URL-based
delete endpoint remains available for account-wide registrations.

> [!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.

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

## 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)
```

**1. Verify the signature**

Reject any request whose `X-UI-Signature` doesn't match your recomputed HMAC.

**2. 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.

**3. Use HTTPS**

Always register an `https://` URL so the payload is encrypted in transit.

> [!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.

## 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.
Use `DELETE /api/public/v1/webhooks/{webhook_id}` to delete a registered webhook.

> **[Create Webhook](/api-reference/public-webhooks/create-webhook)**
>
> Register a URL, optional study scope, and event subscriptions.

> **[Delete Webhook](/api-reference/public-webhooks/delete-webhook-by-id)**
>
> Stop sending completed interviews to a registered webhook ID.


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

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

| Subcommand | Purpose |
| - | - |
| `login` or `auth login` \[--scopes read,write,...] | Sign in through browser OAuth with PKCE. |
| `auth status` | Show whether OAuth and a saved API key are configured. |
| `logout` or `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. |

\| `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 estimate_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 estimate_panel --json | jq .inputSchema
userintuition-mcp describe --json estimate_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.

**Inline flags**

`--key value` pairs. Values are JSON-parsed when possible, so the right type lands in the schema:

```bash theme={null}
userintuition-mcp estimate_panel \
  --study_id 11111111-1111-4111-8111-111111111111 \
  --target 25 \
  --incident_rate 50 \
  --country_code US
```

* `--target 25` → number `25`
* `--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`.

**Inline JSON**

For deeply nested inputs:

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

When `--input-json` is provided, all other `--flag` arguments are ignored.

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

### 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 estimate_panel --study_id 11111111-1111-4111-8111-111111111111 --target notanumber --incident_rate 50 --country_code US
Invalid input for estimate_panel: target: Invalid input: expected number, received string
$ 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 11111111-1111-4111-8111-111111111111 --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 11111111-1111-4111-8111-111111111111 | jq .
{"error": "Study not found"}
$ echo ${PIPESTATUS[0]}
1
```

Recoverable API failures may include typed fields in addition to the `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 participant rewards, 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 75 direct tool commands. Panel launch and review Apps are available through MCP clients; use the CLI for estimates, provisioning, and fielding inspection. 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 — 75 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 75 direct tool commands include `create_study`, `list_studies`, `estimate_panel`, `generate_report`, `search_research`, and `answer_research`. Paid panel launch and study/answer Apps use an MCP client. 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 for a Panel estimate, 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).

## Next steps

> **[Quickstart](/cli/quickstart)**
>
> Install the binary and make your first call in under two minutes.

> **[Command reference](/cli/commands)**
>
> Every subcommand, every flag, with examples.

> **[Recipes](/cli/recipes)**
>
> Practical patterns — CI cost gates, lifecycle scripts, batch operations.

> **[Troubleshooting](/cli/troubleshooting)**
>
> Auth errors, missing binaries, common pitfalls.


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

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

## 1. Install

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

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

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

## 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. `USERINTUITION_API_KEY` environments are supported and take precedence over saved credentials.

## 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. To launch recruitment, open an MCP client and use its panel review and human approval flow. The CLI supports estimation and fielding inspection.

## Next steps

> **[Command reference](/cli/commands)**
>
> Full reference for `list`, `describe`, `call`, and every flag.

> **[Recipes](/cli/recipes)**
>
> CI cost gates, lifecycle scripts, batch operations.


# 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 ✓"
```

***

## Inspect fielding and retrieve a report

After a person launches recruitment through an MCP client, inspect its progress and retrieve a generated report. This script observes fielding for up to 24 hours, then queues and polls report generation:

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

study_id="$1"
target=25

# Recruitment is approved and launched through an MCP client.

# 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
job_id=$(userintuition-mcp generate_report --study_id "$study_id" | jq -er '.job_id')
report_deadline=$(( $(date +%s) + 1800 ))
while true; do
  job=$(userintuition-mcp get_report_job --study_id "$study_id" --job_id "$job_id")
  status=$(jq -r '.status' <<<"$job")
  case "$status" in
    succeeded) break ;;
    failed|cancelled) echo "$job" >&2; exit 1 ;;
  esac
  (( $(date +%s) < report_deadline )) || { echo "Report job still pending: $job_id" >&2; exit 1; }
  sleep 5
done
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.

***

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

***

## Discovering tools by capability

The CLI exposes 75 direct tool commands. Use its local inventory to discover commands. 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.
* **Use MCP for paid panel launch.** The person reviews the saved plan and quote and approves through the App or explicit chat confirmation.
* **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:

**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`.

**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
```

**One-shot**

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

No install needed — npm downloads on demand.

**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
```

***

## `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 estimate_panel --study_id 11111111-1111-4111-8111-111111111111 --target notanumber --incident_rate 50 --country_code US
Invalid input for estimate_panel: target: Invalid input: expected number, received string
```

Re-read the schema:

```bash theme={null}
userintuition-mcp describe estimate_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"`; `--quality '["Excellent"]'` not `--quality Excellent`.
* **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: In-depth Interview, Concept Test, or Prototype Test.

Pick the study type that matches what you want to learn. 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, just a conversation.** Use this when you want to learn from people's lived experience. The moderator 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 the moderator 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.

***

## Select your study type

**1. Pick a card**

Click the study type that matches what you're trying to learn. The selected card is highlighted with a dark background.

**2. Continue**

Click **Save & Continue** to go to Customize Plan.

> [!TIP]
>
> 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.

***

## Frequently asked questions

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

> **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).

> **What if my research spans more than one study type?**
>
> Pick the one that matches your primary objective. In step 2, tell Charles about your other objectives and he'll work them into the plan.

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

***

## Next steps

> **[Step 2: Customize Plan](/creating-a-study/customize-plan)**
>
> Work with Charles to tailor the research plan.

> **[Study Types](/study-types/overview)**
>
> What each study type does, how to set it up, and what you get back.


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

Chat with Charles, our AI researcher, to build a research plan around your company, situation, and objectives.

Work with Charles, our AI researcher, to design a research plan for your context and objectives. A generic study asks generic questions. One built around your company, recent changes, and hypotheses gets insights you can act on.

***

## Chat with Charles

Type your context in the chat, and the research plan builds in the panel on the right as you go. Keep chatting to refine it.

At a minimum, Charles needs:

* **Company or product name**, so the moderator knows who it's representing
* **Core research question**: what you're trying to learn

> [!TIP]
>
> If the default plan meets your needs, type something like "Use your best judgment" to proceed with the standard template. More context usually gives more actionable insights.

### Add attachments

Click the **paperclip** in the message box to open **Add attachment**. You can add:

* **A project brief (.docx)**: one Word document per message. Charles reads it as context for the plan.
* **Concept images** (PNG, JPG, GIF, or WebP): the images you want participants to react to. Each image needs a unique label. See [Concept Test](/study-types/concept-test#attaching-images).

Files can be up to 10 MB each. Attachments are sent with your next message.

### Add links

To add a concept link or a prototype, paste the URL into the chat and tell Charles what it is. If the page appears to need a login, you're asked for login details to share with participants. See [Prototype Test](/study-types/prototype-test#adding-your-prototype).

***

## What Charles will ask

Charles asks clarifying questions about your research context. They depend on your study type and what you share, and usually cover:

**Context**

* **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**

* **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?

**Objectives**

* **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 how a conversation with Charles might start 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 in the right panel. It 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 |

***

## Edit the research plan

You have two ways to refine the plan.

### Keep chatting

Ask Charles for 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 updates the plan based on your feedback.

> [!TIP]
>
> 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.

### Edit directly in Review Goals

For small wording changes, edit the plan directly in the next step.

When the plan covers your key questions, click **Save & Continue**.

***

## Frequently asked questions

> **What if Charles asks a question I don't know the answer to?**
>
> Tell Charles what you do know. He works with whatever context you can provide.

> **Can I come back and change the plan later?**
>
> Yes. Click **Back** to return to this step at any point, or edit the plan directly in step 3.

> **How long does this step take?**
>
> Usually 5–10 minutes. Complex research can take longer.

***

## Next steps

> **[Step 3: Review Goals](/creating-a-study/review-goals)**
>
> Name your study and edit the plan directly.

> **[Best Practices](/resources/best-practices)**
>
> Design focused studies and turn interviews into decisions.


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

See the six setup steps for creating a study, what you need before you start, and what to do once it's live.

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 steps

| 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

Have two things ready:

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

By the end you'll have a research plan tailored to your question, a configured moderator, and a study ready to launch to your participants.

***

## Tips for a good study

**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 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 use. Avoid internal jargon in your questions.

***

## After launch

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

* [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

> **Can I save and return later?**
>
> Yes. Progress saves automatically, so you can close the browser and pick up where you left off.

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

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

***

## Next steps

> **[Step 1: Create Study](/creating-a-study/create-study)**
>
> Pick the study type that matches what you want to learn.

> **[Study Types](/study-types/overview)**
>
> Compare the three study types before you start.


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

Review your full study configuration, then launch so the 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.

***

## What you'll see

### Summary cards

At the top of the **Review your Study** screen, five cards summarize your configuration:

| Card | Shows |
| - | - |
| **Study Type** | The type you selected (In-depth Interview, Concept Test, or Prototype Test) |
| **Interviewer** | The moderator voice you chose |
| **Interview Type** | The format you configured (Chat, Voice, or Video) |
| **Language** | The interview language you selected |
| **Recruiting** | Your recruiting method (BYOP, Panel, or Synthetic Respondent) |

### Study name

This is how the study appears in your dashboard.

### Screener questions

Each screener question is listed with its answer options and rules: which options **Disqualify**, and on multiple-select questions which are **Must Select**, **May Select**, or **Reject**. Text-input questions show their allowed and disallowed values, number range, or **All values accepted**.

### Research plan preview

The complete research plan: Objective, Background, Learning Goals, Conversation Flow, and Study-Specific Rules.

***

## Final review checklist

Before launching, confirm:

**Research plan**

* The 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

**Interviewer settings**

* The voice matches your brand and audience
* The interview mode is appropriate for your participants
* The language is the one your participants speak

**Recruiting and screeners**

* The recruiting method is the one you intend to use
* Screener questions qualify and disqualify the right people

**Study configuration**

* The study name is descriptive and recognizable
* You've tested the conversation (recommended)

To change anything, click **Back** to return to the relevant step, make your changes, then click **Save & Continue** through the remaining steps to return here.

***

## Launch your study

When you're ready, click **Save and Invite Participants**. Your study goes live and you're taken to the study dashboard. Launching doesn't send any invitations; you invite participants from the dashboard.

If your workspace has fewer than 3 credits when you launch, you're taken to your **Wallet** to add credits first. Enterprise plans skip this check.

> [!NOTE]
>
> In the [sandbox](/api-reference/staging-quickstart), synthetic studies show **Launch Synthetic Study** instead, which starts three synthetic interviews right away.

***

## What happens after launch

**1. Study goes live**

Your study is immediately active and can receive participants.

**2. Invite participants**

From the dashboard, invite participants using the options for your recruiting method: a study link, email invites, the embed widget, or an external panel for BYOP; our panel for Panel; or synthetic respondents for Synthetic.

**3. Conversations happen**

As participants complete interviews, data flows into your dashboard.

**4. Review and analyze**

Read transcripts, listen to recordings, and generate reports.

**5. 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.

***

## Changes after launch

You can rename the study at any time. You can also edit the research plan, interviewer voice, and interview mode, but avoid doing so once participants have responded.

> [!WARNING]
>
> Changing questions or flow after participants have responded means earlier and later responses won't be directly comparable. For significant changes, create a new study instead.

***

## Frequently asked questions

> **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 **Send Email Invites** is disabled, though the rest of the **Invite Participants** menu stays available. Choose **Resume Study** to start it again. A study that has already reached its target is complete and can't be paused.

> **What if I need to start over?**
>
> Delete the study and create a new one. Deleting is permanent, and all of the study's data is lost.

> **Is there a limit to how many studies I can have active?**
>
> No.

***

## Next steps

> **[Recruiting overview](/recruiting/overview)**
>
> Every way to invite participants, and what each costs.

> **[Dashboard](/managing-your-study/dashboard)**
>
> Track responses and manage your live study.


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

Name your study and edit the research plan Charles generated before you set up the interview.

Review the research plan Charles generated in the previous step, and edit it directly before the study goes live.

***

## Name your study

At the top of the screen, name your study. Charles suggests a name based on your conversation, and you can change it. Names can be up to 40 characters.

A good name includes:

* The research type (e.g., "NPS Deep Dive")
* A date or quarter (e.g., "Q1 2026")
* 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"

***

## Check the research plan

Below the study name, the full research plan opens in a rich text editor. It includes:

* **Objective**: what the study aims to accomplish. It should directly address your business question.
* **Background**: context about your company and situation that informs how the moderator approaches conversations.
* **Learning Goals**: specific, answerable research questions, each with the evidence needed underneath. A goal can also list relevant perspectives or a boundary. Older plans may also have 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 how the moderator runs the conversation.

***

## Edit the research plan

Click into the document and type to edit. The toolbar has undo and redo, a heading dropdown, bold, italic, links, bulleted and numbered lists, and block quotes.

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

Changes save automatically as you edit. For bigger changes, click **Back** to return to Customize Plan and tell Charles what you'd like. He updates the plan, and you can review it again here.

When the plan is ready, click **Save & Continue**.

***

## Frequently asked questions

> **Can I add entirely new sections to the research plan?**
>
> Yes. Keep new content in the same overall structure so the moderator can follow it.

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

> **How long should the research plan be?**
>
> There's no strict limit, but longer plans mean longer interviews. Most effective studies have 4–6 main topic areas with 2–4 questions each.

> **Will participants see this document?**
>
> No. The plan guides the moderator. Participants only experience the conversation.

***

## Next steps

> **[Step 4: Setup Interview](/creating-a-study/setup-interview)**
>
> Choose the voice, format, language, recruiting method, and screeners.

> **[Step 2: Customize Plan](/creating-a-study/customize-plan)**
>
> Go back to Charles for bigger changes to the plan.


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

Set the moderator voice, interview format, language, recruiting method, and screener questions for your study.

This step sets how participants experience the interview. It has five collapsible sections. Your choices save automatically.

***

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

> [!NOTE]
>
> The voice applies to voice and video interviews only. In chat, participants never hear the moderator.

***

## Interview format

How participants 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.

Two things limit the choice:

* **Studies with concept links can't use chat.** Concept links need a screen-capable interview, so **Chat** is disabled once the study has them.
* **Synthetic studies must use chat.** Choosing **Synthetic** as the recruiting method switches the format to chat.

Choosing **Voice** or **Video** also adds a consent screener to your [screener questions](#screener-questions-and-targeting-attributes). It tells participants the format and roughly how long the interview takes, based on your plan. It screens out anyone unwilling to take part, and for video, anyone without a webcam they're willing to use. Switching to chat removes it.

> **[Interview modes in depth](/getting-started/interview-modes)**
>
> Permissions, screen sharing, cost, and what each format is good for.

***

## Interview language

Select the language for the interview. Eighty-two are available, plus auto-detect.

English — `en`\

Afrikaans — `af`\

Albanian (Shqip) — `sq`\

Amharic (አማርኛ) — `am`\

Arabic (العربية) — `ar`\

Armenian (Հայերեն) — `hy`\

Assamese (অসমীয়া) — `as`\

Azerbaijani (Azərbaycanca) — `az`\

Basque (Euskara) — `eu`\

Bengali (বাংলা) — `bn`\

Bosnian (Bosanski) — `bs`\

Bulgarian (Български) — `bg`\

Burmese (မြန်မာ) — `my`\

Cantonese (粵語) — `yue`\

Catalan (Català) — `ca`\

Croatian (Hrvatski) — `hr`\

Czech (Čeština) — `cs`\

Danish (Dansk) — `da`\

Dutch (Nederlands) — `nl`\

Estonian (Eesti) — `et`\

Filipino — `fil`\

Finnish (Suomi) — `fi`\

French (Français) — `fr`\

Galician (Galego) — `gl`\

Georgian (ქართული) — `ka`\

German (Deutsch) — `de`\

Greek (Ελληνικά) — `el`\

Gujarati (ગુજરાતી) — `gu`

Hebrew (עברית) — `he`\

Hindi (हिन्दी) — `hi`\

Hungarian (Magyar) — `hu`\

Icelandic (Íslenska) — `is`\

Indonesian (Bahasa Indonesia) — `id`\

Inuktitut (ᐃᓄᒃᑎᑐᑦ) — `iu`\

Irish (Gaeilge) — `ga`\

Italian (Italiano) — `it`\

Japanese (日本語) — `ja`\

Javanese (Basa Jawa) — `jv`\

Kannada (ಕನ್ನಡ) — `kn`\

Kazakh (Қазақша) — `kk`\

Khmer (ភាសាខ្មែរ) — `km`\

Korean (한국어) — `ko`\

Lao (ພາສາລາວ) — `lo`\

Latvian (Latviešu) — `lv`\

Lithuanian (Lietuvių) — `lt`\

Macedonian (Македонски) — `mk`\

Malay (Bahasa Melayu) — `ms`\

Malayalam (മലയാളം) — `ml`\

Maltese (Malti) — `mt`\

Mandarin Chinese (中文) — `zh`\

Marathi (मराठी) — `mr`\

Mongolian (Монгол) — `mn`\

Nepali (नेपाली) — `ne`\

Norwegian Bokmål (Norsk bokmål) — `nb`\

Odia (ଓଡ଼ିଆ) — `or`

Pashto (پښتو) — `ps`\

Persian (فارسی) — `fa`\

Polish (Polski) — `pl`\

Portuguese (Português) — `pt`\

Punjabi (ਪੰਜਾਬੀ) — `pa`\

Romanian (Română) — `ro`\

Russian (Русский) — `ru`\

Serbian (Српски) — `sr`\

Sinhala (සිංහල) — `si`\

Slovak (Slovenčina) — `sk`\

Slovenian (Slovenščina) — `sl`\

Somali (Soomaali) — `so`\

Spanish (Español) — `es`\

Sundanese (Basa Sunda) — `su`\

Swahili (Kiswahili) — `sw`\

Swedish (Svenska) — `sv`\

Tamil (தமிழ்) — `ta`\

Telugu (తెలుగు) — `te`\

Thai (ไทย) — `th`\

Turkish (Türkçe) — `tr`\

Ukrainian (Українська) — `uk`\

Urdu (اردو) — `ur`\

Uzbek (Oʻzbekcha) — `uz`\

Vietnamese (Tiếng Việt) — `vi`\

Welsh (Cymraeg) — `cy`\

Wu Chinese (吴语) — `wuu`\

Zulu (isiZulu) — `zu`

### Pick a specific language wherever you can

**Setting a specific language localizes the whole participant experience.** The screener questions and the moderator's opening line are translated into it, as well as the conversation.

**Auto-detect (Ask Participant)** lets each participant choose their language once the conversation starts. The screener questions and the moderator's opening line stay in **English**. A participant who came for a Spanish interview meets an English screener and greeting first.

> [!WARNING]
>
> If most interviews will be in one language, **set that language**. Reserve auto-detect for mixed audiences where you can't predict the language and can accept an English screener.

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

***

## Recruiting method

How you'll reach participants. Three options:

| Option | Meaning |
| - | - |
| **BYOP** | Bring your own participants directly, or connect your own panel provider, while managing recruiting and billing yourself |
| **Panel** | Recruit participants from our network of quality respondents |
| **Synthetic** | Run chat interviews with AI respondents based on your qualifying screeners and targeting attributes |

**This choice determines your invite options after launch.** BYOP studies get a study link, email invites, embed codes, and an [external panel](/recruiting/external-panels) connection. Panel studies get panel recruiting and niche audience requests. Synthetic studies recruit from [synthetic participants](/recruiting/synthetic-respondents).

When you first choose **Synthetic**, the format switches to chat, and four targeting attributes are added to your screener to shape the AI respondents: **Age**, **Gender**, **Household Income**, and **Ethnicity**. Remove any you don't need. Synthetic isn't available for studies with concept links.

***

## 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 has one of three types:

| Type | What participants do | How you qualify them |
| - | - | - |
| **Single Select** | Pick one option | Tick **Disqualify** on any option that should screen people out |
| **Multiple Select** | Pick several options | Set a rule on each option: **Must Select**, **May Select**, or **Reject** |
| **Text Input** | Type an answer | Doesn't screen anyone out. Set what it **Accepts**: **Any text** or **Numbers only**, with an optional allowed input range for numbers |

On multiple-select questions, **Must Select** means a participant has to choose that option to qualify, **May Select** means choosing it is fine either way, and **Reject** screens out anyone who chooses it. Click **Add "Other"** to add an Other option, and tick **Allow freeform** so participants can type their own answer.

To qualify people on a number, use a select question with options. A number range on a Text Input only limits what participants can enter.

Standard attributes follow the same rules. Most are option-based; **Zip Code** is a text input where you list **Allowed ZIP codes** and **Disallowed ZIP codes** (comma-separated; leave the allowed list empty to accept all).

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

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

* When enabled, participants see that question's answer options in a fresh random order each time they open the screener. Which options qualify or disqualify is unchanged.
* 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.

***

## Continue

Review your selections and click **Save & Continue**.

***

## Frequently asked questions

> **Can I add screener questions later?**
>
> Yes, either here or by asking Charles in step 2. He'll use standard qualifications where they fit.

> **What if a participant's device doesn't support the format?**
>
> They see an error before the interview starts. Voice and video need a working microphone, and video needs a camera that the participant allows access to. Chat works anywhere.

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

***

## Next steps

> **[Step 5: Test Conversation](/creating-a-study/test-conversation)**
>
> Take the interview yourself or watch an AI respondent take it.

> **[Recruiting overview](/recruiting/overview)**
>
> How to choose a recruiting method, and what each costs.


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

Take your interview yourself or watch an AI respondent take it, then fix problems before real participants arrive.

Experience your study from a participant's perspective before launching, and check that the conversation flows naturally and covers what you need.

Take the interview yourself, or watch an AI respondent take it. Either way it's the moderator you configured, running your research plan. Testing is optional, but a ten-minute test catches problems while they're cheap to fix.

**Test conversations are free and don't count against your usage limits**, for both **Test it yourself** and **Test with AI**. Test as many times as you need.

***

## Run a test

### Start the test

Choose one of two options:

| Option | What happens |
| - | - |
| **Test it yourself** | Talk to your moderator as a participant would. The interview opens in a new tab, and you're brought back here when it ends. |
| **Test with AI** | Watch an AI respondent take the interview live, in a chat transcript on this screen. |

> [!NOTE]
>
> For studies with concept links, use **Test it yourself**. **Test with AI** isn't available for them. In the [sandbox](/api-reference/staging-quickstart), only **Test with AI** is available.

### During the test

Whichever option you choose, the conversation follows the full participant flow:

1. The moderator greets the participant and introduces the study
2. It asks questions from your research plan
3. It probes deeper based on the responses
4. The conversation wraps up

**Tips for testing it yourself:**

* **Respond naturally:** answer as a real participant would.
* **Vary your answers:** give some detailed answers and some brief ones.
* **Test edge cases:** see what happens when you give an unexpected answer.
* **Finish the conversation:** experience the entire flow.

### Rate the test

When the conversation ends, or you end it early, rate it:

* Click **View call** to open the test call's details once it's ready.
* Click **Good** if it went well. You move straight on to Ready to Launch.
* Click **Needs Work** if something was off. Describe the problem in the text box, then choose one:
  * **Send feedback to the Team**: sends your feedback to us and moves you on to step 6.
  * **Use feedback to improve your Study**: takes you back to [Customize Plan](/creating-a-study/customize-plan) and sends your feedback to Charles, who revises the plan.
* Click **Test Again** to run another test.

***

## Fix problems yourself

Besides **Needs Work**, you can change the plan directly:

* **Small changes to wording or flow:** click **Back** twice to return to [Review Goals](/creating-a-study/review-goals), edit the plan, then go through the steps again to re-test.
* **Significant restructuring:** click **Back** to return to [Customize Plan](/creating-a-study/customize-plan), tell Charles what you need, let him regenerate the plan, then review and test again.

***

## Continue to launch

Click **Save & Continue**. You can do this without running a test, or with minor issues noted, but we recommend at least one test first. Otherwise your first real participant is your first test.

***

## Frequently asked questions

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

> **Can other team members test the conversation?**
>
> Yes. Anyone with access to the study can run a test conversation.

> **How long does a test conversation take?**
>
> As long as a real interview, usually 10–20 minutes depending on your research plan. You can end early if you've seen enough.

> **The moderator responded differently than I expected. Is that a problem?**
>
> Not necessarily. It adapts to each conversation, so no two run identically. Adjust your research plan if it *consistently* misses an important probe or heads somewhere you don't want.

***

## Next steps

> **[Step 6: Ready to Launch](/creating-a-study/ready-to-launch)**
>
> Review your full configuration and launch.

> **[Calls & Transcripts](/results/calls-and-transcripts)**
>
> Review completed interviews and their transcripts.


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

Compare chat, voice, and video interviews by what they capture, the permissions they need, and their cost, then pick one.

Every study runs in one of three formats: chat, voice, or video. You choose the format in [Setup Interview](/creating-a-study/setup-interview), and it applies to every interview in the study. Participants can't change it.

***

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

This is the lowest-friction option. There's nothing to allow or 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]
>
> **Video interviews require the camera.** Participants can't start until they allow camera access in their browser. Anyone who won't or can't turn their camera on can't take part.

***

## 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**. Participants decide on permissions up front, and consent is handled before any recording begins.

Voice and video studies also get a consent screener added automatically. It tells participants the format, that the moderator is AI, and roughly how long the interview takes. Anyone unwilling to take part is screened out, and for video, so is anyone without a webcam they're willing to use.

If a participant's device or browser can't support the format, or they block the permission, they see an error before the conversation starts.

***

## Cost

Interviews are billed in credits, and the format sets the multiplier: 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.

> **[Billing and credits](/resources/billing-and-credits)**
>
> What a credit costs on each plan.

***

## When a format isn't available

Two study settings narrow your choice:

* **Concept links rule out chat.** A study with concept links needs a screen-capable interview, so **Chat** is disabled. Use voice or video.
* **Synthetic respondents are chat only.** Choosing [Synthetic](/recruiting/synthetic-respondents) as the recruiting method switches the study to chat.

***

## Choosing a format

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 is part of the finding, and accept that requiring the camera will turn some participants away. If you only need to see their screen, voice with screen sharing gets you there.

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

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

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

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

***

## Next steps

> **[Study Types](/study-types/overview)**
>
> Pick between an interview, a concept test, and a prototype test.

> **[Setup Interview](/creating-a-study/setup-interview)**
>
> Where you set the format, voice, and language.


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

Learn the core concepts behind User Intuition: studies, interviews, Charles, the moderator, reports, and credits.

These are the building blocks of User Intuition. Read this page once before you create 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, with no stimulus |
| **Concept Test** | Reactions to an image or video |
| **Prototype Test** | Watching people work through a prototype or live site |

> **[Study types in depth](/study-types/overview)**
>
> What each one does and when to reach for it.

***

## 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 for the whole study when you build it.

> **[Interview modes](/getting-started/interview-modes)**
>
> How chat, voice, and video differ in permissions, screen sharing, and cost.

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

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 three recruiting methods:

| Method | How you reach participants |
| - | - |
| **BYOP** (bring your own participants) | Share a study link · Send email invites · Embed a widget · [Connect your own panel provider](/recruiting/external-panels) |
| **Panel** | Recruit from our panel · Recruit a niche audience |
| **Synthetic** | Run chat interviews with [AI respondents](/recruiting/synthetic-respondents) built from your screeners and targeting attributes |

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

> **[Recruiting participants](/recruiting/overview)**
>
> How to choose, and what each method costs.

***

## Reports

**Reports** synthesize your interviews into findings, evidence coverage, participant responses and profiles, and recommended next steps. Generate one once you have usable interviews, and regenerate it as more come in. See [Reports](/results/reports).

***

## 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. It's available on the Pro plan.

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 sync into it.

> **[Intelligence Hub guide](/results/intelligence-hub)**
>
> Sync sources, ask questions, and generate outputs.

***

## Key metrics

You'll see these on every study dashboard:

| Metric | Meaning |
| - | - |
| **Responses** | Completed interviews |
| **Avg Length** | Average interview duration |
| **Quality Interviews** | Responses that meet the quality bar for reports |
| **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.

> **[Billing and credits](/resources/billing-and-credits)**
>
> Plans, credit pricing, and panel costs.

***

## Next steps

> **[Interview Modes](/getting-started/interview-modes)**
>
> How chat, voice, and video differ.

> **[Creating a Study](/creating-a-study/overview)**
>
> The full setup guide, step by step.


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

Create, test, and launch your first research study in about 15 minutes.

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

## 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 or synthetic respondents

## Launch your first study

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

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

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

**3. Review Goals**

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

**4. Setup Interview**

Configure five things:

* **Moderator voice**: preview the options and pick one
* **Interview format**: Chat, Voice, or Video
* **Interview language**: 82 languages, or auto-detect and let the participant pick
* **Recruiting method**: BYOP (bring your own participants), Panel, or [Synthetic](/recruiting/synthetic-respondents) (AI respondents, chat only). This determines your invite options later.
* **Screener questions**: qualify participants before they reach the interview

Click **Save & Continue**.

**5. Test Conversation**

This step is recommended: a test run catches problems before real participants hit them. Test conversations are free and don't consume credits.

* Choose **Test it yourself** to take the interview as a participant would, or **Test with AI** to watch an AI respondent take it live
* When it ends, click **Good** to move on, or **Needs Work** to send feedback to our team or back to Charles to improve the plan
* Click **Test Again** to run another

**6. Ready to Launch**

Review your study configuration, screener questions, and research plan, then click **Save and Invite Participants**.

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

**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 |
| - | - |
| **BYOP** | Copy the study link · Send email invites · Copy the embed code · Bring your own panel |
| **Panel** | Recruit from our panel · Recruit a niche audience |
| **Synthetic** | Recruit from synthetic participants |

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

## Next steps

> **[Key Concepts](/getting-started/key-concepts)**
>
> How studies, interviews, the moderator, and the Intelligence Hub fit together.

> **[Creating a Study](/creating-a-study/overview)**
>
> Detail on each setup step.


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

Connect HubSpot to sync your CRM contacts and lists, then invite them to any BYOP study with Send Email Invites.

Connect HubSpot to use your CRM contacts as a source for [email invites](/recruiting/invite-customers). Your HubSpot contacts and lists sync into User Intuition and appear under **Invite Participants** → **Send Email Invites** on every BYOP study.

***

## Install the app

**1. Open the listing**

Find **User Intuition** in the HubSpot Marketplace (or use the install link from your team) and click **Install**.

**2. Choose your portal**

Select the HubSpot account to connect. You must be an admin of that portal.

**3. Authorize the requested scopes**

The app requests read access to contacts, companies, and deals, plus permission to show its card on CRM records. Click **Connect app**.

**4. Land in User Intuition**

You're signed in to User Intuition and land on **Create Study**. If your HubSpot email already has a User Intuition account, that account is linked. Otherwise a new one is created.

**5. Run the first sync**

A default **All Contacts** segment is created automatically. Start the first sync from the User Intuition card on any HubSpot record or from the app settings page.

Each portal has one connection. Reinstalling on the same portal updates it rather than creating a duplicate.

***

## Invite HubSpot contacts to a study

**1. Open Send Email Invites**

On the study's **Invites** tab, click **Invite Participants** → **Send Email Invites**.

**2. Select the HubSpot connection**

Click the HubSpot card at the top of the panel. It shows the sync status and how many contacts are available.

**3. Pick contacts or segments**

Use the **Contacts** tab to search by name, email, or phone, or the **Segments** tab to pick whole segments (each shows its customer count).

**4. Send**

Click **Send N Invitations** (or **Send to N Segments**). Contacts without an email address are skipped, and anyone already invited to this study isn't invited again.

**Send Email Invites** is available on BYOP studies that aren't paused. See [Send Email Invites](/recruiting/invite-customers) for the full workflow.

***

## What you see in HubSpot

### CRM record cards

A **User Intuition** card appears on contact, company, and deal records in HubSpot. It shows:

* The portal's sync state (idle, syncing, completed, or error)
* How many contacts have been imported
* A button to start a sync
* A link to your User Intuition workspace

To invite the people on a contact, company, or deal, pick them in a study's **Send Email Invites** panel.

### App settings page

Open the User Intuition app from **Settings** → **Integrations** → **Connected apps** in HubSpot. Use this page to see the portal's sync status, start a full sync, or open your User Intuition workspace.

***

## What syncs

Data flows one way, from HubSpot into User Intuition. Interview data isn't written back to HubSpot.

| HubSpot object | Becomes in User Intuition | Notes |
| - | - | - |
| Contact | Contact | Email, name, and phone are mapped; other properties are stored with the contact. |
| HubSpot list (where applicable) | Segment | Pick from the **Segments** tab when sending invites. |
| — | **All Contacts** segment | Created on connection so you can invite every synced contact at once. |

Companies and deals aren't imported as separate records. You invite their associated contacts.

### Start a sync

You can start a sync from:

* The User Intuition card on any HubSpot record
* The User Intuition settings page in HubSpot
* The re-sync button on the HubSpot connection card in User Intuition's invite panel (shown once the status is **COMPLETE** or **FAILED**)

A sync updates existing contacts in place rather than duplicating them. The first sync on a large portal can take several minutes.

### Automatic updates

New contacts and contact property changes in HubSpot flow into User Intuition automatically. Changes to properties outside those events are picked up on the next full sync, so run one occasionally as a backstop.

***

## Uninstall the app

Uninstalling the app from HubSpot disconnects the portal and stops updates from flowing into User Intuition. Studies, invites, and interviews you've already run stay in your workspace.

Reconnecting later starts fresh and re-runs the full sync. On a large portal, plan it for a quiet window.

***

## Pitfalls and known limits

> **Admin install only**
>
> Installing requires HubSpot admin permissions on the portal. If install fails, check the installer's role.

> **One portal per account**
>
> A User Intuition account links to one HubSpot portal. Connecting a different portal replaces the existing link.

***

## Next steps

> **[Shopify](/integrations/shopify)**
>
> Invite your store's customers the same way

> **[Send email invites](/recruiting/invite-customers)**
>
> Manual entry, contacts, segments, and tracking


# Shopify
Source: https://docs.userintuition.ai/integrations/shopify

Connect your Shopify store to sync customers and segments, then invite them to any BYOP study with Send Email Invites.

Connect Shopify to use your store's customers as a source for [email invites](/recruiting/invite-customers). Customers and customer segments sync into User Intuition and appear under **Invite Participants** → **Send Email Invites** on every BYOP study.

***

## Install the app

Installing the app creates your User Intuition account automatically. You don't need to sign up first.

**1. Install from the Shopify App Store**

Find the User Intuition listing and install it.

**2. Approve the requested scopes**

The app requests read-only access to customers and orders.

**3. Open the app in your Admin**

Shopify redirects you to the app inside your Admin. Your User Intuition account is created from your shop's email on file.

**4. Let the initial sync run**

Customers and segments start syncing right away. You can keep working while it completes.

> [!NOTE]
>
> If you follow a link from the Shopify app to User Intuition and aren't signed in, sign in or sign up as usual. The shop connects to your account once you're signed in.

***

## Invite Shopify customers to a study

**1. Open Send Email Invites**

On the study's **Invites** tab, click **Invite Participants** → **Send Email Invites**.

**2. Select the Shopify connection**

Click the Shopify card at the top of the panel. It shows the sync status and how many contacts are available.

**3. Pick customers or segments**

Use the **Contacts** tab to search customers by name, email, or phone, or the **Segments** tab to pick whole Shopify segments. Each segment shows its customer count.

**4. Send**

Click **Send N Invitations** (or **Send to N Segments**). Customers without an email address are skipped, and anyone already invited to the study isn't invited again.

See [Send Email Invites](/recruiting/invite-customers) for the full workflow.

***

## The app in your Shopify Admin

The app appears in your Shopify Admin under **Apps** and opens inside the Admin. From there you can:

* See sync status and how many customers have been imported
* Browse your studies and their status
* Create a new study
* Open your User Intuition workspace for everything else

***

## What syncs

Customers (with email, phone, orders, and tags) and customer segments sync from Shopify into User Intuition on install and whenever you start a sync. A default **All Customers** segment is created on first connection.

Large stores sync in batches, so you'll see the customer count climb in the app as it runs. Re-running a sync is safe. It refreshes existing customers and segments rather than creating duplicates.

***

## GDPR requests

User Intuition handles Shopify's compliance requests automatically:

* **Customer data request:** acknowledged so you can fulfill it. Imported customer data lives in your User Intuition account.
* **Customer redaction:** that customer's imported record is removed.
* **Shop redaction:** all imported segments, customers, and shop data are removed.

Shopify sends shop redaction about 48 hours after uninstall. To remove a customer's data immediately, trigger redaction from your Shopify Admin.

***

## Disconnect and uninstall

To disconnect, uninstall the app from your Shopify Admin's **Apps** page. The connection and the shop's imported customers and segments are removed right away. Shopify's shop redaction request about 48 hours later removes anything that remains.

> [!WARNING]
>
> If your User Intuition account was created through the Shopify app (or connected to Shopify within 30 minutes of signing up), uninstalling deletes the whole account, including studies, interviews, and your login. If the account existed before you connected Shopify, only the imported customers and segments are removed. Export anything you need first.

***

## Common setup pitfalls

> **Shop email missing on Shopify**
>
> Your User Intuition account is created from the shop's contact email. If it's blank, set it under **Settings → Store details** before opening the app.

> **Very large customer bases**
>
> The initial sync for a very large store can take several minutes. Let it run rather than refreshing.

> **No segments visible after install**
>
> If you haven't created any Shopify segments, only **All Customers** appears. Create segments in **Customers → Segments** in Shopify and re-run the sync.

> **Reinstalling on the same shop**
>
> Reinstalling reconnects the shop and re-runs the sync. If your account was created through the Shopify app, uninstalling deleted it, so you start with a fresh account.

***

## Next steps

> **[Stripe](/integrations/stripe)**
>
> Invite your Stripe customers and subscribers the same way

> **[Send email invites](/recruiting/invite-customers)**
>
> Manual entry, contacts, segments, and tracking


# Stripe
Source: https://docs.userintuition.ai/integrations/stripe

Connect Stripe to sync customers and cohorts, then invite them to any BYOP study with Send Email Invites.

Connect Stripe to use your customers as a source for [email invites](/recruiting/invite-customers). Customers and customer cohorts sync into User Intuition and appear under **Invite Participants** → **Send Email Invites** on every BYOP study. The integration runs as a Stripe App alongside your Stripe Dashboard.

***

## Connect Stripe

You connect from the Stripe Dashboard, not from inside User Intuition.

**1. Install the User Intuition Stripe app**

In the Stripe Dashboard, install the User Intuition app and approve the access Stripe shows you.

**2. Continue to User Intuition**

Follow the app's link to User Intuition.

**3. Sign in or sign up**

Sign in to your User Intuition account, or create one. The Stripe account connects automatically once you're signed in.

**4. Wait for the initial sync**

A default **All Customers** segment is created and your customers and cohorts start syncing in the background.

Each User Intuition account links to one Stripe account. Connecting a different Stripe account replaces the existing link.

***

## Invite Stripe customers to a study

**1. Open Send Email Invites**

On the study's **Invites** tab, click **Invite Participants** → **Send Email Invites**.

**2. Select the Stripe connection**

Click the Stripe card at the top of the panel. It shows the connection status and how many contacts are available.

**3. Pick a segment or individual customers**

On the **Segments** tab, check the Stripe segments you want. Each shows its customer count. To invite specific people, use the **Contacts** tab and search by name, email, or phone.

**4. Send**

Click **Send to N Segments** (or **Send N Invitations**). Every customer with an email address gets an invite. Customers without an email are skipped.

Customers who already have an invite for the study aren't invited again, so re-sending to a segment is safe. See [Send Email Invites](/recruiting/invite-customers) for the full workflow.

***

## What syncs

| Stripe object | Becomes in User Intuition | Notes |
| - | - | - |
| Customer | Participant | Email, name, phone, currency, and Stripe metadata. |
| Subscription | Participant data | Subscription status and plan are stored on the customer's participant record. |
| Customer cohorts | Segments | For example, "All Customers", "Active Subscribers", or per-product groupings. |

After the initial sync, new customers, customer updates, and subscription changes in Stripe flow in automatically. Card numbers, payment methods, and other sensitive payment data are never synced.

***

## Connection status

The Stripe connection card in the invite panel shows a status badge and the number of contacts available.

| Status | Meaning |
| - | - |
| **PENDING** | Connected, but the first sync hasn't started. |
| **SYNCING** | Customers and cohorts are being fetched. |
| **SEGMENTS\_SYNCED** | Cohorts are imported; customers are still syncing. |
| **COMPLETE** | The initial sync finished. Changes in Stripe now flow in automatically. |
| **FAILED** | The sync didn't finish. Use the re-sync button on the card to try again. |

The re-sync button appears on the card once the status is **COMPLETE** or **FAILED**.

***

## Disconnect

To disconnect, uninstall the User Intuition app from the **Stripe Dashboard**. New data stops flowing in. Participants and segments already imported stay available in the invite panel.

If you reconnect later, the initial sync runs again. Existing participants are matched to their Stripe customer and updated, not duplicated.

***

## Troubleshooting

> **No customers appearing**
>
> Check the status badge on the Stripe connection card. **syncing** means the initial sync is still running. Large customer lists take longer.

> **Stale data in segments**
>
> If a recent Stripe change isn't showing, confirm the Stripe app is still installed and that webhook delivery is healthy in the Stripe Dashboard.

> **Customers without email**
>
> Customers without an email sync but can't be invited. Add an email in Stripe and the next sync picks it up.

> **Switching Stripe accounts**
>
> Uninstall the app from the old Stripe account first, then connect the new one from its Stripe Dashboard.

***

## Next steps

> **[Embed the AI widget](/recruiting/embed-widget)**
>
> Catch customers inside your product instead

> **[Send email invites](/recruiting/invite-customers)**
>
> Manual entry, contacts, segments, and tracking


# Welcome to User Intuition
Source: https://docs.userintuition.ai/introduction/welcome

Learn what User Intuition does, which study types you can run, and where to start.

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 is transcribed and analyzed, and you can build what you learn into 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.

### Insight that compounds

On the Pro plan, sync your studies into your organization's Intelligence Hub and ask questions across all of them at once. What used to be buried in slide decks and people's heads becomes searchable, and each study you add makes the last ones more useful.

***

## Get help

Use the search bar at the top of any page, or email **[support@userintuition.ai](mailto:support@userintuition.ai)**. See [Support](/resources/support) for more.

***

## Next steps

> **[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.


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

The Study Dashboard is where you watch progress, invite participants, and reach your results. You land here after launch. To come back later, click **Dashboard** in the left navigation and pick your study. The dashboard updates live as participants finish, so you don't need to reload.

***

## Key metrics

Four cards across the top:

| Metric | Description |
| - | - |
| **Responses** | Completed interviews |
| **Avg Length** | Average duration of completed conversations |
| **Quality Interviews** | Interviews good enough to go into your report |
| **Study Progress** | Responses collected against your target |

### Understanding quality

An interview counts toward **Quality Interviews** based on how long it ran, how substantive the answers were, and how much of your research plan it covered. Interviews that fall short are still recorded and readable in the **Calls** tab.

### Adjusting your target

On studies where you bring your own participants, click the **Study Progress** card to open **Adjust Target**. Enter how many interviews you want going forward and choose a frequency:

| Frequency | What it means |
| - | - |
| **One-time (total)** | Recruit this many interviews once |
| **Weekly** / **Monthly** / **Quarterly** | Recruit this many interviews every period |

With a recurring target, the card shows progress for the current period (for example, "4 / 10 interviews this month") and the date it resets. Once a study stops collecting, the card shows how many responses came in against how many you requested — for example, "18 responses collected (20 requested)."

Panel study targets are set when you recruit from the panel, so the card isn't clickable there.

***

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

***

## Dashboard 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** the invitation or copy that participant's invite link. Both are unavailable while the study is paused.

### Calls

Every completed interview, with its quality rating and end reason. Click a row for the transcript, attributes (screener answers), and summary. See [Calls & transcripts](/results/calls-and-transcripts).

### Reports

Synthesis across all completed interviews in the study. See [Reports](/results/reports).

***

## 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** / **Copy Button Embed Code** — put it in your product | **Recruit a Niche Audience** — request a quote for hard-to-reach people |
| **Bring Your Own Panel** — connect an external panel provider | |

Synthetic studies show **Recruit from synthetic participants** instead.

The menu stays available while a study is paused, but **Send Email Invites** is disabled until you resume it. To compare methods and costs, see [Recruiting participants](/recruiting/overview).

***

## Managing the study

The **Actions** menu in the top right handles everything else: editing, duplicating, pausing, incentives, and deletion. See [Study actions](/managing-your-study/study-actions).

***

## Tips while your study runs

* **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.
* **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.
* **Track your response rate.** Compare invites sent against calls completed. A low rate usually means the invitation, not the study.
* **Let it run.** Changing questions mid-study makes early and late responses hard to compare.

***

## Next steps

> **[Study actions](/managing-your-study/study-actions)**
>
> Edit, duplicate, pause, enable incentives, or delete a study.

> **[Calls & transcripts](/results/calls-and-transcripts)**
>
> Review individual interviews in detail.


# Study Actions
Source: https://docs.userintuition.ai/managing-your-study/study-actions

Edit, duplicate, pause, delete, or add incentives to a study from the dashboard Actions menu, and see what you're charged for.

The **Actions** menu in the top right of your study dashboard holds everything you can do to a study after it's live.

Most actions work the same on every study. Incentives and charges depend on whether you're running a **panel** study or bringing your **own participants**.

| Action | Panel studies | Your own participants |
| - | :-: | :-: |
| View Study | ✓ | ✓ |
| Edit Study | ✓ | ✓ |
| Duplicate Study | ✓ | ✓ |
| Pause / Resume Study | ✓ | ✓ |
| Delete Study | ✓ | ✓ |
| Enable Incentives | — | ✓ |

***

## Available on every study

### View Study

Opens the complete configuration — research plan, moderator voice, format, language, and screener questions — read-only.

Use it to check what you asked before interpreting a result, or to show the design to a colleague.

### Edit Study

Reopens the setup flow so you can change the research plan, moderator, format, or screeners.

> [!WARNING]
>
> **Editing a study that's already collecting has a cost.** If you change questions or flow partway through, early and late responses aren't directly comparable.

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

For substantial changes after collecting responses, **duplicate the study and edit the copy** instead. The first set of responses stays intact.

> [!NOTE]
>
> Some studies get a mid-study review that suggests up to two questions to add. Accepting it adds them to the live study plan for future interviews. See [Mid-study review](/results/reports#mid-study-review).

### Duplicate Study

Copies the research plan, moderator settings, and screeners into a new study, without any 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 a **Study Paused** message instead of starting an interview
* **Send Email Invites** is disabled, and you can't resend invites or copy their links. The rest of the **Invite Participants** menu stays available
* Test conversations still work, so you can keep checking the study yourself
* Everything already collected stays exactly where it is

**Resume Study** reopens the same links, so you don't need to redistribute anything.

A **Complete** study (one that reached its target) can't be paused.

### Delete Study

Permanently removes the study and everything attached to it: all interviews, transcripts, recordings, reports, and participant records.

> [!WARNING]
>
> **Deletion cannot be undone.** Save anything you need first — **Download calls (CSV)** from the Calls tab for transcripts, or **Print Report** from the Reports tab.

If you might collect more later, **pause** instead. If you want the findings to outlive the study, **sync it to the Intelligence Hub** first.

***

## Studies where you bring your own participants

### Enable Incentives

Pay your participants for completing an interview. Panel studies don't have this option: User Intuition sets and pays panel incentives as part of the per-participant cost.

**1. Open Enable Incentives**

From the **Actions** menu. Once incentives are on, the menu item reads **Incentives: \$X** and opens **Edit Incentives** instead.

**2. Set the amount**

Enter a reward per participant, between **\$5 and \$500**. It's debited from your wallet when a reward is actually sent.

**3. 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.

Rewards are only offered for interviews rated **Excellent** or **Good**, and never for test invites.

To turn incentives off, open **Edit Incentives** and click **Disable**.

> [!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."

***

## Panel studies

### 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 halts a fielding panel and keeps its recruitment progress and reward hold. Resuming restarts the same panel.

**Stopping** is final for the current panel. It closes recruitment, settles completed rewards, and releases any unused hold. When you edit a fielding panel, choose **Pause & Edit** to continue it 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 |

**Fair** differs because of who chose the participant. On panel studies we recruited them, so a thin conversation is on us. On your own studies you control who gets the link.

The **\$30 per-participant** panel cost follows the same rule: you're billed only for Excellent and Good completes. See [Billing and credits](/resources/billing-and-credits).

***

## Frequently asked questions

> **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 your dataset can contain responses collected under different configurations.

> **Who can perform these actions?**
>
> Anyone with permission to manage the study. **View Study** is available to everyone with access.

***

## Next steps

> **[Calls & transcripts](/results/calls-and-transcripts)**
>
> Review each interview, its quality rating, and rewards.

> **[Billing & credits](/resources/billing-and-credits)**
>
> See how interviews and incentives are charged.


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

Users can belong to multiple organizations. Call `list_organizations` to find accessible workspaces and pass `organization_id` on subsequent tools to select one for reads, changes, and billing. Ordinary users can select active memberships in the current app; platform administrators have app-wide access. API-key scopes and spend caps apply. See [organization selection](/api-reference/organizations).

`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 connector
Source: https://docs.userintuition.ai/mcp-server/claude-directory

Connect Claude to the full User Intuition research workflow, from study design and recruitment through interview evidence.

The User Intuition connector in Claude's directory uses the full MCP server. Sign in with your User Intuition account through OAuth to work with studies, participants, fielding, reports, and source-linked interview evidence. Available actions depend on your account permissions and the scopes granted during sign-in.

## Connect

Find **User Intuition Research** in Claude's connector directory and sign in. If you add the remote server manually, use:

```text theme={null}
https://mcp.userintuition.ai/mcp
```

This endpoint exposes all 79 MCP tools. The separate `/directory/mcp` URL is an optional eight-tool, read-only profile for custom clients; it is not the URL used by the Claude directory listing.

## What Claude can do

* Create and customize studies, then show the saved plan for your review.
* Estimate Panel recruitment cost and timing before launch.
* Launch paid Panel recruitment only after a separate human approval. A launch can consume credits or place a card hold.
* Monitor fielding, inspect interviews, and review reports with source references.
* Search existing research, run analysis, and produce research deliverables.
* Manage participants, rewards, webhooks, and other workspace operations when your account permits them.

For the full catalog and required inputs, see the [MCP tool reference](/mcp-server/tools/studies). The [study-creation playbook](/mcp-server/guides/playbook) explains the approval steps for studies, recruitment, rewards, and destructive actions.

## Try it

* “List my studies that have reports.”
* “What did participants say about onboarding in this study? Show the interviews behind the findings.”
* “Create a draft study for an audience I choose, then show me the saved plan and a Panel estimate before any launch.”

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

Prefer `queue_customize_study` with the user's natural-language research brief, poll `get_customize_study_job` until it succeeds, and inspect its `result`. Use synchronous `customize_study` for native concept images. 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

Each customization call represents one conversation turn; poll queued turns before continuing. 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. Call `launch_panel` with the estimate and the same country for a preview. In App-capable clients, the person approves with the App button. `approve_panel_launch` is hidden from the model. Without Apps, show the saved plan and complete quote, wait for explicit human confirmation, then submit the returned `chat_approval_nonce` with `human_confirmed=true`. Never invent confirmation or a nonce. Obtain a fresh estimate and approval if 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.

## A tool is unavailable

Confirm that the client connects to the intended [MCP profile](/mcp-server/overview). The full endpoint exposes 79 tools; core, read-only, compact, and directory profiles offer different subsets. Check the [tool reference](/mcp-server/tools/studies) for the tool name and inputs.

Hosted clients discover tools through the MCP endpoint. Local stdio clients launch the server with:

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

## 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: **79 tools on every transport**, covering the versioned public API plus account context, catalogs, interview usage, and study review apps.

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

> **[Connect the MCP server](/mcp-server/quickstart)**
>
> Configure Claude, Cursor, VS Code, or ChatGPT and verify the connection.

> **[Install a research Skill](/skills/overview)**
>
> Teach your agent a repeatable study-creation or analysis workflow.

## One surface on every transport

The [Claude directory connector](/mcp-server/claude-directory) uses the full `/mcp` endpoint.

* **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 79 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` (61 tools). It omits webhook, feasibility, and external-panel administration; organization selection is included. For existing research without write actions, connect to `https://mcp.userintuition.ai/read-only/mcp` (31 tools). The `https://mcp.userintuition.ai/compact/mcp` profile keeps the research workflow and groups less common webhook, feasibility, and external-panel operations into 70 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 79 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 for MCP server v0.17.1:

| Profile | Tools | Payload bytes | Approx. tokens |
| - | -: | -: | -: |
| Full | 79 | 165,137 | 41,284 |
| Core | 61 | 130,834 | 32,708 |
| Read-only | 31 | 76,745 | 19,186 |
| Compact | 70 | 150,446 | 37,612 |
| Directory | 8 | 31,440 | 7,860 |

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 | What it covers |
| - | - |
| Account | Effective workspace, payment readiness, and platform-admin organization search |
| Studies | Create, customize, review, estimate, launch, pause, stop, report on, search, and answer questions across studies |
| Research sessions | Manage sources, run analysis, and create or edit research outputs |
| External panels | Configure a customer-supplied panel bridge for a BYOP study |
| Participants | Create and manage BYOP invitations and rewards |
| Interviews | Read or delete interviews and inspect usage |
| Panel feasibility | Specialist feasibility review |
| Webhooks | Create, inspect, test, and remove event subscriptions |
| Configuration & catalogs | 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.


# Profiles and prompts
Source: https://docs.userintuition.ai/mcp-server/profiles-and-prompts

Choose a tool catalog and use reusable research prompts.

Connect to the endpoint whose catalog fits your workflow. Each endpoint has its own OAuth authorization.

| Profile | Endpoint | Tools |
| - | - | -: |
| Full | `https://mcp.userintuition.ai/mcp` | 79 |
| Core | `https://mcp.userintuition.ai/core/mcp` | 61 |
| Read-only | `https://mcp.userintuition.ai/read-only/mcp` | 31 |
| Compact | `https://mcp.userintuition.ai/compact/mcp` | 70 |
| Directory | `https://mcp.userintuition.ai/directory/mcp` | 8 |

## Compact operations

Compact groups 15 webhook, feasibility, and external-panel operations into six tools. Set `operation` to the desired operation name and provide its inputs alongside `operation`. Read operations are separate from writes; grouped writes use conservative destructive annotations.

* `inspect_webhooks`: `list_webhooks`, `get_webhook`, or `list_webhook_deliveries`.
* `manage_webhook`: `create_webhook`, `rotate_webhook_secret`, or `test_webhook`.
* `remove_webhook`: choose `delete_webhook_by_id` and provide the webhook ID.
* `inspect_feasibility`: `list_feasibility_requests` or `get_feasibility_request`.
* `manage_feasibility`: `submit_feasibility_request` or `cancel_feasibility_request`.
* `manage_external_panel`: `configure_external_panel`, `regenerate_external_panel_token`, or `delete_external_panel`.

```json theme={null}
{"tool":"inspect_webhooks","arguments":{"operation":"list_webhooks"}}
```

## Research prompts

Clients supporting MCP prompts can discover these with `prompts/list` and request them with `prompts/get`:

* `plan_research_study`: guide a research brief through draft creation, customization, persisted-plan review, and human approval.
* `review_fielding`: inspect study progress, quality, and estimated finish, then decide whether attention is needed.

Prompts supply workflow guidance. They do not perform actions or authorize spending. Follow the queued planning and approval workflow in the [study-creation playbook](/mcp-server/guides/playbook).

## FAQ

### Can I launch a panel from the CLI?

Use an MCP client for paid panel launch and human approval. The CLI supports estimates, study management, and progress inspection through its direct tool inventory.

### Do prompts authorize actions?

No. Prompts guide the workflow; plan review and paid-action confirmation come from the person.

## Next steps

Use the [quickstart](/mcp-server/quickstart) to authenticate, or inspect [account context](/mcp-server/tools/account-context) to select an organization.


# 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 61-tool research workflow, `https://mcp.userintuition.ai/read-only/mcp` for 31 read-only tools, or `https://mcp.userintuition.ai/compact/mcp` for 70 tools with grouped administrative operations. Authorize each endpoint separately. The full URL above exposes all 79 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

**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)

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

**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"
      }
    }
  }
}
```

**Cursor**

Add the same `mcpServers` entry to `.cursor/mcp.json`, replace the example key, and restart Cursor.

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

**VS Code**

Add the server command and environment variable under `"mcp.servers"` in `.vscode/settings.json`, then reload the window.

## 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 79 tools, including `queue_customize_study`, `review_study`, `search_research`, and `answer_research`.

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

> **[Install the Skill](/skills/create-study-from-brief)**
>
> Add the reusable study-design workflow to your AI client.

> **[Read the MCP playbook](/mcp-server/guides/playbook)**
>
> Understand the workflow rules already advertised by the server.

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. MCP text `content` also contains the full JSON for model tool chaining. `view_research_answer` supplies readable answer text and quotation labels alongside its structured data.

## 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` | Search accessible organizations 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. Without an explicit selection, an API key uses its default organization and a session uses its active account context.

Users can belong to multiple organizations. Use `list_organizations` with optional `search`, then pass `organization_id` to `get_account` and subsequent tools. Results are limited to active memberships for ordinary users; platform administrators have app-wide discovery. Search happens before pagination. The `owners` list can contain multiple active owners or be empty. Confirm the organization with the human before a consequential action. The selected workspace supplies billing and audit context; API-key scopes and spend caps apply.


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


# Intelligence Hub
Source: https://docs.userintuition.ai/mcp-server/tools/intelligence-hub

Manage research sessions, chat with verified evidence, and generate or edit Studio outputs.

> [!NOTE]
>
> All Hub tools use `/api/public/v1/intelligence-hub/*`, including analysis and export polling.

Use the organization-scoped public Hub API through these tools. Platform admins can
add studies from other organizations within the same application to a session in
their own selected workspace. Create a session,
add/sync studies or upload sources, then chat or generate outputs. File Search
retrieves relevant evidence; reports and PowerPoints reuse saved findings. You do
not need to start exhaustive analysis before creating an output.

| Tool | Description |
| - | - |
| `create_research_session` | Create a Hub session with an idempotency key |
| `rename_research_session` | Rename a Hub session |
| `delete_research_session` | Delete a Hub session |
| `sync_research_study` | Add or refresh one study in a session |
| `remove_research_study` | Remove a study source from a session |
| `remove_research_source` | Remove a study or document by its opaque source ID |
| `add_all_research_studies` | Attach all available studies |
| `clear_research_sources` | Remove all source associations from a session |
| `inspect_research_session` | List sessions, sources, chat history, outputs; read a session, output, or job |
| `upload_research_source` | Upload external evidence as base64 file contents (10 MB decoded maximum) |
| `chat_research_session` | Synchronous chat; returns a durable job when the wait expires |
| `queue_research_chat` | Queue chat immediately; shares retry keys with synchronous chat |
| `generate_research_output` | Queue a report, native PowerPoint, or saved Highlights video |
| `edit_research_output` | Prompt an in-place report or PowerPoint edit; retains the output ID |
| `rename_research_output` | Rename a saved Studio output |
| `delete_research_output` | Delete a saved Studio output |
| `upload_research_template` | Upload a report or presentation template (5 MB maximum) |
| `download_research_output` | Download Markdown/PPTX/PDF bytes or get a private Highlights video link |
| `start_research_analysis` | Start an advanced exhaustive, quick, aggregate, or exploratory run |
| `resume_research_analysis` | Resume a run with an additional call allowance |
| `cancel_research_analysis` | Cancel an active run |
| `get_research_analysis` | Inspect canonical evidence, coverage and analysis run history |
| `queue_research_deliverable` | Advanced run-bound presentation, clip, reel or default-report video export |
| `get_research_deliverable` | Poll an export job and obtain its private download link |
| `cancel_research_deliverable` | Cancel an export job |

Use `inspect_research_session` with `view: "job"`, `session_id`, and the returned
`job_id` to poll chat, preparation, generation and edits. On success, read the
answer/references or the returned `output_id`. Use `parent_job_id` for a chat
follow-up. Preserve the required `idempotency_key` (1–200 characters) and the exact input on retries. A sync wait
expiring never cancels or duplicates the backend job. Native Tasks remain
available for the existing low-level `queue_research_deliverable` tool; the new
session tools use explicit durable job polling on both transports.

Read outputs before editing. Edits publish in place after success; default
reports are read-only. Highlights are generated once per default-report revision,
with learning-goal chapters and the report's verified quotations. Original audio
is used when available; chat-only studies have no artificial narration.

Uploads accept `file_name` and `data_base64`, never server-local paths or arbitrary
URLs. The host must supply an attachment's bytes. Downloads return structured
`filename`, `mime_type`, `data_base64` and `size_bytes` (64 MB transfer maximum),
or a short-lived `download_url` for video. Decode file bytes to a local artifact;
do not display base64 to the human. Source access is rechecked on every read.

These tools are available on full, core and compact profiles; read-only includes
five read tools: `inspect_research_session`, `get_research_analysis`, `get_research_deliverable`, `download_research_output`, and `view_research_answer`. The directory profile exposes eight research read tools.

## Example: research to Studio

```json theme={null}
{"tool":"create_research_session","arguments":{"name":"Product research","idempotency_key":"session-001"}}
```

Add a study with `sync_research_study`, or upload an external source. Save the
returned session ID and preparation job ID. Then queue a question:

```json theme={null}
{"tool":"queue_research_chat","arguments":{"session_id":"SESSION_UUID","prompt":"What drives trust? Include verified quotations.","idempotency_key":"chat-001"}}
```

Poll `inspect_research_session` with `view: "job"` until it succeeds or fails.
Return the answer and its source references to the human. For another turn, use
`parent_job_id` to preserve the conversation context.

```json theme={null}
{"tool":"generate_research_output","arguments":{"session_id":"SESSION_UUID","type":"powerpoint","prompt":"Summarize the saved findings for the product team.","idempotency_key":"deck-001"}}
```

After success, inspect the returned output ID. To apply a user-requested change:

```json theme={null}
{"tool":"edit_research_output","arguments":{"session_id":"SESSION_UUID","output_id":"OUTPUT_UUID","prompt":"Shorten the executive summary, retaining citations.","idempotency_key":"edit-001"}}
```

The output ID remains the same. Wait for the edit job to succeed before reading or
downloading the updated file. Default reports cannot be edited. Generation and
editing need a `write`-scoped key; inspection/download need `read`. A human's
request to generate Highlights authorizes using the original participant audio
when available; no artificial narrator is introduced for chat studies.

See the [REST API reference](/api-reference/intelligence-hub) for exact schemas,
source IDs, pagination, templates and retry contracts.

Report templates accept Markdown, TXT, or DOCX with placeholders such as `{{title}}`
and `{{findings}}`. Presentation templates accept 16:9 PPTX files and reuse their
theme and layouts. Templates provide formatting, not research evidence.

## Study questions and clickable evidence

| Tool | Description |
| - | - |
| `view_research_answer` | Show a saved Hub chat answer with clickable citations and authenticated reference cards; also checks pending jobs. |

For study findings, comparisons and quotations, resolve the intended studies, create a Hub session if needed, and attach only the requested missing studies. Retain the session for the conversation. Reuse unchanged sources; do not resync or run exhaustive analysis for every question. Follow-ups use the last completed chat job as `parent_job_id`. Study-plan changes still use `customize_study`; status questions use their dedicated tools. Read-only and directory profiles cannot create chat turns.

The answer and its reference cards stay inside the MCP conversation. Always call `view_research_answer` after the chat job completes to display the full answer with clickable citations; do not replace it with a link to the Intelligence Hub dashboard. In clients that support MCP Apps, clicking a citation opens a card in the embedded answer, with original audio or video playback and transcript context. Clients without MCP Apps receive the readable answer and quotes, but cannot display interactive cards.

`chat_research_session` and `queue_research_chat` expose an MCP App that polls the same durable job. `view_research_answer` can reopen it using `session_id` and `job_id`. Clicking a citation fetches its exact quotation, nearby transcript context, study name and available original recording. Reference access is checked again on every read. Citation labels identify transcript turns, not distinct participants. Hub answer generation and verification group citations by source interview so multiple quotes from one interview are not described as different people. Chat interviews have no generated narration. External-document cards show their verified excerpt and page when available.

The App preserves the backend's citation labels and displays no internal IDs or raw JSON. In clients without MCP Apps, the viewer returns readable answer text and quotation labels. Interactive cards are supported inside the embedded App; the MCP server cannot control citation rendering in a host assistant's prose.


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

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

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

23 MCP tools for creating, customizing, reviewing, fielding, reporting on, and searching studies.

Studies are the central research object. The 23 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 |
| - | - |
| `approve_panel_launch` | App-only approval handler, hidden from the model; the person uses the launch App button |
| `queue_report_slides` | Queue an export of an existing saved study report |
| `get_report_slide_job` | Poll the saved-study report slide export |
| `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. Unavailable evidence is represented by null or empty fields. `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.

`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 is optional for chat studies; an explicit value 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.

Study-name writes have a maximum length of 40 characters; reads can return longer saved names.

`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`. Hub session creation, chat, output generation and edits, analysis creation, and deliverable creation require `idempotency_key` (1–200 characters). 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/targeting

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`. 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` | Delete a webhook by its registered URL |

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

Embed a study in your site or app so people can start a voice or chat interview without leaving. Install with HTML, JavaScript, or React.

The User Intuition AI widget lets participants start a voice or chat interview without leaving your product. Responses appear on your study dashboard like any other interview.

Use it for in-app feedback, post-purchase surveys, churn intercepts, or always-on listening from inside your product.

***

## From the dashboard

On a BYOP study, open the **Invites** tab and click **Invite Participants**. Two items give you ready-made code:

| Menu item | What you get |
| - | - |
| **Copy Embed Code** | Opens the **Copy Embed Code** dialog with the full widget, pre-filled with this study's values. Switch between `tsx` (a React component) and `html` (the custom element plus its script tag), then click copy. |
| **Copy Button Embed Code** | Copies a styled **Take the study** button to your clipboard: a plain link to your study with a small `<style>` block. |

The generated code sets voice mode, dark theme, bottom-right position, full size, and the consent dialog. Change any of them with the attributes below.

> [!TIP]
>
> The button is the lighter option: it opens your [study link](/recruiting/share-link) in a new tab. Override its colors, radius, and font with the CSS variables `--userintuition-button-background`, `--userintuition-button-color`, `--userintuition-button-radius`, and `--userintuition-button-font`.

***

## Quickstart

**1. Grab your code**

Click **Invite Participants** → **Copy Embed Code** on the study dashboard, or call `GET /api/public/v1/studies/{study_id}/embed-code?type=widget` with your Study ID.

**2. Install or include the widget**

Run `npm install @userintuition-ai/web` for React, or drop in the UMD `<script>` tag for plain HTML.

**3. Mount it**

Add the generated `<userintuition-widget>` element and script, or pass its values to `<UserIntuitionWidget />`.

**4. 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.

**5. Test the interview**

Open the page, trigger the widget, and complete a test interview. The response appears on your study dashboard.

***

## Install

The package is published as `@userintuition-ai/web`.

```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>
```

***

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

```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} />;
}
```

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

***

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

```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}
/>
```

***

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

***

## From the API

To fetch the same code programmatically, 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. |

These values come pre-filled in the code from the **Copy Embed Code** dialog or the embed-code API. See [Study lifecycle](/api-reference/study-lifecycle) in the API reference.

> [!WARNING]
>
> The widget's `public-key` is not one of your account API keys, and is safe to ship in client-side code. Never put an account API key from [Account settings](/resources/account-settings#api-keys) in a web page.

***

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

***

## Next steps

> **[External panels](/recruiting/external-panels)**
>
> Route respondents from a panel provider you already use.

> **[Share a study link](/recruiting/share-link)**
>
> The simpler alternative — a hosted URL anyone can open in a browser.


# External Panels
Source: https://docs.userintuition.ai/recruiting/external-panels

Route respondents from Prolific, Cint / Lucid, CloudResearch, Terac, or any panel provider into a BYOP study through one entry URL.

Already buy respondents from a panel provider? Connect that provider to a BYOP study from **Invite Participants** → **Bring Your Own Panel**. You paste one entry URL into the provider. Respondents arrive with their provider ID, take the interview, and are sent back to the provider with their outcome: complete, screened out, or quota full.

You recruit and pay the provider directly; we run the interviews. To have us recruit and bill for participants instead, use [our research panel](/recruiting/research-panel).

***

## Setting it up

**1. Open the panel configuration**

On the study dashboard, click **Invite Participants** → **Bring Your Own Panel**. Once a configuration is saved, the same item reads **View/Edit Panel Configuration**.

**2. Choose your provider**

Pick **Prolific**, **Cint / Lucid**, **CloudResearch**, **Terac**, or **Custom provider**. Choosing a named provider fills in its parameter names and placeholders for you.

**3. Check the ID mapping**

Confirm the **Respondent ID parameter** and its **Provider placeholder**, plus the optional session and study ID pairs. See [ID parameters](#id-parameters).

**4. Add your redirect URLs**

Paste the return URLs from your provider. **Complete** and **Screen-out** are required. See [Redirect URLs](#redirect-urls).

**5. Save and copy the entry URL**

Click **Save configuration**, then click **Copy provider entry URL** and add it to your study on the provider's side.

> [!WARNING]
>
> Anyone with the entry URL can enter the study. Share it only with your provider.

***

## ID parameters

The entry URL carries the provider's identifiers in query parameters, so each interview can be matched back to the respondent.

| Field | What it's for |
| - | - |
| **Respondent ID parameter** / **Provider placeholder** | Required. The parameter name, and the macro your provider swaps for the respondent's ID |
| **Session ID parameter** / **Session placeholder** | Optional. A per-attempt ID, for providers that issue one |
| **Study ID parameter** / **Study placeholder** | Optional. The provider's own ID for the study |

The presets fill these with each provider's conventions:

| Provider | Respondent ID | Session ID | Study ID |
| - | - | - | - |
| **Prolific** | `PROLIFIC_PID` | `SESSION_ID` | `STUDY_ID` |
| **Cint / Lucid** | `respondent_id` (`[%RID%]`) | `session_id` (`[%MID%]`) | — |
| **CloudResearch** | `participantId` | `assignmentId` | `projectId` |
| **Terac** | `teracSubmissionId` | — | `taskId` |
| **Custom provider** | `respondent_id` (`{{RESPONDENT_ID}}`) | — | — |

Check them against your provider's documentation before saving; you can edit any field.

***

## Redirect URLs

When a respondent finishes, they're sent back to the provider at the URL for their outcome.

| Redirect | When it's used | Required? |
| - | - | - |
| **Complete redirect URL** | The respondent finished the interview | Yes |
| **Screen-out redirect URL** | Your screener questions disqualified them | Yes |
| **Quota-full redirect URL** | The study had already reached its target | Optional |
| **Technical-failure redirect URL** | The session couldn't continue for a technical reason | Optional |

Redirect URLs can include `{{respondent_id}}`, `{{session_id}}`, `{{external_study_id}}`, `{{call_id}}`, and `{{outcome}}`, which are filled in for each respondent.

> [!TIP]
>
> Choosing **Terac** pre-fills the complete and screen-out redirects with the User Intuition thank-you page. Replace them if your Terac task expects its own return URLs.

***

## While it's fielding

The provider appears as its own row at the top of the Invites table, with a status of **Fielding**, **Paused**, or **Complete** and the time of the latest interview. Click **View/Edit information** on that row to reopen the configuration.

You can [pause and resume](/managing-your-study/study-actions#pause-and-resume) the study as usual. Respondents who arrive while it's paused are asked to try again later, and can re-enter once you resume.

A study connects to one provider at a time. Interviews use credits as usual. See [Billing and credits](/resources/billing-and-credits).

***

## Frequently asked questions

> **Can I use two providers on one study?**
>
> No. Duplicate the study to run a second provider alongside it.

> **Can I still share the study link or send email invites?**
>
> Yes. The other options in the **Invite Participants** menu stay available.

> **My provider isn't listed.**
>
> Choose **Custom provider** and enter your provider's parameter name, placeholder macro, and return URLs.

***

## Next steps

> **[Research panel](/recruiting/research-panel)**
>
> Have us recruit and pay participants for you

> **[External panels API](/api-reference/external-panels)**
>
> Configure, rotate, and disable the integration programmatically


# Send Email Invites
Source: https://docs.userintuition.ai/recruiting/invite-customers

Email study invitations to addresses you add or to contacts synced from HubSpot, Shopify, or Stripe, and track who completes.

Add email addresses, or pick contacts synced from HubSpot, Shopify, or Stripe, and User Intuition sends the invitations for you. The **Invites** tab tracks who was invited and who has completed.

Use this when your list is too long to send by hand, or when you want delivery and completion tracked in one place. For invitations that come from you directly, which usually get better response rates, [share a study link](/recruiting/share-link) instead.

***

## Open Send Email Invites

On the study dashboard's **Invites** tab, click **Invite Participants** → **Send Email Invites**. The panel has three tabs: **Manual**, **Contacts**, and **Segments**.

**Send Email Invites** appears on BYOP studies only. It's greyed out while the study is paused; resume the study to send again.

***

## Add addresses manually

**1. Stay on the Manual tab**

The **Manual** tab is selected by default.

**2. Enter email addresses**

Type an address, or paste several separated by commas. There's no file upload, so paste a long list comma-separated.

**3. Add them to the list**

Click **+** or press Enter. Valid addresses join the list, duplicates are dropped, and invalid ones are flagged for you to fix.

**4. Send**

Click **Send N Invitations**.

Manual entry suits small or one-off invites, such as specific customers or a test with your own team.

***

## Invite contacts from HubSpot, Shopify, or Stripe

If your customers live in [HubSpot](/integrations/hubspot), [Shopify](/integrations/shopify), or [Stripe](/integrations/stripe), connect that account and invite them straight from this panel. You connect by installing the User Intuition app from the tool itself, not from inside a study. Each integration's page covers setup and what syncs.

Each connection appears as a card at the top of the Send Email Invites panel, with its sync status and contact count. Click a card to load its contacts and segments. Once a sync has finished, the refresh icon on the selected card re-syncs it.

**Contacts**

Search or scroll the synced contacts, check the people you want, and click **Send N Invitations**.

**Best for:** inviting specific customers by name, and keeping participant records consistent with your CRM across studies.

**Segments**

Check one or more segments and click **Send to N Segments**. Every connection has a default segment covering everyone synced. Other segments sync from the connected tool.

**Best for:** recently churned customers, high-value customers, a subscription tier, or any cohort you already maintain in HubSpot, Shopify, or Stripe.

Using a different CRM? Paste its addresses into the **Manual** tab, or [share a study link](/recruiting/share-link).

***

## Manage invitations

### The Invites table

The **Invites** tab lists every invitation with four columns: **Email**, **Invite Status**, **Call Status**, and **Actions**. Test conversations carry a **Test** tag next to the email.

| Invite Status | Meaning |
| - | - |
| **Sent at \[date]** | Invitation email was sent |
| **N/A** | No email sent; the participant came through the study link or widget |
| **Pending** | Not yet sent |

| Call Status | Meaning |
| - | - |
| **Taken on \[date] at \[time]** | Participant completed the interview |
| **Pending** | No interview yet |

### Invite actions

Each row has two actions:

| Action | Description |
| - | - |
| **Resend** | Send the invitation email again |
| **Copy** (icon) | Copy this participant's unique invite link |

Both are disabled while the study is paused. There's no way to delete an individual invitation.

### Search and filter

* Use the **Search** box to find invitations by email
* Use the **Show** dropdown to display 5, 10, 20, or 50 invitations per page

***

## Best practices

> **Personalize when possible**
>
> Participants respond better when they're asked by name.

> **Set expectations**
>
> Tell participants how long the interview will take. Clear expectations improve completion rates.

> **Time your invitations**
>
> Send invitations when participants are likely to have time to respond. Avoid holidays and weekends for B2B research.

> **Send reminders**
>
> Use **Resend** for participants who haven't responded after a few days.

> **Mention incentives**
>
> If you're offering incentives, highlight them in your invitation. Even small ones improve participation.

***

## Frequently asked questions

> **How many participants can I invite?**
>
> There's no limit.

> **Can I invite the same person to multiple studies?**
>
> Yes. Space out invitations to the same people to avoid research fatigue.

> **What email do participants receive?**
>
> Participants receive a branded email invitation with your study details and a unique link to begin the interview.

> **Can I customize the invitation email?**
>
> Contact support to discuss email customization options for enterprise customers.

> **Can I close invitations after reaching my target?**
>
> A study that reaches its target stops accepting interviews, and [pausing the study](/managing-your-study/study-actions#pause-and-resume) closes every invite link until you resume.

***

## Next steps

> **[HubSpot](/integrations/hubspot)**
>
> Sync HubSpot contacts and lists to invite them by email

> **[Share a study link](/recruiting/share-link)**
>
> Send the invitation yourself, from a channel your customers know


# Recruiting Participants
Source: https://docs.userintuition.ai/recruiting/overview

Choose how to fill a study: bring your own participants, recruit from our research panel, or run synthetic respondents. Compare turnaround and cost.

There are three ways to fill a study. You pick one under **Recruiting Method** in [Step 4](/creating-a-study/setup-interview#recruiting-method):

| Recruiting method | Who you talk to |
| - | - |
| **BYOP** (bring your own participants) | Your customers, your users, or respondents from a panel provider you already use |
| **Panel** | People we recruit for you from our research panel |
| **Synthetic** | AI respondents built from your screeners and targeting attributes |

Your choice sets the options in the **Invite Participants** menu once the study is live.

> [!NOTE]
>
> A study uses one method. To hear from both your own participants and the panel, run two studies.

***

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

Four 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 or pick contacts synced from [HubSpot](/integrations/hubspot), [Shopify](/integrations/shopify), or [Stripe](/integrations/stripe), and we email them | Larger lists, when you want delivery tracked |
| [**Embed a widget or button**](/recruiting/embed-widget) | Put the study inside your product or site | Catching people mid-experience |
| [**External panels**](/recruiting/external-panels) | Point a provider like Prolific or Cint at one entry URL | Respondents you buy from a panel provider you already use |

### Why the study link is the default here

A study link keeps the invitation coming from **you**: in your voice, in a channel your customer already knows, with whatever context makes them want to help, such as an account manager's note or a line in your newsletter.

Response rates are better when the ask comes from someone the person already knows. And you keep that relationship, rather than handing part 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

Use the panel when you don't have the people, or need people who aren't your customers. Which option you use depends on how common your audience 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 can reach beyond it, including hard-to-reach geographies.

| 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 first column is your audience's *incidence rate*: the share of the general population who'd qualify for your study.

You don't need a precise number. Ask: **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 need a niche recruit. Asking the panel will be slow and return thin results.

***

## Synthetic respondents

AI respondents answer your study in chat, each playing a persona built from your screener answers and targeting attributes.

Use them for fast, low-cost answers: explore a concept early, rehearse a study before you field it, or iterate on a plan in hours instead of days. Interview-grounded respondents draw on past interviews with real panel members. See [Synthetic respondents](/recruiting/synthetic-respondents).

***

## What it costs

| | Cost |
| - | - |
| **Your own participants** | Nothing beyond credits. Optionally [pay them a reward](/managing-your-study/study-actions#enable-incentives), \$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 |
| **Synthetic respondents** | **1 credit per 10 interviews**, no participant fee |

Every interview uses credits, however the participant got there. See [Billing and credits](/resources/billing-and-credits).

***

## How many participants do you need?

Whichever way you recruit real people, 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.

Out of 100 people you interview, how many do you think would mention what you're looking
for?

to be % confident you'd hear about something  of every
100 people would mention.

Sizing one group — if your study covers several personas, size each separately.

Most studies are smaller than the confidence people want from them. Ten interviews feels thorough, but not for anything affecting fewer than 1 in 5 participants.

> **[How this is calculated](/resources/sample-size)**
>
> The reasoning, the reference tables, and what to do when you need a proportion rather than a discovery.

***

## Screening participants

Whichever method you choose, [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. For synthetic studies, they're what each persona is built from.

***

## Best practices

> **Say how long it takes**
>
> People abandon an interview that runs longer than they were told. Put the real number in the invitation.

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

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

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

***

## Next steps

> **[Share a study link](/recruiting/share-link)**
>
> The recommended way to reach your own participants

> **[Research panel](/recruiting/research-panel)**
>
> Panel recruiting and niche audiences


# 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 when you choose **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

**1. Open Invite Participants**

On your study dashboard, click **Invite Participants** → **Recruit from Our Panel**.

**2. Set how many interviews you want**

The default is 20; the minimum is 1. See [How many participants do you need?](#how-many-participants-do-you-need). To control the mix, use the **⋮** button beside the field to [set targets per answer](#set-targets-per-answer).

**3. Choose a frequency**

**One-time** fields your target once. **Weekly**, **Monthly**, or **Quarterly** recruits that many interviews on repeat. See [Recurring panels](#recurring-panels).

**4. Choose a target market**

Participants are recruited from the country you select. See [Where we recruit](#where-we-recruit). The interview language comes from your study settings.

**5. Launch**

Click **Continue**, review the credits and card hold in **Confirm Panel Creation**, then click **Create Panel**. The study moves to **Fielding**. Watch progress on the dashboard.

The panel matches against your screener questions and targeting attributes from Step 4, so get those right before you field.

### Set targets per answer

By default the panel fills your target with whoever qualifies. To control the mix, such as 10 iOS users and 10 Android users, set fixed targets on a screener question's answers.

Click the **⋮** button beside **How many interviews?** to open **Set single-select targets**. It lists every single-select screener question with at least two qualifying options, including age. For each option, enter a number of interviews or leave it **Open**. Open options share whatever's left of the total. Click **Set targets** to save.

* Targets must be positive whole numbers.
* A question's targets can't add up to more than the panel total.
* If targets add up to less than the total, leave at least one option **Open**.

To use this, your study needs a single-select screener with two or more qualifying answers. Add one in Step 4 first.

> [!TIP]
>
> Working through the API? Option-level targets are covered in [Panel targeting](/api-reference/panel-targeting).

### 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 to find them.

> [!NOTE]
>
> **Language narrows the list.** The country picker only shows countries where your study's interview language is available, so set the language first. English is available in most countries; a language like Swedish or Thai only in its own. If your country isn't showing, check the language.

Working through the API? [List Panel Countries](/api-reference/public-panel-countries/list-panel-countries) returns the current countries and the languages each supports.

### Running the same study in several countries

A study fields one panel at a time, so you have two options:

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

Language is a study setting, not a panel setting. Set it for each market before you field, for example switching a study duplicated for Japan to Japanese.

### Recurring panels

Setting a frequency of **Weekly**, **Monthly**, or **Quarterly** recruits your target number of interviews on that cadence, rather than once.

Use this for a tracking study: the same questions to a fresh sample each wave, so you see a trend rather than a snapshot. Each wave lands in the same study.

> [!NOTE]
>
> If you set up a new panel while one is already fielding, you'll be asked to stop the existing one first.

### 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 nothing: no participant fee and no credits.

When you launch a panel, we place a hold on your card for the participant rewards. The confirmation shows the amount, and it appears as **held** in your [transaction history](/resources/billing-and-credits#transaction-history). You're charged against it as quality interviews come in. 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 verified before they reach your study. Every completed interview is rated **Excellent**, **Good**, **Fair**, or **Poor**, as for your own participants.

You pay only for Excellent and Good. With your own participants, Fair is also charged; here we chose the participant, so a thin conversation is ours to absorb.

***

## Recruit a niche audience

> [!NOTE]
>
> **Beta.** Available from **Invite Participants** → **Recruit a Niche Audience**.

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, so lead time is usually days, not hours.

**Every participant is verified.** Before they reach your study, we confirm 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 (see [How many participants do you need?](#how-many-participants-do-you-need)) and who. The more specific you are, 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.

***

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

Out of 100 people you interview, how many do you think would mention what you're looking
for?

to be % confident you'd hear about something  of every
100 people would mention.

Sizing one group — if your study covers several personas, size each separately.

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.

> **[How this is calculated](/resources/sample-size)**
>
> The reasoning, the reference tables, and why this differs from a survey sample size.

***

## Frequently asked questions

> **Can I use the panel and my own participants in the same study?**
>
> No. A study uses one recruiting method: BYOP, Panel, or Synthetic. Run two studies if you want both.

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

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

> **Can I pause a fielding panel?**
>
> Yes: **Actions** → **Pause Study**. See [Study actions](/managing-your-study/study-actions#pause-and-resume). While paused, you can still launch a fresh panel from **Invite Participants**; launching it resumes the study.

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

***

## Next steps

> **[Synthetic respondents](/recruiting/synthetic-respondents)**
>
> Rehearse your study with AI respondents before you field it

> **[Study dashboard](/managing-your-study/dashboard)**
>
> Watch fielding progress and completed interviews


# Share a Study Link
Source: https://docs.userintuition.ai/recruiting/share-link

Copy your study link 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 your own email, a Slack message, a newsletter, or a reply in an existing thread.

**When you're bringing in your own participants, this is the method we recommend.** The invitation comes from *you*, in your voice and in a channel the person already knows. Response rates are better when the ask comes from someone familiar, and you keep that relationship.

Use [email invites](/recruiting/invite-customers) instead when your list is too long to send by hand, or when you want invited-and-completed status tracked for you.

***

## When to use a study link

* **Always-on feedback:** let customers reach you whenever they have something to share
* **Social media:** share on X, LinkedIn, or community forums
* **Email newsletters:** include it in regular customer communications
* **Your website:** add a permanent "Share feedback" link
* **Customer communities:** post in Slack, Discord, or forums
* **QR codes:** print on receipts, packaging, or in-store displays. Any QR code generator works.

***

## Copy your study link

**1. Open the Invite Participants menu**

On the study dashboard's **Invites** tab, click **Invite Participants**.

**2. Select Copy Study Link**

Click **Copy Study Link**. The link is copied to your clipboard.

**3. Share it**

Paste the link wherever you want to reach people.

> [!NOTE]
>
> On a **Panel** study the same menu item reads **Copy Test Link**. Use it to try the study yourself, not for distribution.

For a styled "Take the study" button on your site, use **Copy Button Embed Code** in the same menu. See [Embed the AI widget](/recruiting/embed-widget#from-the-dashboard).

***

## How the link works

* **Open to anyone.** No email address or account needed, and it works on any device with a browser.
* **Unlimited uses.** One link serves every participant. Each person gets their own session and response.
* **Stays live with the study.** There's no expiry. Pausing the study closes the link until you resume, so you don't need to redistribute it. Reaching the study's target closes it for good.

***

## Study link vs. email invites

| | Study link | Email invites |
| - | - | - |
| **Tracking** | Anonymous unless they provide an email | Tied to a specific email |
| **Who can take part** | Anyone who has the link | Only the people you invite |
| **Reach** | Unlimited | Limited to your list |

***

## Tracking link participants

Link participants appear on the **Invites** tab with:

* Their email, if they provided one during the interview
* **Invite Status** of **N/A**, since no invitation email was sent
* **Call Status** showing when they completed the interview

Each study has one link. To see which channel people came from, create a separate study per channel, or ask how they found the study in your research plan.

***

## Frequently asked questions

> **Can I limit who can use the link?**
>
> No. Study links are open to anyone. For controlled access, use [email invites](/recruiting/invite-customers).

> **Can I deactivate the link?**
>
> Pause the study to close the link; resume to reopen it. Deleting the study closes it for good.

> **Do link participants count against my response limits?**
>
> Yes. All responses count toward your plan limits regardless of how participants were invited.

***

## Next steps

> **[Send email invites](/recruiting/invite-customers)**
>
> Have us email your list and track who completes

> **[Embed the AI widget](/recruiting/embed-widget)**
>
> Run interviews inside your product or site


# Synthetic Respondents
Source: https://docs.userintuition.ai/recruiting/synthetic-respondents

Get fast, low-cost answers from AI respondents built from your targeting, including respondents grounded in real panel interviews.

Synthetic respondents are AI participants. Each one plays a persona built from your screener answers and targeting attributes, and takes your study as a chat interview. Their conversations appear on your dashboard like any other.

You choose them by picking **Synthetic** as the recruiting method in [Step 4](/creating-a-study/setup-interview#recruiting-method).

***

## When to use them

Synthetic respondents give you answers in minutes, at a fraction of the cost of fielding.

* **Explore early.** Pressure-test a concept, message, or hypothesis before you commit budget to it.
* **Rehearse your study.** Check that questions flow, probes land, screeners route as intended, and the report gives you what you need.
* **Iterate quickly.** Run a batch, refine the plan, and run again in the same afternoon.
* **Ground it in real people.** [Interview-grounded respondents](#interview-grounded-respondents) are built from past interviews with real members of our panel.

> [!TIP]
>
> A common pattern: run 10 synthetic interviews, refine the study from what you learn, then [duplicate it](/managing-your-study/study-actions#duplicate-study) and field it to a [panel](/recruiting/research-panel) or [your own participants](/recruiting/share-link) to confirm the findings before a high-stakes decision.

***

## Setting up a synthetic study

Choosing **Synthetic** in Step 4 changes three things:

* **Chat only.** The interview format switches to **Chat**. Voice and Video are unavailable.
* **No concept links.** Studies with concept links can't use Synthetic.
* **Demographics are added for you.** The first time you choose Synthetic, **age**, **gender**, **household income**, and **ethnicity/race** are added to your targeting attributes. You can edit or remove any of them.

Everything else works as it does for any study. Personas are built from the qualifying answers to your screeners and targeting attributes, so tighten those to shape who the respondents are.

***

## Running synthetic interviews

**1. Launch the study**

On **Ready to Launch**, the Recruiting card reads **Synthetic Respondent**. Launch as normal.

**2. Open Invite Participants**

On the study dashboard, click **Invite Participants** → **Recruit from synthetic participants**.

**3. Choose how many**

Pick a target of **10**, **20**, or **30** interviews. The dialog shows the cost before you start.

**4. Start interviews**

Click **Start interviews**. Responses appear on the dashboard as each one completes.

While a batch is running, the menu item reads **Synthetic interviews in progress** and you can't start another. Once it finishes you can run another batch on the same study.

### Interview-grounded respondents

The dialog also offers **interview-grounded** respondents. Each one draws on a past interview with a different real member of our panel who matches your targeting, so its answers reflect how that person actually talked about their life and choices. Generated personas fill the rest of the target, and the dialog shows the split (for example, "6 interview-grounded and 4 generated personas").

Each grounded response is labeled **Synthetic · Interview-grounded** with the month of the source interview.

If there aren't enough eligible members for a target, that target is unavailable and you aren't charged.

***

## Reports

Generate a report from the **Reports** tab, as for any study. You need **at least three** finished synthetic responses.

***

## What it costs

**1 credit per 10 interviews**: 10 interviews is 1 credit, 30 is 3. There's no participant fee. See [Billing](/resources/billing-and-credits).

In the sandbox, **Launch Synthetic Study** starts three free synthetic interviews right away. See the [Staging quickstart](/api-reference/staging-quickstart).

***

## Frequently asked questions

> **Can I mix synthetic and real participants in one study?**
>
> No. A study uses one recruiting method. Run the synthetic version first, then duplicate the study and choose a different recruiting method in Step 4 for the real one.

> **Why can't I choose Synthetic for my study?**
>
> Studies with concept links can't use synthetic respondents. Remove the concept links, or field the study to real participants.

> **How should I use synthetic findings?**
>
> As fast, directional input: to shape a concept, sharpen a study, or choose which ideas to take forward. Interview-grounded respondents bring in real panel members' experiences. For decisions that need direct customer evidence, confirm with real participants.

***

## Next steps

> **[Research panel](/recruiting/research-panel)**
>
> Confirm your findings with real participants

> **[Study dashboard](/managing-your-study/dashboard)**
>
> Follow responses as each synthetic interview completes


# Account and Team Settings
Source: https://docs.userintuition.ai/resources/account-settings

Manage your profile, company information, team and workspaces, API keys, and authentication tokens from your account settings.

Open account settings by clicking your avatar and name in the footer of the left sidebar. Each setting lives in one of three places in that menu:

| 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) |
| Organization name | Team & Workspaces | Workspace owner only |
| Teammates | Team & Workspaces | Owners and admins |
| Active workspace | Team & Workspaces | Yes |
| Password | Manage Account | Yes |
| API keys | Manage Account > API Keys | Create / revoke |
| API token | Manage Account > API Token | View/copy only |

***

## Profile settings

**1. Open the menu**

Click your avatar in the sidebar to open the account dropdown.

**2. Select Profile Settings**

Click **Profile Settings** to open the settings panel.

**3. Edit your information**

Update your first name, last name, and company name. Email is read-only and managed through your account provider.

**4. Save**

Click **Save Changes** to apply your updates.

### Company name

Your company name appears in your profile and is used across the platform.

* If you are in a **workspace (organization)**, the company name comes from the organization name. The workspace owner changes it in [Team & Workspaces](#team-and-workspaces).
* If you are an **individual user**, company name is required. You're prompted to set it the first time you sign in.

***

## Account management

Click **Manage Account** in the account dropdown for:

* Email and password management
* Connected accounts and security settings
* API token access

***

## Team and workspaces

Click **Team & Workspaces** in the account dropdown to manage teammates and switch between workspaces. If you have pending invitations, the menu item shows a count, for example **Team & Workspaces (1 invitation)**.

Inviting teammates is available on any plan. Studies and credit balances belong to the workspace they were created in. Switching workspaces doesn't move them.

### Switching workspaces

Use the **Workspace** dropdown at the top of the dialog to pick another workspace you belong to. The app reloads into the selected workspace.

### Accepting an invitation

Pending invitations appear in the dialog as **Join *workspace name***. Click **Accept invitation** to join and switch into that workspace.

### Workspace roles

| Role | Who | Can do |
| - | - | - |
| **Owner** | The person who created the workspace | Everything an admin can, plus rename the organization |
| **Admin** | Teammates given the admin role | Invite and manage teammates; buy credits, change plans, and manage payment methods in [Wallet](/resources/billing-and-credits) |
| **Member** | Everyone else | Run research in the workspace and view the Wallet read-only |

### Inviting teammates

Owners and admins invite teammates by email and manage members in the Team & Workspaces dialog. Members see an **Admins only** notice and need to ask an admin.

If you aren't in a workspace yet, the dialog lets you create one.

### Renaming the organization

The workspace owner sees an **Organization name** field in the dialog. Edit it and click **Save organization name**. The new name is used as the company name for everyone in the workspace.

***

## API keys

API keys give programmatic access to the User Intuition API and the [MCP server](/mcp-server/overview) for your organization. Keys don't expire. They work until you revoke them, or until the account that created them leaves the organization.

### Creating an API key

**1. Open Manage Account**

Click your avatar, then select **Manage Account**.

**2. Go to the API Keys tab**

In the account management dialog, click **API Keys** in the sidebar.

**3. Name your key**

Enter a name, such as "Research agent" or "MCP Server". A blank name defaults to "Default".

**4. Choose access and a cap**

**Read studies and results** is always on. Check **Create and edit research** for write access. Check **Launch paid panels** or **Send participant rewards** only when needed. Either one also turns on write access and requires a **Lifetime spend cap (USD)** above zero.

**5. Click Create Key**

Click **Create Key**. Your new API key is displayed in a banner at the top of the page.

**6. Copy the key immediately**

Click **Copy Key**. After you dismiss the banner or navigate away, only the key prefix is visible.

> [!WARNING]
>
> The full key is shown only once. If you lose it, revoke it and create a new one.

### Managing API keys

The API Keys page lists all active keys for your organization. Each row shows:

| Field | 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, for capped keys, how much of the lifetime cap has been used (for example, "$12.00 of $100.00 cap used") |

A cap can't be changed after the key is created. Create a new key when it runs out. Older keys created before access options existed may show no cap; revoke and replace one to set a cap.

### Revoking an API key

Click the trash icon next to a key, then click **Confirm**. Revoked keys stop working immediately and can't 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 copy a short-lived session token. Session tokens expire periodically and a new one is generated when you sign in. For most uses, [API keys](#api-keys) are easier because they don't expire.

**1. Open Manage Account**

Click your avatar, then select **Manage Account**.

**2. Go to API Token**

In the account management dialog, click the **API Token** tab in the sidebar.

**3. Reveal your token**

Click **Reveal Token** to display your current token.

**4. Copy the token**

Click **Copy Token** to copy it to your clipboard.

> [!WARNING]
>
> Your API token gives full access to your account. Don't share it.

***

## Next steps

> **[Referrals](/resources/referrals)**
>
> Earn credits by inviting friends to User Intuition.

> **[Billing & credits](/resources/billing-and-credits)**
>
> Manage your plan, credits, and payment methods.


# Best Practices
Source: https://docs.userintuition.ai/resources/best-practices

Design focused studies, recruit the right participants, and turn interviews into decisions with these proven research practices.

Use these practices to design focused studies, recruit the right people, and turn interviews into decisions.

***

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

### 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, such as why people churned or what confused them in onboarding, 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.

### 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 the quality mix

Compare **Quality Interviews** with total **Responses** on the dashboard. 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

The [Intelligence Hub](/results/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

> **Asking leading questions**
>
> Instead of "Don't you think our checkout is confusing?", ask "Walk me through your experience with checkout."

> **Ignoring low-quality responses**
>
> Low-quality responses often reveal confusion or disengagement, which is itself worth investigating.

> **Over-indexing on single responses**
>
> One passionate participant doesn't make a pattern. Wait for consistent themes across multiple interviews.

> **Researching without acting**
>
> Research that doesn't lead to action wastes resources and erodes organizational trust in research value.

***

## Checklists

### Study setup

* [ ] Clear research objective defined
* [ ] 4-6 focused topics identified
* [ ] Questions written in participant language
* [ ] Decision/action identified for insights
* [ ] Study tested before launch (a test conversation, or a [synthetic rehearsal](/recruiting/synthetic-respondents))

### Recruitment

* [ ] Target participants identified
* [ ] Invitation includes time estimate
* [ ] Incentive communicated (if applicable)
* [ ] Reminder plan in place
* [ ] Early responses monitored

### Analysis

* [ ] 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

***

## Next steps

> **[Sample size](/resources/sample-size)**
>
> Work out how many interviews your study needs.

> **[Create a study](/creating-a-study/overview)**
>
> Put these practices into a new study.


# 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 uses credits based on its format. You manage your balance, plan, and payment methods on the **Billing** page.

***

## Accessing billing

Click your avatar and name in the footer of the left sidebar, then choose **Wallet**. You can also go straight to [app.userintuition.ai/wallet](https://app.userintuition.ai/wallet).

> [!NOTE]
>
> In a team workspace, only owners and admins can change billing. Members see the page read-only. See [Workspace roles](/resources/account-settings#workspace-roles).

***

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

### Changing your plan

Each plan card at the top of the Billing page has a button. Your current plan shows **Current plan**; the others show **Upgrade to …** or **Downgrade to …**.

**1. Add a payment method**

Professional requires a card on file. If you don't have one, add it first under [Payment methods](#payment-methods).

**2. Click Upgrade to Professional**

Review the plan details in the dialog and click **Confirm Subscription**.

For Enterprise, click **Upgrade to Enterprise**. In the **Contact Sales Team** form, add a message (and optionally a phone number) and click **Send Message**.

### Downgrading to Starter

You can cancel Professional yourself:

**1. Click Downgrade to Starter**

On the Starter card.

**2. Confirm**

Review what changes and click **Confirm Downgrade**, or **Keep Professional** to back out.

Professional stays active until the end of the current billing period and then doesn't renew. Your remaining credits stay in your wallet. Until the switch, your current plan shows **Cancels at period end** and the Starter card shows **Activates on** with the date. After that, additional credits are charged at the Starter rate.

***

## 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 |
| **Synthetic respondents** | 1 per 10 synthetic participants |

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. See [Synthetic respondents](/recruiting/synthetic-respondents) for how synthetic studies work.

### Which interviews you're charged for

Whether a completed interview costs credits depends on its [quality rating](/results/calls-and-transcripts#quality-ratings) and how the study recruits:

| Quality rating | Panel studies | Your own participants |
| - | :-: | :-: |
| **Excellent** | Charged | Charged |
| **Good** | Charged | Charged |
| **Fair** | Free | Charged |
| **Poor** | Free | Free |

Panel studies use a higher bar because we source the participants. If a panel interview is thin, 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.

### Buying credits

**1. Click Buy more credits**

On the Billing page, click **Buy more credits** in the Credit Balance card.

**2. 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.

**3. Confirm**

Click **Add Credits** to charge the card on file. Credits land in your balance immediately.

### 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. Turn it on**

Toggle **Enable Auto Reload of Credits** on.

**2. Set the amount**

Set **Credits to reload**. The dollar **Amount** updates to match at your plan's rate.

**3. Save**

Click **Save changes**.

> [!WARNING]
>
> Auto-reload needs a payment method on file.

***

## Payment methods

You need a card on file to buy credits, subscribe to a plan, launch a research panel, or send participant rewards.

**1. Click Add or Edit**

In the **Payment method** section of the Billing page, click **Add**, or **Edit** to replace your card.

**2. 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.

**3. Save**

Click **Save**. Your card brand and last four digits appear as confirmation.

### Removing a payment method

Click **Edit**, then **Remove**, and confirm in the **Remove payment method?** dialog. Without a card on file you can't buy credits, and auto-reload stops working.

### Billing email

The **Billing email** field sits above your card in the Payment method section. Enter it before you save a card. It's attached to the card's billing details and can differ from your account email.

> [!NOTE]
>
> Enterprise workspaces are invoiced separately, so the Payment method section and **Buy more credits** are hidden for them.

***

## Research panel pricing

Recruiting from the research panel costs **\$30 per participant** on top of credits. It covers the participant's incentive, screening, and fraud prevention, and you're billed only for quality completes.

When you launch a panel, a hold for the expected participant cost is placed on your card. It appears in **Transactions** as **Study launch hold — *study name*** with a **held** status. When the panel settles, the hold becomes a single **Panel rewards** charge for the quality completes, or is released if nothing is owed.

Niche audiences, such as B2B roles and executives, 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. Hover a bar to see credits, audio and video interviews, and synthetic participants for that day or week

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 |
| **Reward** | Participant incentives: individual digital gift cards, or a **Panel rewards** charge when a panel settles |
| **Hold** | Card authorization placed when you launch a panel, shown until it's captured or released |
| **Refund** | Credits returned to your wallet (shown with a minus sign) |
| **Subscription** | Recurring plan charges |

Credits used by interviews appear in **Usage stats**, not here.

| Status | Indicator |
| - | - |
| **Completed** | Green dot |
| **Held** | Blue dot |
| **Failed** | Red dot |
| **Processing**, **Deferred** | Gray dot |

> [!NOTE]
>
> On Enterprise, rewards show as **Deferred** and are billed at the end of the billing cycle.

Each row shows the description, timestamp, amount, and status. Completed transactions with a receipt have a **Receipt** button to download it. Click **Load More** for older transactions.

***

## Frequently asked questions

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

> **Can I get a refund on unused credits?**
>
> Email [support@userintuition.ai](mailto:support@userintuition.ai) to discuss refund options.

***

## Next steps

> **[Account & team](/resources/account-settings)**
>
> Manage your profile, workspace, and team roles.

> **[Referrals](/resources/referrals)**
>
> Earn credits by inviting friends to User Intuition.


# Frequently Asked Questions
Source: https://docs.userintuition.ai/resources/faq

Find answers to common questions about studies, participants, the AI interviewer, results, privacy, and billing.

Quick answers to common questions about User Intuition. Can't find what you're looking for? [Contact support](/resources/support).

***

## Getting started

> **What is User Intuition?**
>
> User Intuition is an AI-powered customer intelligence platform that runs AI-moderated chat, voice, and video 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.

> **How is User Intuition different from surveys?**
>
> Traditional surveys collect structured, quantitative data. User Intuition holds real conversations. It asks follow-up questions, probes interesting answers, and adapts to each participant. This reveals motivations, emotions, and context that surveys miss.

> **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 step is embedding the widget in your app, if you want to, and that's copying code we provide.

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

***

## Studies and interviews

> **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). See [Study types](/study-types/overview).

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

> **Can I edit my study after launching?**
>
> Yes, but avoid changing questions once participants have completed interviews, because early and late responses won't be comparable. For bigger changes, duplicate the study. See [Edit Study](/managing-your-study/study-actions#edit-study).

> **What happens if a participant drops off mid-interview?**
>
> The interview still appears in the **Calls** tab with the transcript and recording up to the point they left. It's quality-rated on what was captured, like any other interview. Interviews rated **Poor** are never charged. See [Billing and credits](/resources/billing-and-credits#credits).

> **Can I run multiple studies at once?**
>
> Yes. Each study has its own dashboard.

***

## Participants and recruiting

> **Can I interview my own customers?**
>
> Yes, and we recommend it. Your own customers usually give more relevant, actionable insights than panel participants.

> **What if I don't have customer email addresses?**
>
> You have several options: use our research panel of 4M+ participants, [connect your own panel provider](/recruiting/external-panels), share a study link on social media or your website, or embed the widget in your app.

> **Can I run a study with synthetic respondents?**
>
> Yes. Choose **Synthetic** as the recruiting method to run your study against AI respondents built from your screeners and targeting attributes. Synthetic studies run as chat interviews and cost 1 credit per 10 synthetic participants. Use them to explore ideas quickly and to rehearse a study before fielding it. See [Synthetic respondents](/recruiting/synthetic-respondents).

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

> **Which countries can you recruit 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 full list. You pick one country per panel, and the list 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.

> **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, debited from your wallet, and paid only 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.

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

***

## AI interviewer

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

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

> **Can participants tell they're talking to an AI?**
>
> Yes. Participants are told they're speaking with an AI moderator.

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

***

## Data and analysis

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

> **How are reports generated?**
>
> Open the **Reports** tab on your study dashboard, click the **⋮** menu, and choose **Generate Report**. A report can be generated as soon as the study has usable interviews; synthetic studies need at least three finished synthetic responses. See [Reports](/results/reports).

> **Will reports update automatically?**
>
> When new interviews come in or the research plan changes, the report is marked **Out of date**. Choose **Regenerate Report** from the **⋮** menu to rebuild it. When the study reaches its target, the report is regenerated for you and you'll get an email that your results are ready.

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

> **Can I export my data?**
>
> Yes. In the **Calls** tab, open the **⋮** menu and choose **Download calls (CSV)** to export your interviews. Reports can be printed (or saved as PDF) with **Print Report** from the Reports tab's **⋮** menu. Professional and Enterprise customers can also build custom reports and PowerPoint presentations in the [Intelligence Hub](/results/intelligence-hub).

> **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's available on Professional and Enterprise. See [Intelligence Hub](/results/intelligence-hub) for details.

***

## Privacy and security

> **Is participant data secure?**
>
> Yes. See our [Security](https://www.userintuition.ai/security) page for how we protect participant data.

> **How long is data retained?**
>
> See our [Security](https://www.userintuition.ai/security) page for retention policies.

> **Can I delete participant data?**
>
> Yes. On studies with your own participants, delete an individual interview from the **Calls** tab with the trash icon. This permanently removes its transcript, recordings, and responses. Deleting a study removes all associated data permanently.

> **Is User Intuition GDPR compliant?**
>
> See our [Security](https://www.userintuition.ai/security) page for compliance details and data processing agreements.

***

## Billing and plans

For plans, credit costs, coupons, payment methods, and research panel pricing, see [Billing and credits](/resources/billing-and-credits). Test conversations are always free.

***

## Troubleshooting

> **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 interviews also need camera access. Participants can't start until they allow it. If they blocked it earlier, they need to set the browser's camera permission to **Allow**.

> **The transcript seems inaccurate**
>
> Accuracy is high on clear audio. Background noise and strong accents can reduce it, so check the recording when a passage matters.

> **My report seems incomplete**
>
> Reports are only as rich as the interviews behind them. Check the report's **Evidence Coverage** tab to see where the evidence is thin, add more interviews if needed, and regenerate the report once it's marked **Out of date**.

***

## Still have questions?

> **[Contact support](/resources/support)**
>
> Our team is here to help. Reach out for personalized assistance.


# 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

> **1. Invite**
>
> Enter a friend's email from the **Refer a Friend** dialog.

> **2. They sign up**
>
> Your friend receives an email invitation with a link to create their account.

> **3. You earn credits**
>
> Once they make their first payment, your referral is credited and bonus credits are added to your wallet automatically.

***

## Inviting a friend

**1. Open the account menu**

Click your avatar and name at the bottom of the left sidebar, then choose **Refer a Friend**.

**2. Enter your friend's email**

Type the email address of the person you'd like to invite. Press **Enter** or click **Invite**.

**3. Confirmation**

Your friend appears in **Your referrals** with a **Pending** status.

### What your friend receives

Your friend gets an email titled **\<Your name> invited you to User Intuition**, with a link to sign up. Your name comes from your profile. If you haven't set one, the part of your email before the @ is used.

***

## Tracking your referrals

The **Refer a Friend** dialog lists everyone you've invited under **Your referrals**, with each one's 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 show the bonus earned, for example **Credited (+10)**.

***

## Resending an invitation

If a friend hasn't acted on your invite, find them in **Your referrals** and click **Resend** next to their email. This doesn't create a duplicate referral.

**Resend** appears only on **Pending** referrals. It's not available once a referral is credited or your friend has created an account another way.

***

## Rules and limits

> **No self-referrals**
>
> You cannot enter your own account email as a referral.

> **One referral per email**
>
> You can have one active referral per email address. Inviting the same person twice shows "You've already invited this person."

> **New users only**
>
> If the email already has a User Intuition account, under any organization, you'll see "This person already has an account."

> **Outside your team**
>
> You can't refer a member of your workspace or someone with a pending workspace invitation. You'll see "This email already belongs to your organization." Add teammates through [Team & Workspaces](/resources/account-settings#team-and-workspaces) instead.

> **Payment required to credit**
>
> A referral moves from **Pending** to **Credited** only after the invited user makes their first payment, not at sign-up.

***

## Frequently asked questions

> **What if my friend never signs up?**
>
> It stays **Pending** with no expiry, and you can resend the invitation at any time.

> **Are referral credits any different from purchased credits?**
>
> No. They go into the same wallet balance, can be used for any [interview mode](/resources/billing-and-credits#credits), and never expire while your wallet is active.

***

## Next steps

> **[Billing & credits](/resources/billing-and-credits)**
>
> See your balance and how credits are spent.

> **[FAQ](/resources/faq)**
>
> Answers to common questions about User Intuition.


# Sample Size
Source: https://docs.userintuition.ai/resources/sample-size

Calculate how many interviews you need to be confident you'll hear about an issue, based on how common it is.

Most studies are smaller than the confidence people want from them. Ten interviews feels thorough, so ten gets run. Then a finding gets treated as settled when the sample never had the power to settle it.

Answer one question, how common the thing you're looking for is, to get the number you actually need.

Out of 100 people you interview, how many do you think would mention what you're looking
for?

to be % confident you'd hear about something  of every
100 people would mention.

Sizing one group — if your study covers several personas, size each separately.

***

## 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**. 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 [When you need a proportion](#when-you-need-a-proportion-not-a-discovery).

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

***

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

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

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

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

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

> **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."

***

## Next steps

> **[Billing & credits](/resources/billing-and-credits)**
>
> See what your target will cost.

> **[Research panel](/recruiting/research-panel)**
>
> Field a panel study at the size you need.


# Contact Support
Source: https://docs.userintuition.ai/resources/support

Contact the User Intuition team from the app or by email, check service status, and send feature requests.

Reach our team from inside the app or by email. If something seems broken for everyone, check the [service status page](#service-status) first.

***

## What to include

To help us resolve your issue faster, include:

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

***

## Contact us

### From inside the app

The fastest way to reach us is the **Contact Support** form.

**1. Open the account menu**

Click your avatar and name in the footer of the left sidebar.

**2. Choose Contact Support**

Select **Contact Support** to open the form.

**3. Describe the issue**

Fill in a **Subject** and **Message** (both required). Add a **Phone Number** if you'd like a call back.

**4. Send**

Click **Send Message**. Your name and account email are included automatically, so we can reply directly.

### Email support

For general questions, technical issues, or account assistance:

> **Email Support**
>
> **[support@userintuition.ai](mailto:support@userintuition.ai)**
>
> Typical response time: Within 24 hours on business days

### Sales inquiries

For pricing, enterprise features, or custom solutions:

> **Sales**
>
> **[sales@userintuition.ai](mailto:sales@userintuition.ai)**

***

## Service status

If you're experiencing widespread issues, check the [service status page](https://status.userintuition.ai/) for the current state of the API, MCP server, dashboard, and docs. Contact support if your work is affected.

***

## Feature requests

Email feature requests to **[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

***

## Enterprise support

Enterprise customers also get:

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

***

## Next steps

> **[FAQ](/resources/faq)**
>
> Find answers to common questions.

> **[Key concepts](/getting-started/key-concepts)**
>
> Understand the platform fundamentals.


# Calls & Transcripts
Source: https://docs.userintuition.ai/results/calls-and-transcripts

Review completed interviews: the calls list, quality ratings, and the transcript, attributes, and summary for every conversation.

The **Calls** tab on your study dashboard lists every completed interview, with its transcript, screener answers, and summary.

***

## The calls list

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 incentives are enabled |

Click any row to open its details, covered [below](#reviewing-a-single-interview).

### Status

| Status | Meaning |
| - | - |
| **Completed** / **Ended** | The interview happened and the data is in |
| **Active** | Someone is in the conversation right now |
| **Pending** | The interview is queued |
| **Processing** | The interview finished; the transcript and analysis are being prepared. Give it 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 |

For why **Fair** is charged differently, 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 see. Excellent, Good, and Fair are shown by default. Poor is also shown while the study has only a few interviews, then hidden. 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 can still be useful. Check its quality rating and transcript before discounting it.

### Row actions

The icon at the end of each row depends on how the study recruits:

| Study type | Action | What it does |
| - | - | - |
| Panel | **Reject call** | Removes the call. If the study hasn't met its target, recruiting reopens to replace it. |
| Everything else | **Delete call** | Permanently deletes the call with its transcript, recordings, and responses |

Both ask you to confirm, and neither can be undone.

### Downloading calls

Open the **⋮** menu above the table and choose **Download calls (CSV)**. You get one row per call: email, status, date, duration, quality, end reason, full transcript, and recording links. The export follows your quality filter. Transcripts can't be downloaded one at a time.

***

## Reviewing a single interview

Expanding a row opens **Call Details**, with up to three tabs and these controls:

* **Share** copies a link to this call. Anyone with access to the study can open it.
* An **audio player** for the call recording, when there is one.
* **View Video** plays the video recording, on studies that captured one. Studies that sent participants to a concept link show **Replay** buttons instead, which play back what they did there.

### Transcript

The full conversation, with the moderator on one side and the participant on the other. Each turn shows its time into the call, so you can find the same moment in the recording.

> [!TIP]
>
> Read the transcript, but listen to at least a few. Tone, hesitation, and emphasis don't survive the transcription.

### Attributes

The participant's answers to your screener questions. Panel studies also show their panel profile attributes.

On synthetic studies grounded in an earlier interview, a **Synthetic · Interview-grounded** note appears at the top. The responses are AI-generated from a real member interview, not a new conversation. See [Synthetic respondents](/recruiting/synthetic-respondents).

### 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 reached are marked unanswered, so you can spot coverage gaps at a glance.

***

## Frequently asked questions

> **Are transcripts generated automatically?**
>
> Yes, and they're available as soon as the interview finishes processing.

> **How accurate are the transcripts?**
>
> Accuracy is high on clear audio. Background noise and strong accents can reduce it, so check the recording when a passage matters.

> **Can I edit a transcript?**
>
> No. Transcripts are read-only so the record stays faithful to what was said.

***

## Next steps

> **[Reports](/results/reports)**
>
> Synthesis across every interview in the study.

> **[Intelligence Hub](/results/intelligence-hub)**
>
> Analysis across every study you've run.


# 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. For what a single study found, use its [study report](/results/reports#study-report-vs-intelligence-hub) instead.

> [!NOTE]
>
> The Intelligence Hub is included on the **Professional** and **Enterprise** plans. On Starter you can open a pre-populated sample session to see how it works; creating your own sessions prompts you to upgrade.

***

## What you can do

* Ask questions that span several studies at once
* Upload external files alongside your study data
* Get cited answers in chat
* Generate custom reports and PowerPoint decks
* Ask for changes to a generated report or deck in plain language
* Keep projects apart in separate sessions

***

## Getting started

Click **Intelligence Hub** in the left navigation. Your work is organized into **sessions**, listed beneath it. Each session has its own sources, chat history, and generated outputs. A session page has three panels:

| Panel | Position | Purpose |
| - | - | - |
| **Sources** | Left | Add studies and upload files |
| **Chat** | Center | Ask questions about your data |
| **Studio** | Right | Generate reports and presentations |

**1. Create a session**

Click **Create new session**. It opens as "Untitled Session"; rename it from the session's **⋮** menu to something like "Q1 churn deep-dive."

**2. Add sources**

Use the **Sources** panel to sync completed studies or upload files.

**3. Ask a question**

Type into the **Chat** panel. The answer is drawn from every source in the session.

***

## Adding sources

Sources are the data behind every answer and every generated output.

### Sync a study

Syncing a study brings in its interview transcripts and, if it has one, its [study report](/results/reports).

**1. Select a study**

In the **Sources** panel, open **Add study as source**. It lists your studies not yet synced to this session, with a search box. When everything's synced, it reads **All studies synced**.

**2. Sync**

Click **Sync Assistant Data**. A message shows how many transcripts came across and whether a report was included.

When a synced study has collected new interviews since you added it, a **Re-sync** button appears on that source. Click it to bring them in.

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

A file is ready to query when its status changes from **uploading** to **completed**. 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.

***

## Asking questions

Add at least one source, then type a question into the **Chat** panel. Answers draw on every source in the session.

**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 citations. Click one to see the transcript or document it came from. Answers can be inaccurate, so check the citations before acting on anything important.

***

## Generating outputs in Studio

The **Studio** panel turns your sources into deliverables. Both output types build in the background, so you can keep chatting.

### Reports

**1. Click Reports**

In the Studio panel, click **Reports**.

**2. Add a prompt**

In **Custom 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."

**3. Generate**

Optionally fill in **Report Name**, then click **Generate Report**. When it's ready, click its name to open it.

### PowerPoint presentations

**1. Click PowerPoint**

In the Studio panel, click **PowerPoint**.

**2. Add a prompt**

In **Custom Prompt**, describe the focus. For example: "Cover the top three issues participants raised, one slide each, written for an executive audience."

**3. Generate**

Optionally fill in **PowerPoint Name**, then click **Generate PowerPoint**. View or download the deck once it completes.

### Revising an output

Open a completed report or PowerPoint and type into **Ask for changes to this output…** at the bottom. For example: "Shorten the executive summary and add a slide on pricing." Click **Send**.

The update runs in the background, so you can close the view and come back. The revised version opens in the same view and is saved to your outputs.

### Managing outputs

Everything you generate appears under **Outputs** in the Studio panel with its name, type, and creation date. Click an output to open it; the rest is in its **⋮** menu.

| Action | Description |
| - | - |
| **View Prompt** | See the exact prompt used to generate it |
| **Rename** | Change the output name |
| **Delete** | Permanently remove the output |

***

## Managing sessions

| Action | How |
| - | - |
| **Create** | Click **Create new session** in the left navigation |
| **Switch** | Select a session from the list under **Intelligence Hub** |
| **Rename** | Hover the session, open its **⋮** menu, and select **Rename** |
| **Delete** | Hover the session, open its **⋮** menu, and select **Delete** |

***

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

* **Start narrow.** Specific questions beat broad ones. "What did users say about the checkout flow?" outperforms "Tell me about the user experience."
* **Combine studies.** The hub earns its keep when several studies are in one session and it can compare across them.
* **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.
* **Build over time.** Each study you sync makes every future question richer.

***

## Next steps

> **[Best practices](/resources/best-practices)**
>
> Design studies that produce better interviews to analyze.

> **[Reports](/results/reports)**
>
> The per-study report each study produces.


# Reports
Source: https://docs.userintuition.ai/results/reports

Generate, read, refresh, and print your study report, and learn when to use the Intelligence Hub instead.

Every study gets its own report, synthesized from the interviews it collected. It answers one question: **what did this study find?** It takes you from the headline findings down to the participant quotes behind them. Open it from the **Reports** tab on your study dashboard.

***

## Study report vs Intelligence Hub

| | Study report | [Intelligence Hub](/results/intelligence-hub) |
| - | - | - |
| **Answers** | What did this study find? | What do all my sources say about this question? |
| **Scope** | One study | Several studies plus files you upload |
| **Output** | Fixed structure, generated per study | Chat answers, custom reports, and PowerPoint decks |
| **Plan** | Every plan | Professional and Enterprise |

When you sync a study into a Hub session, its report comes along as a source.

***

## Generating the report

Generate, regenerate, and print the report from the **⋮** menu at the top right of the Reports tab.

### Generating for the first time

**1. Open the Reports tab**

On your study dashboard.

**2. Generate the report**

Open **⋮** and choose **Generate Report**.

You can generate a report as soon as the study has usable interviews. Synthetic studies need at least three finished synthetic responses.

### Keeping the report current

When new interviews come in or the research plan changes, the report is marked **Out of date**. Open **⋮** and choose **Regenerate Report** to rebuild it from every eligible interview.

When the study reaches its target, the report is regenerated for you and you get an email that your results are ready.

### Printing

Open **⋮** and choose **Print Report** to print it or save it as a PDF from your browser's print dialog.

***

## What's in the report

The report is organized into five tabs.

### Study Findings

The main readout:

* **Executive Summary**: a one- or two-paragraph overview of the most important findings, followed by **Key Metrics** describing the sample.
* **Key Insights**: a short list of the most significant findings and notable exceptions, each linked to its sources.
* **Detailed Findings**: numbered findings under each Learning Goal from your research plan. Each finding covers the main point, how many participants it applies to, supporting quotes, impact, exceptions, limits, and why it matters for your decision. Counts are shown as a count and percentage, for example `2 of 5 participants (40%)`. The percentages describe this sample only, not the wider population.

Numbered citations such as `[12]` appear throughout. Click one to see the source interview and quote behind the claim.

### Evidence Coverage

Evidence Coverage assesses how well the evidence supports the findings. It has three parts:

* **Sample adequacy**: what this sample can and cannot support, and whether more interviews would materially help.
* **Learning Goal evaluations**: for each Learning Goal, the evidence available, its gaps, and what decisions it can support.
* **Important remaining gaps**: a prioritized list of what's still unresolved and why it matters. Each gap has an ID that Recommended Next Steps link back to.

These are interpretations, not scores. You decide whether the evidence is enough for your decision. Older reports show Evidence Coverage as unavailable until you regenerate them.

### Participant Responses

Each interview in the report, one at a time: its overall takeaways and what that participant said against each Learning Goal. Use it when you want to follow one person's view through the whole study.

### Participant Profiles

Who you talked to, summarized across the sample from the profile and screener questions.

### Recommended Next Steps

Up to two next steps, each tied to a gap in Evidence Coverage. Click a gap ID on the card to jump to it. Each card has one action:

| Action | What it does |
| - | - |
| **Create \[study name]** | Starts a follow-up study, pre-filled with this report's findings, open questions, and the gap it addresses, then opens it for you to review before launch |
| **Invite participants** | Takes you to the Invites tab to collect more interviews for this study |

**No additional research proposed from this assessment** means no gap was worth acting on. If you see **Research recommendations unavailable**, regenerate the report to retry.

***

## Mid-study review

Some studies get a review partway to their target. It appears under **Recommended Next Steps** and shows early findings from the interviews so far. It either confirms your current guide is working or offers a **Suggested improvement**: up to two new questions, with guidance on when to ask them. You also get an email linking to it.

To use the suggestion:

**1. Click Accept**

The **Accept** button is on the **Suggested improvement** card under **Recommended Next Steps**.

**2. Confirm the change**

Tick the acknowledgement, then choose **Confirm and accept** in the **Accept this study improvement?** dialog. The questions are added to the live study plan.

Future interviews use the new questions. Earlier interviews don't change. Click **Dismiss** to leave the study as it is. Only the study owner or an organization administrator can accept.

> [!WARNING]
>
> Accepting changes the study mid-collection, so interviews before and after the change aren't directly comparable. See [Study actions](/managing-your-study/study-actions#edit-study).

***

## Working with the report

### Tracing a finding to its transcript

Click a finding's citation to see the source quote, or open the **Calls** tab to read the full transcript.

### Via API or MCP

You can also generate and fetch reports programmatically. See the [API reference](/api-reference/introduction) and the MCP server's [study tools](/mcp-server/tools/studies).

***

## How many interviews a report needs

There's no fixed number. It depends on your research purpose, how relevant the participants are, how deep the interviews went, and whether your decision needs segment comparisons. A small sample doesn't become representative because it has a report. [Evidence Coverage](#evidence-coverage) tells you when more interviews would help.

***

## Frequently asked questions

> **Can I edit the report?**
>
> No. Study reports are read-only. Copy content to edit it elsewhere, or create a custom report in the [Intelligence Hub](/results/intelligence-hub) and ask for changes there.

> **How often should I regenerate the report?**
>
> When it's marked **Out of date** and you need the latest picture. A batch of 5-10 new interviews is a good trigger; a couple more rarely changes much.

> **Can I get a report in a different format, or a presentation?**
>
> The study report has one standard structure. For a report focused on a particular question or audience, or a PowerPoint deck, sync the study into an [Intelligence Hub](/results/intelligence-hub) session and generate one from Studio.

> **Why does my report look thin?**
>
> Check interview depth and quality on the **Calls** tab, whether the participants were the right people, and whether your research plan has clear Learning Goals.

***

## Next steps

> **[Intelligence Hub](/results/intelligence-hub)**
>
> Analysis across studies, with custom reports and presentations.

> **[Calls & transcripts](/results/calls-and-transcripts)**
>
> Review individual interviews.


# 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/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/plugins/user-intuition-research/skills/analyze-completed-study/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/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: `c4eec17d2ea1e71b9d82323cad2206fe4bae2cfe05cfcb2433539f81f309b458`

## 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`, poll `get_report_job` with its job ID until it succeeds, then fetch the saved report.
4. For questions about findings, comparisons, or quotations, reuse or create an organization Hub session, sync only the requested missing study sources, and use `chat_research_session` or `queue_research_chat`. Poll `inspect_research_session` with `view: "job"` when needed. After completion, call `view_research_answer` to display the answer and exact citation labels in the conversation. Reuse the session and the last completed `parent_job_id` for follow-ups.
5. 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.
6. 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.
7. 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/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/plugins/user-intuition-research/skills/create-study-from-brief/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/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: `790021e61de1e6fa1b5414316c5131711c2d840f1e209b2c33b158240d8d34c3`

## 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 the human to choose Panel, BYOP (bring your own participants), or synthetic respondents when unstated. Set `recruiting_method` to `panel`, `byop`, or `synthetic_respondents` accordingly. Synthetic respondents use chat only. 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 for Panel or BYOP, and chat for synthetic respondents. 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. Prefer `queue_customize_study` with the user's natural-language brief, then poll `get_customize_study_job` until it succeeds and inspect its `result`. Use synchronous `customize_study` when sending a native concept image. Pass the 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. Use `decisions: "human"` by default. Set `decisions: "agent"` only when the person has delegated research-design choices; report returned assumptions. Relay required `questions[]` to the user and submit their answer as another planning turn. Poll each queued turn before continuing. Agent mode does not authorize a recruiting choice, plan approval, or paid launch.
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`. Plans contain Learning Goals: answerable questions with evidence requirements underneath. Do not render the derived `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 `estimate_panel` and separate approval of its complete estimate through the launch preview and human confirmation flow.
```


# 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/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/plugins/user-intuition-research/skills/curate-interview-quality/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/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/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/plugins/user-intuition-research/skills/design-screeners/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/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/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/plugins/user-intuition-research/skills/field-a-panel/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/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: `44c11cc483c14d7f2b7f6c47c1593713672d3dcca249043ed52df59042b6d1c7`

## 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. Obtain explicit launch approval through the preview flow below; never infer it 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. Call `launch_panel` with the `estimate_id` and the same settings and country to obtain a preview. In clients supporting MCP Apps, the person approves with the App button; `approve_panel_launch` is App-only and must not be called by the model. Without Apps, show the saved plan and complete quote, obtain explicit human confirmation, then call `launch_panel` with the returned `chat_approval_nonce` and `human_confirmed=true`. Never invent a nonce or confirmation. Report what was launched. After an uncertain 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/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/plugins/user-intuition-research/skills/invite-your-own-participants/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/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`, `get_report_job`, `chat_research_session`, `queue_research_chat`, `view_research_answer` |
| [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`, `queue_customize_study`, `get_customize_study_job`, `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`, `estimate_panel`, `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` |

## Using these workflows

Connect the authenticated MCP server, select the intended organization, and inspect each tool schema for its required inputs. Research-design delegation does not replace plan approval or paid-action confirmation.


# 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/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/plugins/user-intuition-research/skills/monitor-fielding/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/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

**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).

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

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

**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
```

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

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

> **[create-study-from-brief](/skills/create-study-from-brief)**
>
> Turn a research brief into a launch-ready interview study.

> **[design-screeners](/skills/design-screeners)**
>
> Recruit exactly the right respondents — panel and custom screeners, done safely.

> **[field-a-panel](/skills/field-a-panel)**
>
> Recruit N respondents from the panel, with cost approved before any spend.

> **[invite-your-own-participants](/skills/invite-your-own-participants)**
>
> Interview your own customers — invites, share links, and rewards (BYOP).

> **[run-a-concept-test](/skills/run-a-concept-test)**
>
> Put a concept, prototype, or landing page in front of participants.

> **[monitor-fielding](/skills/monitor-fielding)**
>
> Daily digest of every fielding study — progress, quality, stalls.

> **[analyze-completed-study](/skills/analyze-completed-study)**
>
> From transcripts to stakeholder-ready findings, with real quotes only.

> **[curate-interview-quality](/skills/curate-interview-quality)**
>
> Review low-quality interviews and delete only the exact interviews the user confirms.

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

> **[Skills library](/skills/library)**
>
> Browse and copy ready-to-use skills.

> **[MCP quickstart](/mcp-server/quickstart)**
>
> Skills require an MCP-connected client. Wire one up first.


# 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/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/plugins/user-intuition-research/skills/retrieve-study-results/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/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: `010252ac4b8768a8d66f490f444dd24da1be2b7b2f35403e55d650bf866e1234`

## 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; `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/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/plugins/user-intuition-research/skills/run-a-concept-test/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/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: `9c401ba7aba891fde2336de325c2cf65b1c03a594f78bc0186eb8ee7857bf4f7`

## 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. Estimate Panel cost with `estimate_panel` 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/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/plugins/user-intuition-research/skills/search-research/SKILL.md) · [Source](https://github.com/user-intuition/skills/blob/05728f6c0f1b5677cc17f1d2db2eb71f0f76935d/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, page, or video, capture their reaction, and have the moderator probe 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.

> **Visual designs**
>
> Compare two homepage mockups, validate a new icon set, or get reactions to a redesigned dashboard before you build it.

> **Feature concepts**
>
> Show wireframes or annotated screens of a feature you're considering and learn whether participants understand the value.

> **Marketing copy**
>
> Test headlines, value propositions, or ad creative to find which framing resonates.

> **Packaging and pricing**
>
> Get unprompted reactions to packaging, a pricing page, or a plan comparison before it goes live.

***

## What you can attach

Each Concept Test study supports two kinds of assets, both added in [Customize Plan](/creating-a-study/customize-plan) while you work with Charles:

| Asset type | Use for | Example | How to add it |
| - | - | - | - |
| **Concept image** | Static visuals you want the participant to look at | Homepage mockup, ad creative, screenshot | **Add attachment** in the chat |
| **Concept link** | A page or video the participant should open and react to | Draft landing page, demo video, hosted mockup | Paste the URL into the chat |

Attach as many of each as you need. Every asset has a **label** the moderator uses to refer to it, so labels should describe what the participant is about to see.

***

## Attaching images

**1. Open Add attachment**

In Step 2, click the **paperclip** in the chat's message box. The **Add attachment** dialog opens.

**2. Add your images**

Drag files into the dialog or click to browse. Supported formats are **PNG**, **JPEG**, **GIF**, and **WebP**, up to 10 MB each. You can add several at once.

**3. Label each one**

Every image needs a label before you can add it: something short and descriptive, such as `Homepage v2` or `Pricing page — control`. The moderator uses this label when introducing the image to the participant.

**4. Send them with your next message**

The images are staged in the chat and upload when you send your next message to Charles. Previous images stay in place.

> [!WARNING]
>
> Labels must be unique within a study. Uploading an image with a label that already exists **replaces** the existing image (case-insensitive match). To keep both, use distinct labels like `Homepage A` and `Homepage B`.

### Removing an image

Before you send, remove a staged image from the chat. After it's uploaded, ask Charles to remove it.

***

## Attaching shareable links

Use concept links when what you want a reaction to lives on a page rather than in an image, such as a draft landing page, a demo video, or a hosted mockup.

**1. Paste the link into the chat**

In Step 2, paste the full URL into your message to Charles.

**2. Say what it is**

Tell Charles what the link shows so he can label it clearly, such as `Pricing page — variant B` or `Launch video`. As with images, labels are unique per study and reusing a label replaces that link's URL.

**3. Add login details if asked**

If the page looks like it needs a login, a **Login details** dialog opens and the chat pauses until you **Save login details** or **Skip for now**.

Make sure participants can reach every link. If it has view permissions, open them to anyone with the link. For a page behind a login, the **Login details** dialog takes a username, password, and optional note. Participants see them, with copy buttons, when the page opens during their interview. Use a throwaway or demo account, since the password is visible to participants and appears in the screen recording.

To remove a link, ask Charles to delete it.

> [!WARNING]
>
> **Concept links rule out chat.** Once a study has concept links, the **Chat** interview format and **Synthetic** recruiting are unavailable, and **Test with AI** is hidden in step 5. Use voice or video.

***

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

***

## Set concepts up well

How the moderator handles concepts shapes how you should prepare them:

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

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

> **Three to five is plenty**
>
> More than that fragments the conversation and cuts the time spent on each one.

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

Build two things 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

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

> **Can I update a concept after launching the study?**
>
> Yes. Uploading an image or adding a link with the same label replaces the existing entry, so you can swap a concept mid-study. Completed interviews still reflect the version that was live at the time.

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

> **What if a participant can't see the image or open the link?**
>
> The moderator 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.

***

## Next steps

> **[Prototype Test](/study-types/prototype-test)**
>
> Watch people use a prototype or live site instead.

> **[Customize Plan](/creating-a-study/customize-plan)**
>
> Attach your concepts while you build the plan with Charles.


# In-depth Interview
Source: https://docs.userintuition.ai/study-types/in-depth-interview

Run a conversation-only study about what people 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, like a recent experience or 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.

***

## Set one up

Nothing to attach. Tell Charles in [Customize Plan](/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.

***

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

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

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

> **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).

> **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).

***

## Next steps

> **[Concept Test](/study-types/concept-test)**
>
> Get reactions to an image or video instead.

> **[Customize Plan](/creating-a-study/customize-plan)**
>
> Brief Charles and build your research plan.


# Study Types
Source: https://docs.userintuition.ai/study-types/overview

Compare the three study types (in-depth interview, concept test, prototype test) and pick the right one for your question.

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.

***

## Pick a study type

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.

***

## 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, use the research panel, or run [synthetic respondents](/recruiting/synthetic-respondents). Synthetic is chat only, so studies with concept or prototype links can't use it
* **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

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

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

***

## Next steps

> **[In-depth Interview](/study-types/in-depth-interview)**
>
> A conversation with no stimulus: discovery, decisions, unmet needs.

> **[Creating a Study](/creating-a-study/overview)**
>
> The six setup steps, whichever type you choose.


# Prototype Test
Source: https://docs.userintuition.ai/study-types/prototype-test

Watch people work through your prototype or live site while they narrate, and replay their clicks and interactions afterward.

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, like an ad, a mockup, or 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 [Customize Plan](/creating-a-study/customize-plan) by pasting it into the chat and telling Charles about it. A Figma prototype, a clickable mockup, a staging environment, or a live production page all work.

Prototype links are concept links, so the study needs voice or video: **Chat** format, **Synthetic** recruiting, and **Test with AI** aren't available once a link is added.

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

***

## How sessions are captured

There are two capture paths, and which one you get depends on your prototype.

### With the recording snippet

If you install our recording snippet on the site, every click and interaction is captured directly, **with no screen share**. Participants use the page as normal.

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, such as *"you've been on the pricing step a while. What are you weighing up?"* The participant doesn't hear these checks. Each one appears in your transcript afterwards as its own labeled row, so you can see what the moderator was reacting to.

### With screen share

Without the snippet, participants share their screen and the session is captured that way. You still get the recording and the conversation, but not 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. For the richer capture, test a hosted build instead of a Figma link.

***

## Install the recording snippet

When you add a link, Charles checks whether the snippet is already there. If it isn't, he gives 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.

***

## Review 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 (for example, the participant closed the tab mid-flow), the replay is flagged as possibly incomplete. The conversation and transcript are unaffected.

***

## Frequently asked questions

> **Does this work on a site behind a login?**
>
> Yes. When you add the link, Charles checks whether the page needs a login. If it does, a **Login details** dialog opens and the chat pauses until you save details or choose **Skip for now**. Enter a username or email, a password, and an optional note. Participants see them, with copy buttons, when the prototype opens during their interview. Use a throwaway or demo account, since participants can see the password and it appears in the screen recording.

> **Can I test more than one prototype in a study?**
>
> Yes. Add each link and Charles will structure the conversation to move between them. This is useful for old-versus-new comparisons.

> **Do participants need to install anything?**
>
> No. The snippet goes on your site, not on their machine.

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

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

***

## Next steps

> **[Creating a Study](/creating-a-study/overview)**
>
> The six setup steps, from study type to launch.

> **[Customize Plan](/creating-a-study/customize-plan)**
>
> Add your prototype link while you build the plan with Charles.