Skip to main content
POST
Create a new interview

Authorizations

Authorization
string
header
required

Supabase JWT — Authorization: Bearer <token>.

Body

application/json
name
string
required

Interview / position name.

Minimum string length: 1
Example:

"Project manager"

location
string
required

Job location.

Minimum string length: 1
Example:

"remote"

interview_template_id
string<uuid>
required

Id of the interview template to base this interview on.

Minimum string length: 1
Example:

"baa3bf7c-6926-46fd-9005-16738a31f72d"

mojito_language_code
enum<string>
required

Platform language code used for the interview. Must be one of the platform-languages.json codes.

Available options:
ar,
bg,
zh,
hr,
cs,
da,
nl,
en,
fil,
fi,
fr,
de,
el,
hi,
hu,
id,
it,
ja,
ko,
ms,
no,
pl,
pt,
br,
ro,
ru,
sk,
es,
sv,
ta,
th,
tr,
uk,
vi
Example:

"en"

status
enum<string>
required

Lifecycle status of the interview. Options — draft: Created but not published — not visible to candidates and cannot be run yet. Use to stage an interview before going live. | active: Published and live — candidates can run it..

Available options:
draft,
active
Example:

"active"

type
enum<string>
required

Product type of the interview. Options — interview: Standard candidate interview for a role — answers are AI-scored and produce a hiring recommendation. | coaching: Practice/coaching session — candidate-facing feedback to help them improve; not a hiring evaluation. Only available on the coaching portal, NOT the interview portal. | assessment: Skills/knowledge assessment — evaluates competencies and is scored like an interview..

Available options:
interview,
coaching,
assessment
Example:

"interview"

visibility
enum<string>
required

Who can discover and access the interview. Options — merchant_public: Listed on the merchant's public interview list — anyone with the merchant link can find and start it. | merchant_invite: Invite-only — only candidates explicitly invited (by email/link) can access it; not listed anywhere. | merchant_unlisted: Reachable only via a direct link — not listed anywhere; share the link manually..

Available options:
merchant_public,
merchant_invite,
merchant_unlisted
Example:

"merchant_public"

recording
enum<string> | null

Cheating/proctoring detection mode for candidate answers — this is NOT a full session recording. Video options also record the candidate. Omit/null to disable. Options — audio_first_5_answers: Audio-only cheating detection, first 5 answers only. | audio_all: Audio-only cheating detection on every answer. | video_all: Audio + video cheating detection on every answer (candidate is recorded for all answers). | video_first_5_answers: Audio + video cheating detection, first 5 answers only..

Available options:
audio_first_5_answers,
audio_all,
video_all,
video_first_5_answers
Example:

"video_all"

recording_full_session
enum<string> | null

Full interview-session recording (includes the avatar and voice) produced as a single file. Independent of recording. Omit/null to disable. Options — audio_all: Record the whole session audio (avatar + candidate voice) into a single file. Adds +0.2 credits. | video_all: Record the whole session video + audio (avatar + candidate) into a single file. Adds +0.4 credits..

Available options:
audio_all,
video_all
Example:

"video_all"

interview_type
enum<string>

Interview style — configures the AI avatar and shapes both the AI-generated questions and the follow-up questions asked during the interview. Defaults to pre-screening when omitted. Options — pre-screening: Pre-screening — quick qualification check focusing on basic requirements and availability. | pre-screening-with-test-questions: Pre-screening with test questions — pre-screening plus practical questions to test relevant skills. | second-interview: Second round interview — deeper dive for candidates who passed initial screening. | remote-freelancer-verification: Remote worker verification — verify remote work capabilities and communication skills. | strength-based-interview: Strength-based interview — focus on what candidates enjoy and excel at to predict job satisfaction. | potential-based-interview: Potential-based interview — assess learning ability and growth potential rather than past experience. | process-verification-from-knowledge-base: Knowledge Base interview — generate questions from your knowledge base documents..

Available options:
pre-screening,
pre-screening-with-test-questions,
second-interview,
remote-freelancer-verification,
strength-based-interview,
potential-based-interview,
process-verification-from-knowledge-base
Example:

"pre-screening-with-test-questions"

seniority_level
enum<string> | null

Target seniority level for the role; auto-detected from the job description when omitted. Options — entry-level: Early-career or graduate roles. | intermediate: Some experience required. | senior: Experienced professional. | managerial: Team or department lead. | director: Director-level responsibility. | executive: C-suite or executive role..

Available options:
entry-level,
intermediate,
senior,
managerial,
director,
executive
Example:

"senior"

result_view
enum<string> | null

Result screen shown to the candidate after finishing. With any value other than none, the candidate sees a results screen where they can provide feedback, record an intro video and edit the transcript, and must then submit the result; the value sets how much score/result detail is shown. Options — none: No results screen at all — the interview is submitted immediately when the candidate finishes (no feedback, intro video, transcript edit or manual submit step). | minimal: Minimal results layout, no score shown. | minimal_with_score: Minimal results layout including the overall score. | advanced: Advanced results layout with more detail. | full: Full results layout with all sections. | full_expand_scores: Full results with every score breakdown expanded..

Available options:
none,
minimal,
minimal_with_score,
advanced,
full,
full_expand_scores
Example:

"full"

interview_conversation_speed
enum<string> | null

Conversation pace of the AI avatar. Omit/null keeps the template default pace. Options — slower: The avatar speaks more slowly — easier to follow for non-native speakers. | normal: Default speaking pace. | faster: The avatar speaks more quickly for a snappier conversation..

Available options:
slower,
normal,
faster
Example:

"normal"

candidate_video_introduction
enum<string> | null

Whether a candidate video introduction is optional or required.

Available options:
optional,
required
Example:

"optional"

interview_tone
string | null

Interview tone — configures the AI avatar's speaking style and the tone of the AI-generated questions and follow-ups; omit to default to relaxed. Suggested values — relaxed: Friendly and conversational tone that helps candidates feel at ease. | simple: Plain language at CEFR A2 level — short sentences and simple words. | professional: Formal and business-like approach suitable for senior roles. | persuasive: Engaging style that encourages candidates to elaborate.. Case-insensitive; other strings are accepted but unknown tones fall back to the default.

Example:

"professional"

interview_length

Number of questions to generate (max 40).

Example:

8

interview_attempts
number | null

Allowed candidate attempts (1-20).

Required range: 1 <= x <= 20
Example:

1

max_duration
number | null

Maximum interview duration in minutes used to scope question generation.

Example:

30

max_followups
integer | null

Maximum number of AI follow-up questions. 0 disables follow-ups; presets are 0-3 (none/low/normal/high) and custom values start at 4; null uses the template default (Normal).

Required range: 0 <= x <= 999
Example:

2

questions_random_subset
number | null

Ask only a random subset of the questions, expressed as a fraction between 0.01 and 0.9 (e.g. 0.5 = 50%). null asks all questions.

Required range: 0.01 <= x <= 0.9
Example:

0.5

code
string | null

Optional external code/reference for the interview.

Example:

"my code"

cover_image_url
string | null

Cover image URL.

Example:

"https://example.com/cover.png"

interview_department
string | null

Department the position belongs to.

Example:

"Engineering"

interview_salary
string | null

Salary range shown for the position.

Example:

"$80k - $100k"

interview_available_till
string | null

ISO date/time after which the interview is no longer available to candidates. null keeps it always available.

Example:

"2026-12-31"

recruiter_profile_id
string | null

Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant.

Example:

"28106cba-1c27-4e53-b149-32113e5e8e31"

hiring_for_company
object | null

Who the position is really for. Omit/null (or an object with name null/blank) when hiring for yourself; { name: 'undisclosed' } for an unnamed external client; or { name: '' } plus optional description/location/sector/company_size for a named client. Stored in creation_parameters.hiring_for_company.

Example:
tags
string[] | null

Free-form tags stored on the interview.

Example:
merchant_id
string | null

Merchant id. Admin / sub-merchant callers only; otherwise taken from your token.

Example:

"28106cba-1c27-4e53-b149-32113e5e8e31"

knowledge_base_store_id
string | null

Knowledge base store id to source additional context from.

description
string | null

Short job description (regenerated by AI).

description_long
string | null

Long job description.

candidate_expectations
string | null

Free-text candidate expectations folded into AI generation.

welcome_message
string | null

Custom welcome message shown to the candidate.

thank_you_message
string | null

Custom thank-you message shown after the interview.

additional_context
object | null

Arbitrary additional context object merged into AI generation.

instructional_video_custom_text
string | null

Custom narration text for the instructional video.

is_embedded
boolean | null

Set true when the interview will be embedded as an iframe on an external page. Provisions an embed key and returns embed_id / embed_signing_key, which are used to authenticate/sign the iframe embed.

Example:

false

include_rapport_question
boolean | null

Include an opening rapport question. Defaults to false.

Example:

true

include_closing_prompt
boolean | null

Include a closing prompt. Defaults to true.

Example:

true

instructional_video
boolean | null

Show an instructional video before approval. Defaults to false.

Example:

true

use_enhanced_expectations
boolean | null

Reserved flag passed through to generation.

required_pronunciation
boolean | null

Require pronunciation assessment (restricts to pronunciation-capable languages). Defaults to false.

Example:

false

result_enable_edit_transcript
boolean | null

Allow editing the transcript on the result view. Defaults to true.

Example:

true

custom_scoring
object | null

Custom result-scoring overrides merged with defaults and template overrides.

pdf_export_auto_config
object | null

Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export.

Response

Interview created.

Id of the created interview. Includes embed_id/embed_signing_key when is_embedded=true.

interview_def_set_id
string
required

Id of the newly created interview definition set.

Example:

"00000000-0000-0000-0000-000000000000"

embed_id
string

Embed id, present only when is_embedded=true.

embed_signing_key
string

Embed signing key, present only when is_embedded=true.