create_interview

{
  "type": "object",
  "properties": {
    "name": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "description": "Interview / position name.",
      "example": "Project manager"
    },
    "location": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "description": "Job location.",
      "example": "remote"
    },
    "interview_template_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "format": "uuid",
      "description": "Id of the interview template to base this interview on.",
      "example": "baa3bf7c-6926-46fd-9005-16738a31f72d"
    },
    "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 used for the interview. Must be one of the platform-languages.json codes.",
      "example": "en"
    },
    "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"
    },
    "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 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..",
      "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.",
      "example": "optional"
    },
    "interview_tone": {
      "type": [
        "string",
        "null"
      ],
      "description": "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": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {}
      ],
      "description": "Number of questions to generate (1-40). Also capped by max_duration, which allows one question per 2 minutes: 20 min -> 10 questions, 30 min -> 15, 45 min -> 22, 60 min -> 30, 80 min -> 40. Asking for more than the cap is not an error — you get the cap, and the response reports the real count in questions_generated. Omit this field to let the AI pick 5-8.",
      "example": 8
    },
    "interview_attempts": {
      "type": [
        "number",
        "null"
      ],
      "maximum": 20,
      "minimum": 1,
      "description": "Allowed candidate attempts (1-20).",
      "example": 1
    },
    "max_duration": {
      "type": [
        "number",
        "null"
      ],
      "description": "Maximum interview duration in seconds. Scopes how many questions are generated (see interview_length) and is stored on the interview as the live session limit and the basis for the credit multiplier. Defaults to 1200 (20 minutes) when omitted.",
      "example": 1200
    },
    "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
    },
    "questions_random_subset": {
      "type": [
        "number",
        "null"
      ],
      "maximum": 0.9,
      "minimum": 0.01,
      "description": "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.",
      "example": 0.5
    },
    "code": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional external code/reference for the interview.",
      "example": "my code"
    },
    "cover_image_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cover image URL.",
      "example": "https://example.com/cover.png"
    },
    "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.",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31"
    },
    "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"
      ]
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Merchant id. Admin / sub-merchant callers only; otherwise taken from your token.",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31"
    },
    "knowledge_base_store_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Knowledge base store id to source additional context from."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Short, two-sentence job description shown to the candidate. Provide it to use it as-is; leave it null/blank and it is AI-generated from the position name and any other context.",
      "example": "Backend role focused on Python, async APIs, and AWS."
    },
    "description_long": {
      "type": [
        "string",
        "null"
      ],
      "description": "Full job description in Markdown (Job Purpose, Responsibilities, Required & Preferred Qualifications). Provide it to use it as-is; leave it null/blank and it is AI-generated (interview and assessment types only). 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 folded into AI generation."
    },
    "welcome_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom welcome message shown to the candidate."
    },
    "thank_you_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom thank-you message shown after the interview."
    },
    "additional_context": {
      "additionalProperties": {},
      "type": [
        "object",
        "null"
      ],
      "description": "Arbitrary additional context object merged into AI generation."
    },
    "instructional_video_custom_text": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom narration text for the instructional video."
    },
    "is_embedded": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "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": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Include an opening rapport question. Defaults to false.",
      "example": true
    },
    "include_closing_prompt": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Include a closing prompt. Defaults to true.",
      "example": true
    },
    "instructional_video": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Show an instructional video before approval. Defaults to false.",
      "example": true
    },
    "use_enhanced_expectations": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Reserved flag passed through to generation."
    },
    "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
    },
    "custom_scoring": {
      "additionalProperties": {},
      "type": [
        "object",
        "null"
      ],
      "description": "Custom result-scoring overrides merged with defaults and template overrides."
    },
    "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."
    }
  },
  "required": [
    "name",
    "location",
    "interview_template_id",
    "mojito_language_code",
    "status",
    "type",
    "visibility"
  ]
}