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