Create and assign interviews
Create and assign one interview per assignee. Admin only.
Provide existing project members via assignee_ids and/or new people to
invite via invite_emails (at least one is required). Invitees are added
as non-admin Contributors. A separate interview is created for each
assignee and the response is the list of created interviews.
write_scope defaults to local. A global write scope requires every
assignee to already be a project admin and cannot be combined with
invite_emails.
scheduled_send_at delays only the invitation email — interviews are
created and visible in-app immediately. reminders configures automatic
chase emails that run until the interview is completed, the cap is
reached, or an admin stops them.
draft_id marks this send as consuming a saved interview draft: the
draft is deleted in the same transaction, and its stored title is reused
when the sent topic still matches the draft’s.
interview_type: "guided-interview" creates guided (multi-topic
deep-dive) conversations structured by topics — an ordered list of
{title, description, skill_id} seeded as conversation-scoped topics at
send time (at least one is required). With a draft_id, the draft’s
type is authoritative (immutable), while payload topics override the
draft’s saved list — the form may hold unsaved edits at send time.
Guided sends reject questions: the topics structure the conversation,
so must-cover points belong in the topic (focus) text.
campaign_id / campaign_name group the created interviews under an
interview campaign (e.g. a workshop wave). campaign_id picks an existing
campaign; campaign_name reuses the project’s campaign with that name
(case-insensitive) or creates it. When both are absent the send falls back
to the consumed draft’s saved campaign; an explicit campaign_id: null
clears a drafted campaign.
Authorizations
Use Authorization: Bearer
Path Parameters
UUID of the project
Body
UUIDs of existing project members to interview (must be tech/contributor members).
Email addresses of people to invite on the fly as non-admin Contributors and assign an interview.
The interview focus. Used to auto-name the interview and seed its first question.
Whether interview edits stay local to the conversation or write to the shared knowledge store.
local, global Simplified interview: recipients open the distraction-free full-page
chat instead of the app. When a draft_id is set, defaults to the
draft's value.
Optional specific topics or questions (max 10). Clara weaves them naturally into the open interview and covers each before closing the topic.
ISO language code (e.g. fr) the interview must be conducted in. Null
adapts to each recipient's own preferred language. When a draft_id is
set and this field is absent, defaults to the draft's value. Unknown
codes are rejected (400).
Optional note from the assigner; replaces the default invitation email copy.
Optional future time to send the invitation email (in-app visibility stays immediate).
Automatic reminder settings (disabled by default).
Conversation type to create. Ignored when draft_id is set (the
draft's type is authoritative).
interview, guided-interview Guided interviews only: the ordered topics the interview walks through (max 12, at least one required for guided sends). Overrides a consumed draft's saved topics when provided.
Optional id of a saved interview draft this send consumes. Rejected (400) when the draft no longer exists (already sent or deleted).
Existing campaign to group the created interviews under (must belong
to the project). Absent falls back to the consumed draft's saved
campaign; an explicit null clears a drafted campaign. Wins over
campaign_name when both are sent.
Campaign to group the created interviews under, by name: reuses the project's campaign with that name (case-insensitive) or creates it.
Response
Interviews created and assigned
Interview title (auto-generated from the topic when not provided).
UUID of the user who created the interview.
Email of the user who created the interview (the importer, for imported interviews).
Conversation type: "interview" (standard mono-topic), "guided-interview"
(a multi-topic deep-dive whose ordered topics come from the sent draft or
assign payload; its focus text lives in
type_additional_parameters.interview_focus), or "imported-interview"
(a read-only transcript of an interview recorded outside the platform,
created via the import-transcript endpoint).
Free-form parameters associated with the conversation type.
Ordered list of transcript entries (messages, tool calls, etc.).
Assistant memory state accumulated over the conversation.
Files uploaded during this interview (ordered by upload time). Only the id and name are included; resolve a fresh signed download URL via the project-level local-documents detail endpoint.
UUID of the assigned user (null while a pending invite has not yet joined).
UUID of the user who created the assignment.
Assignee email, falling back to the invite email for not-yet-joined invitees.
True when assigned to someone who has not yet joined the project.
Invitation-email customization and reminder schedule for an assigned interview. Null for self-assigned interviews, non-interview conversations, and interviews created before this feature existed.
The seeded interview topic and optional specific questions, for rendering the
in-chat intro card. Null for non-interviews and interviews without a topic.
For guided interviews this is read from
type_additional_parameters.interview_focus (they have no focus issue).
Guided interviews only: the ordered topic agenda seeded at send time, with per-topic progress. Empty for every other interview type.
Campaign this interview belongs to; null for ad hoc interviews.
True while the requesting user has never started an assigned interview in this project. Drives the intro card's expanded "how it works" explainer.
Parse-pipeline state of an imported external transcript (interviews of type
"imported-interview"). Null on every other interview type. The raw pasted
transcript is never returned — the parsed chat_history is the transcript.
Background-generated summary of the conversation ("" until generated).
Null for imported interviews until their transcript parse completes.
pending, in_progress, completed Whether edits stay local to the conversation or write to the shared knowledge store.
local, global Simplified interview: when true the invite opens the distraction-free full-page chat (/interview//) instead of the app. Set at assign time; never changed afterwards.