> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jobmojito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate an interview from a job position

> Let JobMojito write the description, questions and candidate expectations from a job position: the create call, its fields, how many questions fit, and every optional setting.

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](https://developer.jobmojito.com/cookbooks/create-an-interview.md).

The template you pick decides whether the candidate gets a voice-only or an avatar interview: see [The template picks the interview modality](https://developer.jobmojito.com/cookbooks/create-an-interview.md#the-template-picks-the-interview-modality).

**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`.

```bash cURL theme={null}
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.

```json theme={null}
{
  "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 }
    ]
  }
}
```

> [!NOTE]
>
> `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](https://developer.jobmojito.com/mcp/identifiers.md).

```json theme={null}
{ "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](https://developer.jobmojito.com/cookbooks/create-an-interview.md#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](#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](https://developer.jobmojito.com/cookbooks/manage-knowledge-base.md). |

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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
  }
}
```

> [!NOTE]
>
> 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.

## Next steps

> [card] [Invite candidates](https://developer.jobmojito.com/cookbooks/invite-candidates.md)
>
> Turn your new interview into links or email invitations.

> [card] [Review results](https://developer.jobmojito.com/cookbooks/review-results.md)
>
> Read transcripts, scores, and export reports once candidates finish.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.