Create an interview from an array of questions
Creates a new interview definition set from a caller-provided array of questions, builds its default and generated steps, optionally activates it, and optionally creates an embed key.
Authorizations
Supabase JWT — Authorization: Bearer <token>.
Body
Interview/position name.
1"Project manager"
Interview location.
1"remote"
Id of the interview template to use. Must reference an existing interview_templates row.
1"46b98d37-1557-4391-beca-03037ead19f2"
Platform language code (one of the platform-languages.json codes); must also resolve to a supported language with an Azure speech mapping.
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 "en"
Short interview description.
1"Project manager role"
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..
draft, active "active"
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..
interview, coaching, assessment "interview"
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..
merchant_public, merchant_invite, merchant_unlisted "merchant_public"
Ordered list of interview questions to create as steps.
1Cheating/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..
audio_first_5_answers, audio_all, video_all, video_first_5_answers "video_all"
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..
audio_all, video_all "video_all"
Interview style — configures the AI avatar and the follow-up questions it generates during the interview. The base questions you supply are used as-is and are NOT affected by this setting. 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..
pre-screening, pre-screening-with-test-questions, second-interview, remote-freelancer-verification, strength-based-interview, potential-based-interview, process-verification-from-knowledge-base "pre-screening-with-test-questions"
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..
entry-level, intermediate, senior, managerial, director, executive "senior"
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..
none, minimal, minimal_with_score, advanced, full, full_expand_scores "full"
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..
slower, normal, faster "normal"
Whether a candidate video introduction is optional or required.
optional, required Tone — configures the AI avatar's speaking style and the follow-up questions it generates; the base questions you supply are not affected. 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.
"professional"
Allowed attempts, 1-20.
1
Fraction of questions to randomly ask, between 0.01 and 0.9.
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).
0 <= x <= 9992
Optional external code/reference.
Cover image URL.
Department the position belongs to.
"Engineering"
Salary range shown for the position.
"$80k - $100k"
ISO date/time after which the interview is no longer available to candidates. null keeps it always available.
"2026-12-31"
Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant.
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.
Free-form tags stored on the interview. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's tags_interview_set_filter. Only active sessions with visibility public or merchant_public are listed.
Require pronunciation assessment (restricts to pronunciation-capable languages). Defaults to false.
false
Allow editing the transcript on the result view. Defaults to true.
true
Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export.
Optional knowledge base store id; validated for existence.
Target merchant id (admins / sub-merchant only).
Long-form interview description.
Free-text candidate expectations.
Pre-generated candidate expectations, bucketed by requirement level (weak/moderate/strong); auto-generated when omitted for type=interview. Extra keys are preserved.
Custom scoring overrides merged with defaults.
Extra context forwarded to expectation generation.
Enable an instructional video before approval.
Custom text for the instructional video.
When true, skip step deduplication on insert.
Custom welcome message.
Custom thank-you message.
Set true when the interview will be embedded as an iframe on an external page. Creates an embed key and returns embed_id/embed_signing_key, used to authenticate/sign the iframe embed.
Response
Interview created.
The created interview definition set id, plus embed credentials when is_embedded=true.