Skip to main content
There are three ways to create an interview, depending on how much you want JobMojito to generate for you:
You provideUseMCP tool
A job description → AI generates questionsPOST /job-interview-createcreate_interview
Your own list of questionsPOST /job-interview-create-from-arraycreate_interview_from_questions
A candidate + position, get a ready link backPOST /job-interview-create-for-candidate-with-tokencreate_interview_for_candidate
You’ll need an interview_template_id. List your available templates with GET /merchant-avatar-list (MCP tool list_avatars) and pick one.

​
The template picks the interview modality

The interview_template_id is not just cosmetic — the template’s type decides whether the candidate gets a voice-only or an avatar experience. Choose it deliberately; there is no separate “voice or avatar” flag on the create call.
Template type (from list_avatars)Candidate experience
interactive_elevenlabsVoice-only — realtime conversation, no video avatar.
interactive_heygenRealtime interactive avatar — a talking video avatar.
offline_heygenNon-interactive avatar — pre-recorded avatar video (no live back-and-forth).
offline_elai and offline_synthesia are legacy integrations. They may still appear in list_avatars for older accounts, but they cannot be used to create new interviews — only offline_heygen is supported for the pre-recorded modality.
Filter directly to the modality you want: GET /merchant-avatar-list?type=interactive_elevenlabs for voice-only, or ?type=interactive_heygen for a realtime avatar. The item’s id is the interview_template_id you pass below.
Some options only work on avatar templates. On a voice-only (interactive_elevenlabs) template, early_stop scoring and instructional_video are unsupported and the create call returns 422. Pick an interactive_heygen template if you need those.
To confirm the modality of an interview you’ve already created, read it back with get_interview_definition (POST /job-interview-get) — the response includes interview_template_type and a convenience is_voice_only boolean.

​
Option A — from a job position (AI-generated questions)

JobMojito writes the description, questions, and candidate expectations for you.
1

Choose a template

Call GET /merchant-avatar-list and note an interview_template_id.
2

Create the interview

Send the position details. The required fields are name, location, interview_template_id, mojito_language_code, status, type, and visibility.
curl -X POST https://cool.jobmojito.com/functions/v1/job-interview-create \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Backend Engineer",
    "location": "Remote (EU)",
    "interview_template_id": "TEMPLATE_UUID",
    "mojito_language_code": "en",
    "status": "active",
    "type": "interview",
    "visibility": "merchant_invite",
    "interview_type": "pre-screening",
    "seniority_level": "senior",
    "interview_length": 8,
    "description": "Backend role focused on Python, async APIs, and AWS.",
    "candidate_expectations": "5+ yrs Python, REST/async, cloud, SQL."
  }'
3

Personalize the candidate experience & scoring (optional but recommended)

The defaults are generic. In the same create call, set these fields to tailor the interview — they are easy to forget:
  • welcome_message — the custom message shown to the candidate before they start. Set it to greet the candidate and set expectations.
  • thank_you_message — the custom message shown after they finish.
  • custom_scoring — an object of result-scoring overrides (your custom rubric). It is merged over the platform defaults and any template overrides, so you only need to include what you want to change. Omit it to use the template/default scoring.
{
  "welcome_message": "Welcome! This is a 15-minute screen for the Senior Backend role. Answer out loud; there are no trick questions.",
  "thank_you_message": "Thanks for your time — our team will review your responses and be in touch within a week.",
  "custom_scoring": {
    "criteria": [
      { "name": "System design", "weight": 40 },
      { "name": "Coding fundamentals", "weight": 40 },
      { "name": "Communication", "weight": 20 }
    ]
  }
}
custom_scoring is a free-form overrides object — its exact shape follows your account’s scoring model. Fetch an existing interview with get_interview_definition to see the current scoring structure before overriding it.
4

Capture the interview id

The response returns interview_def_set_id — keep it; you’ll use it to invite candidates and review results. Note it is passed back to other endpoints under different field names (position_id, interview_id) — see Identifiers & admin links.
{ "interview_def_set_id": "9c1b…e4f2" }

​
Key fields

FieldRequiredNotes
name, location✓Position title and location.
interview_template_id✓Template id from list_avatars. Its type sets the modality (voice-only vs avatar) — see The template picks the interview modality.
mojito_language_code✓Platform language code (e.g. en).
status✓draft, active, archived, or deleted.
type✓Product type, e.g. interview.
visibility✓Who can access it, e.g. merchant_invite, merchant_public.
description, candidate_expectations–Fed into AI question generation.
interview_length–Number of questions to generate (max 40).
welcome_message, thank_you_message–Custom candidate-facing messages — set these; the defaults are generic.
custom_scoring–Custom scoring-rubric overrides (object), merged over defaults.
knowledge_base_store_id–Ground questions in a knowledge base.

​
Option B — from your own questions

Supply an ordered questions array. Same required interview fields as Option A, plus a description. 
curl -X POST https://cool.jobmojito.com/functions/v1/job-interview-create-from-array \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Specialist",
    "location": "Remote",
    "interview_template_id": "TEMPLATE_UUID",
    "mojito_language_code": "en",
    "description": "Customer support screening",
    "status": "active",
    "type": "interview",
    "visibility": "merchant_invite",
    "questions": [
      { "question": "Tell me about a time you de-escalated an angry customer.", "duration": 120 },
      { "question": "How do you prioritize a full support queue?", "duration": 90 },
      { "question": "Rate your written English.", "is_multiple_choice": true,
        "question_alternatives": ["Native", "Fluent", "Intermediate"] }
    ]
  }'
Each questions item requires question (the text). Useful per-question flags: duration (seconds), is_without_scoring, is_multiple_choice, question_alternatives, is_conditional + conditional_question_main_id (for follow-ups), and knowledge_base_id (ask grounded questions — see Manage a knowledge base). The personalization fields from Option A — welcome_message, thank_you_message, and custom_scoring — apply here too. Set them in the same call so the candidate experience and rubric aren’t left on the generic defaults. Returns interview_def_set_id. Create the position (or reuse one), enrol a candidate, run pre-screening, and get a tokenised interview URL back — all in one request. 
curl -X POST https://cool.jobmojito.com/functions/v1/job-interview-create-for-candidate-with-token \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_name": "Peter Parker",
    "candidate_email": "peter@parker.com",
    "candidate_country_code": "US",
    "candidate_resume": "Full plaintext résumé here…",
    "position_name": "Senior Backend Engineer",
    "position_location": "Remote (EU)",
    "position_country_code": "DE",
    "mojito_language_code": "en"
  }'
If you already have a position, pass position_def_set_id instead of the position_* fields. The response includes status (e.g. ai_accept, recruiter_action, ai_reject), interview_url, and the created interview_def_set_id / position_def_set_id.
Need to publish, archive, or unpublish later? Use POST /job-interview-set-state (set_interview_state) with the position_id and a status of active, draft, archived, or deleted. Retrieve a definition with POST /job-interview-get (get_interview_definition).

​
Next steps

Invite candidates

Turn your new interview into links or email invitations.

Review results

Read transcripts, scores, and export reports once candidates finish.