Create interview from questions
create_interview_from_questionsDestructive
[Interviews] Create a new interview from an explicit array of questions. The AI rephrases your wording by default; pass interview_tone="exact" to have each question asked verbatim, which is what you want when the wording is a script (compliance, translated, or legally reviewed text).
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Optional external code/reference. | |
| name | Yes | Interview/position name. | |
| tags | No | 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. | |
| type | Yes | 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.. | |
| status | Yes | 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.. | |
| location | Yes | Job location — a city/country, or `remote`. Required and must not be empty: when the job description gives no location, pass `Not specified`. | |
| questions | Yes | Ordered list of interview questions to create as steps. | |
| recording | No | 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.. | |
| visibility | Yes | 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.. | |
| description | Yes | Short interview description. | |
| environment | No | Which of your webhook environments results from this interview are delivered to. Defaults to production. Options — `production`: Live hiring. Results reach the webhooks configured as production. This is the default when the field is omitted. | `uat`: User-acceptance testing - an isolated environment for pre-release verification. | `development`: Development/testing. Use for interviews created by a test or preview app so their results never reach the production webhook. | `demo`: Demonstrations and sales trials.. | |
| is_embedded | No | 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. | |
| merchant_id | No | Target merchant id (admins / sub-merchant only). | |
| result_view | No | 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.. | |
| max_followups | No | 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). | |
| custom_scoring | No | Custom scoring overrides merged with defaults. | |
| interview_tone | No | Tone — configures the AI avatar's speaking style and the follow-up questions it generates; the base `questions` you supply are not affected. Case-insensitive; omit to default to relaxed. Options — `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. | `exact`: Asks the questions exactly as provided, without rephrasing — for interviews built from your own questions (create_interview_from_questions) where the wording is a script.. | |
| interview_type | No | 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.. | |
| conversation_id | No | Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request. | |
| cover_image_url | No | Cover image URL. | |
| seniority_level | No | 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.. | |
| welcome_message | No | Custom welcome message. | |
| description_long | No | Long-form interview description. Rendered as Markdown on the candidate-facing position page, including chips, callouts, cards, columns and buttons — formatting guide: https://developer.jobmojito.com/cookbooks/format-content-with-markdown | |
| interview_salary | No | Salary range shown for the position. | |
| thank_you_message | No | Custom thank-you message. | |
| additional_context | No | Extra context forwarded to expectation generation. | |
| hiring_for_company | No | 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: '<company>' } plus optional description/location/sector/company_size for a named client. Stored in creation_parameters.hiring_for_company. | |
| interview_attempts | No | Allowed attempts, 1-20. | |
| instructional_video | No | Enable an instructional video before approval. | |
| interview_department | No | Department the position belongs to. | |
| mojito_language_code | Yes | Platform language code (one of the platform-languages.json codes); must also resolve to a supported language with an Azure speech mapping. | |
| recruiter_profile_id | No | Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant. | |
| disable_deduplication | No | When true, skip step deduplication on insert. | |
| interview_template_id | Yes | Id of the interview template to use. Must reference an existing interview_templates row. | |
| candidate_expectations | No | Free-text candidate expectations. | |
| pdf_export_auto_config | No | Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export. | |
| recording_full_session | No | 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.. | |
| required_pronunciation | No | Require pronunciation assessment (restricts to pronunciation-capable languages). Defaults to false. | |
| knowledge_base_store_id | No | Optional knowledge base store id; validated for existence. | |
| questions_random_subset | No | Fraction of questions to randomly ask, between 0.01 and 0.9. | |
| interview_available_till | No | ISO date/time after which the interview is no longer available to candidates. null keeps it always available. | |
| candidate_expectations_json | No | Pre-generated candidate expectations, bucketed by requirement level (weak/moderate/strong); auto-generated when omitted for type=interview. Extra keys are preserved. | |
| candidate_video_introduction | No | Whether a candidate video introduction is optional or required. | |
| interview_conversation_speed | No | 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.. | |
| result_enable_edit_transcript | No | Allow editing the transcript on the result view. Defaults to true. | |
| instructional_video_custom_text | No | Custom text for the instructional video. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| embed_id | No | Embed id, present only when is_embedded=true. | |
| _mcp_instructions | No | Server-issued metadata for this conversation. | |
| embed_signing_key | No | Embed signing key, present only when is_embedded=true. | |
| interview_def_set_id | Yes | Id of the newly created interview definition set. |