create_interview_from_questions

{
  "type": "object",
  "properties": {
    "name": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "description": "Interview/position name.",
      "example": "Project manager"
    },
    "location": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "description": "Interview location.",
      "example": "remote"
    },
    "interview_template_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "description": "Id of the interview template to use. Must reference an existing interview_templates row.",
      "example": "46b98d37-1557-4391-beca-03037ead19f2"
    },
    "mojito_language_code": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "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
      ],
      "description": "Platform language code (one of the platform-languages.json codes); must also resolve to a supported language with an Azure speech mapping.",
      "example": "en"
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "description": "Short interview description.",
      "example": "Project manager role"
    },
    "status": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "draft",
        "active",
        null
      ],
      "description": "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..",
      "example": "active"
    },
    "type": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "interview",
        "coaching",
        "assessment",
        null
      ],
      "description": "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..",
      "example": "interview"
    },
    "visibility": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "merchant_public",
        "merchant_invite",
        "merchant_unlisted",
        null
      ],
      "description": "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..",
      "example": "merchant_public"
    },
    "questions": {
      "items": {
        "properties": {
          "question": {
            "type": [
              "string",
              "null"
            ],
            "description": "The question text shown to the candidate."
          },
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "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."
          },
          "duration": {
            "type": [
              "number",
              "null"
            ],
            "description": "Answer duration in seconds for this question."
          },
          "mojito_language_code": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "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
            ],
            "description": "Per-question language override (one of the platform-languages.json codes). Inherits the interview language when omitted.",
            "example": "en"
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional label/tag stored on the question."
          },
          "is_conditional": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Conditional follow-up question (view 'with listening conditional'). Use with conditional_question_main_id."
          },
          "is_without_scoring": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Question is asked but not scored (view 'without scoring')."
          },
          "is_candidate_asking_recruiter": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Candidate-asks-recruiter prompt (view 'candidate asking recruiter')."
          },
          "is_expert": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Expert listening question (view 'with listening expert')."
          },
          "is_multiple_choice": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Multiple-choice question (view 'multiple choice')."
          },
          "question_alternatives": {
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ],
            "description": "Alternative phrasings for the question."
          },
          "conditional_question_main_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "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."
          },
          "knowledge_base_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Knowledge-base store id (uuid) the question draws context from."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "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."
          },
          "external_data": {
            "additionalProperties": {},
            "type": [
              "object",
              "null"
            ],
            "description": "Arbitrary JSON metadata stored on the question."
          },
          "candidate_expectations_json": {
            "properties": {
              "weak": {
                "items": {
                  "type": "string"
                },
                "type": [
                  "array",
                  "null"
                ],
                "description": "Baseline requirements every viable candidate should meet (table stakes)."
              },
              "moderate": {
                "items": {
                  "type": "string"
                },
                "type": [
                  "array",
                  "null"
                ],
                "description": "Requirements expected of a solid, competent candidate."
              },
              "strong": {
                "items": {
                  "type": "string"
                },
                "type": [
                  "array",
                  "null"
                ],
                "description": "High-bar requirements only standout candidates clear."
              }
            },
            "type": [
              "object",
              "null"
            ],
            "description": "Per-question candidate expectations, bucketed by requirement level (weak/moderate/strong). Extra keys are preserved."
          }
        },
        "additionalProperties": {},
        "type": "object",
        "required": [
          "question"
        ]
      },
      "type": [
        "array",
        "null"
      ],
      "minItems": 1,
      "description": "Ordered list of interview questions to create as steps."
    },
    "recording": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "audio_first_5_answers",
        "audio_all",
        "video_all",
        "video_first_5_answers",
        null
      ],
      "description": "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..",
      "example": "video_all"
    },
    "recording_full_session": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "audio_all",
        "video_all",
        null
      ],
      "description": "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..",
      "example": "video_all"
    },
    "interview_type": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "pre-screening",
        "pre-screening-with-test-questions",
        "second-interview",
        "remote-freelancer-verification",
        "strength-based-interview",
        "potential-based-interview",
        "process-verification-from-knowledge-base",
        null
      ],
      "description": "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..",
      "example": "pre-screening-with-test-questions"
    },
    "seniority_level": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "entry-level",
        "intermediate",
        "senior",
        "managerial",
        "director",
        "executive",
        null
      ],
      "description": "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..",
      "example": "senior"
    },
    "result_view": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "none",
        "minimal",
        "minimal_with_score",
        "advanced",
        "full",
        "full_expand_scores",
        null
      ],
      "description": "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..",
      "example": "full"
    },
    "interview_conversation_speed": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "slower",
        "normal",
        "faster",
        null
      ],
      "description": "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..",
      "example": "normal"
    },
    "candidate_video_introduction": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "optional",
        "required",
        null
      ],
      "description": "Whether a candidate video introduction is optional or required."
    },
    "interview_tone": {
      "type": [
        "string",
        "null"
      ],
      "description": "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.",
      "example": "professional"
    },
    "interview_attempts": {
      "type": [
        "number",
        "null"
      ],
      "description": "Allowed attempts, 1-20.",
      "example": 1
    },
    "questions_random_subset": {
      "type": [
        "number",
        "null"
      ],
      "description": "Fraction of questions to randomly ask, between 0.01 and 0.9."
    },
    "max_followups": {
      "type": [
        "integer",
        "null"
      ],
      "maximum": 999,
      "minimum": 0,
      "description": "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).",
      "example": 2
    },
    "code": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional external code/reference."
    },
    "cover_image_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cover image URL."
    },
    "interview_department": {
      "type": [
        "string",
        "null"
      ],
      "description": "Department the position belongs to.",
      "example": "Engineering"
    },
    "interview_salary": {
      "type": [
        "string",
        "null"
      ],
      "description": "Salary range shown for the position.",
      "example": "$80k - $100k"
    },
    "interview_available_till": {
      "type": [
        "string",
        "null"
      ],
      "description": "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": {
      "type": [
        "string",
        "null"
      ],
      "description": "Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant."
    },
    "hiring_for_company": {
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "End-employer name. Omit/null when hiring for yourself, 'undisclosed' for an unnamed external client, or the client's company name.",
          "example": "Unimo Enterprises"
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Short description of the end employer, used as background context by the agent.",
          "example": "Unimo Enterprises is a leading logistics and supply chain solutions provider."
        },
        "location": {
          "type": [
            "string",
            "null"
          ],
          "description": "Primary location of the end employer.",
          "example": "Sri Lanka"
        },
        "sector": {
          "type": [
            "string",
            "null"
          ],
          "description": "Industry / sector of the end employer.",
          "example": "Logistics and Supply Chain"
        },
        "company_size": {
          "type": [
            "string",
            "null"
          ],
          "description": "Approximate headcount of the end employer.",
          "example": "100-200"
        }
      },
      "type": [
        "object",
        "null"
      ],
      "description": "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.",
      "example": {
        "name": "undisclosed"
      }
    },
    "tags": {
      "items": {
        "type": "string"
      },
      "type": [
        "array",
        "null"
      ],
      "description": "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.",
      "example": [
        "interview-practice",
        "sales"
      ]
    },
    "required_pronunciation": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Require pronunciation assessment (restricts to pronunciation-capable languages). Defaults to false.",
      "example": false
    },
    "result_enable_edit_transcript": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Allow editing the transcript on the result view. Defaults to true.",
      "example": true
    },
    "pdf_export_auto_config": {
      "properties": {
        "mojito_language_code": {
          "type": [
            "string",
            "null"
          ],
          "description": "Report language code (platform-languages.json code).",
          "example": "en"
        },
        "contact_details": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include candidate contact details."
        },
        "ai_recruiter_assessment": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the AI recruiter assessment."
        },
        "ai_scoring_rubric": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the AI scoring rubric."
        },
        "analytics": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include analytics."
        },
        "files": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include uploaded candidate files."
        },
        "transcript": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the interview transcript."
        },
        "answer_recording": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include per-answer recordings."
        },
        "session_recording": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the full-session recording."
        },
        "group_by_question": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Group transcript answers by expected question."
        },
        "template": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "classic",
            "modern",
            "one_pager",
            null
          ],
          "description": "Report layout: classic (default), modern, or one_pager."
        }
      },
      "type": [
        "object",
        "null"
      ],
      "description": "Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export."
    },
    "knowledge_base_store_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional knowledge base store id; validated for existence."
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Target merchant id (admins / sub-merchant only)."
    },
    "description_long": {
      "type": [
        "string",
        "null"
      ],
      "description": "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"
    },
    "candidate_expectations": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-text candidate expectations."
    },
    "candidate_expectations_json": {
      "properties": {
        "weak": {
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ],
          "description": "Baseline requirements every viable candidate should meet (table stakes)."
        },
        "moderate": {
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ],
          "description": "Requirements expected of a solid, competent candidate."
        },
        "strong": {
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ],
          "description": "High-bar requirements only standout candidates clear."
        }
      },
      "type": [
        "object",
        "null"
      ],
      "description": "Pre-generated candidate expectations, bucketed by requirement level (weak/moderate/strong); auto-generated when omitted for type=interview. Extra keys are preserved."
    },
    "custom_scoring": {
      "additionalProperties": {},
      "type": [
        "object",
        "null"
      ],
      "description": "Custom scoring overrides merged with defaults."
    },
    "additional_context": {
      "additionalProperties": {},
      "type": [
        "object",
        "null"
      ],
      "description": "Extra context forwarded to expectation generation."
    },
    "instructional_video": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Enable an instructional video before approval."
    },
    "instructional_video_custom_text": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom text for the instructional video."
    },
    "disable_deduplication": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "When true, skip step deduplication on insert."
    },
    "welcome_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom welcome message."
    },
    "thank_you_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom thank-you message."
    },
    "is_embedded": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "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."
    }
  },
  "required": [
    "name",
    "location",
    "interview_template_id",
    "mojito_language_code",
    "description",
    "status",
    "type",
    "visibility",
    "questions"
  ]
}