Skip to main content
Glama

Create interview from questions

create_interview_from_questions
Destructive

[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
NameRequiredDescriptionDefault
codeNoOptional external code/reference.
nameYesInterview/position name.
tagsNoFree-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.
typeYesProduct 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..
statusYesLifecycle 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..
locationYesJob location — a city/country, or `remote`. Required and must not be empty: when the job description gives no location, pass `Not specified`.
questionsYesOrdered list of interview questions to create as steps.
recordingNoCheating/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..
visibilityYesWho 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..
descriptionYesShort interview description.
environmentNoWhich 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_embeddedNoSet 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_idNoTarget merchant id (admins / sub-merchant only).
result_viewNoResult 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_followupsNoMaximum 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_scoringNoCustom scoring overrides merged with defaults.
interview_toneNoTone — 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_typeNoInterview 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. | `knockout-screening`: Knock-out screening — a short (about 5 minute) check of the role's must-haves with closed questions; ends early, politely, when a must-have is clearly not met. On creation it defaults custom_scoring.early_stop to true (where the avatar supports early stop) and max_followups to 1 unless you send them..
conversation_idNoPass 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_urlNoCover image URL.
seniority_levelNoTarget 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_messageNoCustom welcome message.
description_longNoLong-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_salaryNoSalary range shown for the position.
thank_you_messageNoCustom thank-you message.
additional_contextNoExtra context forwarded to expectation generation.
hiring_for_companyNoWho 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_attemptsNoAllowed attempts, 1-20.
instructional_videoNoEnable an instructional video before approval.
interview_departmentNoDepartment the position belongs to.
mojito_language_codeYesPlatform language code (one of the platform-languages.json codes); must also resolve to a supported language with an Azure speech mapping.
recruiter_profile_idNoProfile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant.
disable_deduplicationNoWhen true, skip step deduplication on insert.
interview_template_idYesId of the interview template to use. Must reference an existing interview_templates row.
candidate_expectationsNoFree-text candidate expectations.
pdf_export_auto_configNoAuto-generate a candidate PDF report with these options once the interview completes. null disables auto-export.
recording_full_sessionNoFull 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_pronunciationNoRequire pronunciation assessment (restricts to pronunciation-capable languages). Defaults to false.
knowledge_base_store_idNoOptional knowledge base store id; validated for existence.
questions_random_subsetNoFraction of questions to randomly ask, between 0.01 and 0.9.
interview_available_tillNoISO date/time after which the interview is no longer available to candidates. null keeps it always available.
candidate_expectations_jsonNoPre-generated candidate expectations, bucketed by requirement level (weak/moderate/strong); auto-generated when omitted for type=interview. Extra keys are preserved.
candidate_video_introductionNoWhether a candidate video introduction is optional or required.
interview_conversation_speedNoConversation 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_transcriptNoAllow editing the transcript on the result view. Defaults to true.
instructional_video_custom_textNoCustom text for the instructional video.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
embed_idNoEmbed id, present only when is_embedded=true.
_mcp_instructionsNoServer-issued metadata for this conversation.
embed_signing_keyNoEmbed signing key, present only when is_embedded=true.
interview_def_set_idYesId of the newly created interview definition set.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / interview_type / description
      Previous value: -"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.."New value: +"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. | `knockout-screening`: Knock-out screening — a short (about 5 minute) check of the role's must-haves with closed questions; ends early, politely, when a must-have is clearly not met. On creation it defaults custom_scoring.early_stop to true (where the avatar supports early stop) and max_followups to 1 unless you send them.."
    • changedInput schema / properties / interview_type / enum
      Previous value: -[
      -  "pre-screening",
      -  "pre-screening-with-test-questions",
      -  "second-interview",
      -  "remote-freelancer-verification",
      -  "strength-based-interview",
      -  "potential-based-interview",
      -  "process-verification-from-knowledge-base",
      -  null
      -]New value: +[
      +  "pre-screening",
      +  "pre-screening-with-test-questions",
      +  "second-interview",
      +  "remote-freelancer-verification",
      +  "strength-based-interview",
      +  "potential-based-interview",
      +  "process-verification-from-knowledge-base",
      +  "knockout-screening",
      +  null
      +]
  2. Changed1 schema field changed
    • changedInput schema / properties / conversation_id / description
      Previous value: -"Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it."New value: +"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."
  3. Changed2 schema fields changed
    • addedInput schema / properties / conversation_id
      Added value: +{
      +  "description": "Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / _mcp_instructions
      Added value: +{
      +  "description": "Server-issued metadata for this conversation.",
      +  "properties": {
      +    "conversation_id": {
      +      "description": "The server-issued conversation identifier.",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  4. Changed5 schema fields changed
    • changedInput schema / properties / interview_tone / description
      Previous value: -"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."New value: +"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.."
    • addedInput schema / properties / interview_tone / enum
      Added value: +[
      +  "relaxed",
      +  "simple",
      +  "professional",
      +  "persuasive",
      +  "exact",
      +  null
      +]
    • changedInput schema / properties / location / description
      Previous value: -"Interview location."New value: +"Job location — a city/country, or `remote`. Required and must not be empty: when the job description gives no location, pass `Not specified`."
    • changedInput schema / properties / pdf_export_auto_config / properties / mojito_language_code / description
      Previous value: -"Report language code (platform-languages.json code)."New value: +"Report language code (a platform-languages.json code)."
    • addedInput schema / properties / pdf_export_auto_config / properties / mojito_language_code / enum
      Added value: +[
      +  "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",
      +  null
      +]
  5. Changed1 schema field changed
    • addedInput schema / properties / environment
      Added value: +{
      +  "description": "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..",
      +  "enum": [
      +    "production",
      +    "uat",
      +    "development",
      +    "demo",
      +    null
      +  ],
      +  "example": "production",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  6. Changed1 schema field changed
    • changedInput schema / properties / pdf_export_auto_config / properties / template / description
      Previous value: -"Report layout: classic (default), modern, or one_pager."New value: +"Report layout: classic, modern, or one_pager. Omit for the merchant default (modern when unset)."
  7. Changed1 schema field changed
    • addedInput schema / properties / pdf_export_auto_config / properties / template
      Added value: +{
      +  "description": "Report layout: classic (default), modern, or one_pager.",
      +  "enum": [
      +    "classic",
      +    "modern",
      +    "one_pager",
      +    null
      +  ],
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  8. Changed1 schema field changed
    • changedInput schema / properties / description_long / description
      Previous value: -"Long-form interview description."New value: +"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"
  9. Changed3 schema fields changed
    • changedInput schema / properties / questions / items / properties / conditional_question_main_id / description
      Previous value: -"For a conditional question, the id (the local \"id\" field above) of the parent question in this same array that triggers it."New value: +"For a conditional question, the id (the \"id\" field above) of the parent question in this same array that triggers it. The parent must appear earlier in the array than the conditional question referencing it."
    • changedInput schema / properties / questions / items / properties / external_id / description
      Previous value: -"External identifier stored on the question."New value: +"External identifier stored on the question. job-interview-update matches on this first, so an ATS that owns stable ids can send its own array and have the diff line up without round-tripping our ids."
    • changedInput schema / properties / questions / items / properties / id / description
      Previous value: -"Caller-local identifier for this question. Only needed when another question references it via conditional_question_main_id (the mapping is resolved within this array)."New value: +"Identifier for this question. job-interview-get returns the question's real id here; send it back to job-interview-update so an unchanged question keeps its existing record (and with it its answer rules and any rendered avatar video). Also the handle another question references via conditional_question_main_id. On job-interview-create-from-array it is a caller-local value, only needed for those references."
  10. Changed2 schema fields changed
    • changedInput schema / properties / tags / description
      Previous value: -"Free-form tags stored on the interview."New value: +"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."
    • changedInput schema / properties / tags / example
      Previous value: -[
      -  "engineering",
      -  "remote"
      -]New value: +[
      +  "interview-practice",
      +  "sales"
      +]
  11. First observed

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the write/destructive/open-world profile, and the description adds real behavior beyond them: the AI rephrases caller wording by default, the tool builds default and generated steps (not just the literal array), and it optionally activates the interview and optionally creates an embed key. It omits credit cost and non-idempotency, but the disclosure is solid given the annotations carry the safety burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is front-loaded and the tone caveat is well placed, but the second sentence largely restates the first ('create ... from an explicit array of questions' vs 'Creates ... from a caller-provided array of questions'), spending a full paragraph on information already conveyed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 46 parameters, an output schema present, and safety annotations supplied, the description covers the essential mental model: it is a create-from-array operation with AI rephrasing by default, deferred step generation, and optional activation/embed. Return values are handled by the output schema and parameter details by the fully covered schema, so remaining gaps are minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, and the description earns an increment by surfacing the single most consequential parameter decision — the default rephrasing vs. interview_tone="exact" for scripted wording — which is the primary way an agent can get this call wrong across 46 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Create a new interview from an explicit array of questions') and the qualifier 'explicit array of questions' implicitly distinguishes it from the sibling create_interview, which generates questions from a job description. However, it never names that sibling, so the agent must infer the contrast from the phrase alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a genuinely useful conditional for one decision — use interview_tone="exact" when the wording is a script (compliance, translated, legally reviewed). But there is no tool-level when-to-use guidance: nothing says when to pick this over create_interview, nor what the prerequisites (template id, language) are. Usage is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.