Generate an interview from a job position

JobMojito writes the description, questions, and candidate expectations for you. Other ways to create an interview (your own questions, one call per candidate, a role-play persona): Create an interview. The template you pick decides whether the candidate gets a voice-only or an avatar interview: see The template picks the interview modality.

Choose a template

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

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."
  }'

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.

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

Field	Required	Notes
`name`, `location`	✓	Position title and location. Plain UTF-8 text — displayed to the candidate as-is, so no Markdown or HTML (any `#`, `*`, or `<tags>` show up literally).
`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`	–	Short, two-sentence job description shown to the candidate, as plain UTF-8 text — no Markdown or HTML (unlike `description_long`; markup here renders literally). Provide it to use it as-is, or leave it null/blank and it is AI-generated from the position name (and any other context). Also fed into question generation.
`description_long`	–	Full job description in Markdown (Job Purpose, Responsibilities, Required & Preferred Qualifications). This is the only create field that accepts Markdown; `name` and `description` are plain text. Provide it to use it as-is, or leave it null/blank and it is AI-generated.
`candidate_expectations`	–	Free-text candidate expectations, fed into AI question generation.
`interview_length`	–	Number of questions to generate (1-40), capped by `max_duration` — see How many questions fit. Omit it and the AI picks 5-8.
`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.

How many questions fit

interview_length is capped by max_duration, which allows one question per 2 minutes — enough for the question, the answer, and automatic follow-ups.

`max_duration`	Interview length	Max questions
`1200` (default)	20 min	10
`1800`	30 min	15
`2700`	45 min	22
`3600`	60 min	30
`4800`	80 min	40

Asking for more than the cap is not an error — you get the cap. The create response returns questions_generated with the real count, so check it if the number matters to you.

Additional configuration

These optional fields fine-tune the position, the conversation, and what candidates see. They apply to job-interview-create and job-interview-create-from-array (and, where noted, job-interview-create-for-candidate-with-token). All are optional — omit any you don’t need.

Field	Type	Notes
`interview_department`	string	Department the position belongs to.
`interview_salary`	string	Salary range shown for the position.
`interview_available_till`	ISO date/time	When the interview stops being available to candidates.
`interview_conversation_speed`	`slower` \| `normal` \| `faster` \| `fluent`	Speaking pace of the AI avatar. `fluent` answers 300 ms after the candidate stops speaking.
`max_followups`	int `0`–`999`	Max AI follow-up questions. `0` disables follow-ups; omit for the template default.
`questions_random_subset`	number `0.01`–`0.9`	Ask only a random fraction of questions (e.g. `0.5` = 50%).
`required_pronunciation`	boolean	Require pronunciation assessment (restricts to pronunciation-capable languages).
`result_enable_edit_transcript`	boolean	Allow editing the transcript on the result view (default `true`).
`tags`	string[]	Free-form tags stored on the interview.
`recruiter_profile_id`	uuid	Recruiter (merchant profile) that owns the interview.
`hiring_for_company`	object	Who the role is really for (see below). Omit (or `name` null/blank) for yourself, `{ "name": "undisclosed" }` for an unnamed client, or `{ "name": "<company>" }` plus optional `description`/`location`/`sector`/`company_size` for a named client.
`pdf_export_auto_config`	object	Auto-generate a candidate PDF report when the interview completes (see below).

hiring_for_company describes the end employer so the AI agent can answer candidate questions accurately. All fields are optional; name carries the original meaning:

{
  "hiring_for_company": {
    "name": "JobMojito",
    "description": "World leading AI assessment provider.",
    "location": "Estonia",
    "sector": "AI Interview",
    "company_size": "100-200"
  }
}

Omit the field entirely, or send name null/blank → hiring for yourself (no external-client note).
{ "name": "undisclosed" } → external client whose name is withheld from the candidate.
{ "name": "<company>" } → named external client; description, location, sector, and company_size are surfaced to the agent as background context.

pdf_export_auto_config mirrors the report options — every key is optional:

{
  "pdf_export_auto_config": {
    "mojito_language_code": "en",
    "contact_details": true,
    "ai_recruiter_assessment": true,
    "ai_scoring_rubric": false,
    "analytics": true,
    "transcript": true,
    "files": true,
    "answer_recording": false,
    "session_recording": false,
    "group_by_question": false
  }
}

On job-interview-create-for-candidate-with-token these same fields are honoured (it creates the interview through the multistage flow). They require the interview_create_multi_stage migration to be deployed.

Portal branding

Key fields

How many questions fit

Additional configuration

Next steps

Invite candidates

Review results

​Key fields

​How many questions fit

​Additional configuration

​Next steps

Invite candidates

Review results

Key fields

How many questions fit

Additional configuration

Next steps