Create an interview - JobMojito Developer / Agent

There are four ways to create an interview, depending on how much you want JobMojito to generate for you:

You provide	Use	MCP tool	Guide
A job description → AI generates questions	`POST /job-interview-create`	`create_interview`	Generate an interview from a job position
Your own list of questions	`POST /job-interview-create-from-array` (or `POST /job-interview-create` with `questions`)	`create_interview` with `questions`	From your own questions, below
A candidate + position, get a ready link back	`POST /job-interview-create-for-candidate-with-token`	— (HTTP only, not an MCP tool)	One call per candidate, below
A role-play persona (avatar plays a role, no Q&A) — two variants: coaching persona, or an interview-portal interview role-play	`POST /persona-create`	`create_persona`	Create a role-play persona

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_elevenlabs`	Voice-only — realtime conversation, no video avatar.
`interactive_heygen`	Realtime interactive avatar — a talking video avatar.
`offline_heygen`	Non-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.

From your own questions

Supply an ordered questions array. Same required interview fields as generating from a job position, 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 — welcome_message, thank_you_message, and custom_scoring — plus everything in Additional configuration apply here too. Set them in the same call so the candidate experience and rubric aren’t left on the generic defaults. You may also pass candidate_expectations_json — a structured expectations object bucketed by requirement level ({ "weak": [...], "moderate": [...], "strong": [...] }). Omit it and JobMojito auto-generates one for type: "interview". Returns interview_def_set_id.

This same questions format comes back from GET /job-interview-get and is accepted by POST /job-interview-update, so you can change the questions of an interview later without recreating it — see Edit interview questions.

One call per candidate

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 — questions included — with POST /job-interview-get (get_interview_definition), and change its settings or questions with POST /job-interview-update (update_interview).

The additional configuration fields are honoured here too.

Next steps

Invite candidates

Turn your new interview into links or email invitations.

Review results

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

​The template picks the interview modality

​From your own questions

​One call per candidate

​Next steps

Invite candidates

Review results

The template picks the interview modality

From your own questions

One call per candidate

Next steps