> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.