Skip to main content
POST
Create and assign interviews

Authorizations

Authorization
string
header
required

Use Authorization: Bearer <token>. The token is either a user token / OAuth access token, or a service-account API key (cfk_...). A key is valid on every endpoint and acts as its service account, an organization member with per-store permissions. Refused keys answer 403 with Invalid API key., API key revoked., API key expired. or API key disabled..

Path Parameters

project_id
string<uuid>
required

UUID of the project

Body

application/json
assignee_ids
string<uuid>[]

UUIDs of existing project members to interview (must be tech/contributor members).

invite_emails
string<email>[]

Email addresses of people to invite on the fly as non-admin Contributors and assign an interview.

topic
string

The interview focus. Used to auto-name the interview and seed its first question.

artifacts
object[]

The artifacts the interviewer gets, each with whether the respondent can open it (see InterviewDraft). When the key is absent, a draft_id send reuses the draft's selection; with neither, the interviews get no artifacts.

planned_minutes
integer | null

Planned interview length in minutes, copied onto each interview as type_additional_parameters.planned_minutes. When the key is absent, a draft_id send reuses the draft's value; a guided send with neither gets the topic-count default.

Required range: 5 <= x <= 180
campaign_id
string<uuid> | null

Existing campaign to group the created interviews under (must belong to the project). Wins over campaign_name when both are sent.

campaign_name
string

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

id
string<uuid>
read-only
can_edit
boolean
read-only

Whether an admin may still edit this sent interview (before its first answer).

not_editable_reason
string | null
read-only

Why the interview can no longer be edited (answered, completed, archived, test run, not guided); null while can_edit is true.

last_edited_at
string<date-time> | null
read-only

When an admin last edited this sent interview.

last_edited_by_email
string<email> | null
read-only
sent_from_draft_id
string<uuid> | null
read-only

The draft this interview was sent from, when it was sent from one.

name
string | null

Interview title (auto-generated from the topic when not provided).

created_by
string<uuid>
read-only

UUID of the user who created the interview.

created_by_email
string<email> | null
read-only

Email of the user who created the interview (the importer, for imported interviews).

type
string

Conversation type: "interview" (standard), "guided-interview" (multi-topic), or "imported-interview" (a read-only transcript of an interview recorded outside the platform, created via the import-transcript endpoint).

type_additional_parameters
object

Free-form parameters associated with the conversation type. Assigned interviews carry planned_minutes (the planned length) among them.

chat_history
object[]

Ordered list of transcript entries (messages, tool calls, etc.).

chat_memory
object

Assistant memory state accumulated over the conversation. Server-only keys (respondent_profile, the respondent's profile as of the first turn) are omitted; sending one is a 400, and a write keeps the stored value.

local_documents
string<uuid>[]
read-only

UUIDs of documents scoped locally to this interview.

assigned_to
string<uuid> | null
read-only

UUID of the assigned user (null while a pending invite has not yet joined).

assigned_by
string<uuid> | null
read-only

UUID of the user who created the assignment.

assigned_to_email
string<email> | null
read-only

Assignee email, falling back to the invite email for not-yet-joined invitees.

assigned_by_email
string<email> | null
read-only
is_pending_invite
boolean
read-only

True when assigned to someone who has not yet joined the project.

topics
object[]
read-only

Guided interviews only: the ordered topic agenda seeded at assign time, with per-topic progress. Empty for every other interview type.

campaign
object | null

Campaign this interview belongs to; null for ad hoc interviews.

import_info
object | null

Parse-pipeline state of an imported external transcript (interviews of type "imported-interview"). Null on every other interview type. The raw submitted transcript is never returned — the parsed chat_history is the transcript.

meeting_info
object | null

Set on conversations of type meeting — the transcript of a call Clara attended as a bot. The conversation is created post-call, so this block is always complete when present. Every turn of such a transcript is role: user with a speaker name and a meeting_offset_ms; attribute by speaker.

status
enum<string> | null
read-only

Null for imported interviews until their transcript parse completes.

Available options:
pending,
in_progress,
completed
created_at
string<date-time>
read-only
updated_at
string<date-time>
read-only