> ## 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. # Create a role-play persona > An avatar that plays a role in a free-form conversation instead of asking questions: coaching personas and interview role-plays, their fields, and how to make the conversation progress. A **persona** is a different product: the AI avatar plays a defined role in a free-form conversation instead of asking a scored list of questions. Use it for sales role-plays, mock-customer practice, or any "act as X" scenario. There is **no AI question generation** — the role fields you supply *are* the configuration. The session flows as: a welcome message → the avatar's **opening line** → the candidate replies and the role-play begins → a closing message. The `opening_line` is the literal first thing the avatar says; it's the only scripted line, so set it in character (it defaults to a bare "Hello" if you omit it). Other ways to create an interview: [Create an interview](https://developer.jobmojito.com/cookbooks/create-an-interview.md). The avatar template you pick decides voice-only or avatar: see [The template picks the interview modality](https://developer.jobmojito.com/cookbooks/create-an-interview.md#the-template-picks-the-interview-modality). ## Two variants `POST /persona-create` creates one of two variants, chosen with the optional `portal` parameter. Both run the identical session mechanics — free-form role-play, no question list, the same `persona_*` and `opening_line` fields, and the same persona scoring — but they live on different portals and are billed differently. | | **Coaching persona** | **Interview role-play** | | - | - | - | | `portal` | `coaching` (the default) | `interview` | | Portal | Coaching portal only | Recruiter / interview portal | | Who takes it | Mentees on the coaching platform | Candidates, **invited through the normal invitation flow** | | Results | Visible to the coaching platform | Visible to **recruiters**, alongside regular interview results | | Billing | Consumer coaching credits | **Merchant credits**, using the standard interview cost formula | | Attempt limit | Unlimited | `interview_attempts` (default `3`) | | `type` in API responses | `persona` | `persona_interview` | > [!NOTE] > > `portal` defaults to `coaching`, so **existing callers are unaffected** — a `persona-create` call that doesn't mention `portal` behaves exactly as it did before. The **coaching persona** is otherwise unchanged: coaching portal only, billed against consumer coaching credits, with no attempt limit. The **interview role-play** (`portal: "interview"`) behaves like a persona in the session but like an interview commercially and operationally: * **Recruiters see the results.** Interview role-plays are scored on the persona scoring path — you get per-answer and session-level feedback, the same as a coaching persona — and completed sessions appear in the recruiter results list alongside regular interviews. See [Review results](https://developer.jobmojito.com/cookbooks/review-results.md). * **Candidates are invited normally.** Use the standard invitation flow (`POST /job-interview-register-users`) to generate links or send email invites — see [Invite candidates](https://developer.jobmojito.com/cookbooks/invite-candidates.md). * **It draws on merchant credits.** Cost is the standard interview formula — base format cost × duration multiplier, plus any recording add-ons — not consumer coaching credits. Each **completed** session is billed, so a candidate who uses every attempt costs a multiple of the single-session price. See [How credits work](https://developer.jobmojito.com/how-credits-work.md). * **Attempts are capped.** `interview_attempts` limits how many times a candidate may take the role-play; it defaults to **3**. > [!TIP] > > The cap is not a hard ceiling. A recruiter can always grant one more go with `POST /job-interview-result-request-another-attempt` (`request_another_interview_attempt`) — a released attempt no longer counts against the cap. The first example creates a **coaching persona**, the second the **interview-portal interview role-play**. The role fields are identical for either variant. ```bash Coaching persona theme={null} curl -X POST https://cool.jobmojito.com/functions/v1/persona-create \ -H "Authorization: Bearer $SUPABASE_JWT" \ -H "Content-Type: application/json" \ -d '{ "name": "Objection-handling role-play", "interview_template_id": "TEMPLATE_UUID", "mojito_language_code": "en", "status": "active", "visibility": "merchant_invite", "persona_role_avatar": "is to act as a busy procurement manager who is skeptical about switching vendors", "persona_role_user": "is to be a sales rep trying to book a follow-up demo", "persona_avatar_who_is": "Dana Reyes, procurement lead at a mid-size manufacturer. Runs a tight ship and is proud of it. She wants to stop firefighting supplier problems, and she is quietly worried that switching vendors mid-year will be blamed on her if it goes wrong. She will not engage with a pitch until someone acknowledges how much of her week the current vendor already costs her. She does not know that migration is handled by the supplier, not her team.", "persona_avatar_knowledge": "Current contract renews in 3 months. Budget is frozen until Q1. Two missed deliveries in the last quarter, on 14 March and 2 May. Her director, Tom, signs anything over 40k. She will raise price first, then switching risk. She would only mention that she is covering a colleague on parental leave, and is stretched thin, once the conversation feels genuinely useful to her.", "persona_avatar_progress": "Mode: turning point\nInitial hold: will not discuss switching while the conversation is about price.\nUnlocks when: the rep asks about the missed deliveries or the cost of managing the current vendor, rather than answering the price objection.\nAfter unlock: openly discusses the renewal timeline and will agree to a follow-up with Tom.\nHard limits: never commits to a contract on this call, and never accepts a discount as the reason to switch.\nNo goalposts: once unlocked, stays unlocked — no new objection is invented.\nGates: does not mention covering for a colleague on parental leave until after unlock.", "persona_avatar_end_conditions": "End once progress is complete — the follow-up with Tom is agreed — or once the conversation has clearly broken down.", "opening_line": "Look, I have about two minutes. We are pretty happy with our current vendor, so what is it you actually want?", "candidate_expectations": "Should uncover the renewal timeline and handle the price objection." }' ``` ```bash Interview role-play (interview portal) theme={null} curl -X POST https://cool.jobmojito.com/functions/v1/persona-create \ -H "Authorization: Bearer $SUPABASE_JWT" \ -H "Content-Type: application/json" \ -d '{ "name": "Objection-handling role-play", "portal": "interview", "interview_attempts": 3, "interview_template_id": "TEMPLATE_UUID", "mojito_language_code": "en", "status": "active", "visibility": "merchant_invite", "persona_role_avatar": "is to act as a busy procurement manager who is skeptical about switching vendors", "persona_role_user": "is to be a sales rep trying to book a follow-up demo", "persona_avatar_who_is": "Dana Reyes, procurement lead at a mid-size manufacturer. Runs a tight ship and is proud of it. She wants to stop firefighting supplier problems, and she is quietly worried that switching vendors mid-year will be blamed on her if it goes wrong. She will not engage with a pitch until someone acknowledges how much of her week the current vendor already costs her. She does not know that migration is handled by the supplier, not her team.", "persona_avatar_knowledge": "Current contract renews in 3 months. Budget is frozen until Q1. Two missed deliveries in the last quarter, on 14 March and 2 May. Her director, Tom, signs anything over 40k. She will raise price first, then switching risk. She would only mention that she is covering a colleague on parental leave, and is stretched thin, once the conversation feels genuinely useful to her.", "persona_avatar_progress": "Mode: turning point\nInitial hold: will not discuss switching while the conversation is about price.\nUnlocks when: the rep asks about the missed deliveries or the cost of managing the current vendor, rather than answering the price objection.\nAfter unlock: openly discusses the renewal timeline and will agree to a follow-up with Tom.\nHard limits: never commits to a contract on this call, and never accepts a discount as the reason to switch.\nNo goalposts: once unlocked, stays unlocked — no new objection is invented.\nGates: does not mention covering for a colleague on parental leave until after unlock.", "persona_avatar_end_conditions": "End once progress is complete — the follow-up with Tom is agreed — or once the conversation has clearly broken down.", "opening_line": "Look, I have about two minutes. We are pretty happy with our current vendor, so what is it you actually want?", "candidate_expectations": "Should uncover the renewal timeline and handle the price objection." }' ``` Returns `interview_def_set_id` (and `embed_id` / `embed_signing_key` when `is_embedded` is true). ## Key fields | Field | Required | Notes | | - | - | - | | `name` | ✓ | Persona / session name. **Plain UTF-8 text** — shown to the candidate as-is, so no Markdown or HTML. | | `interview_template_id` | ✓ | Avatar template id from `list_avatars`. Its `type` sets the modality (voice vs avatar). | | `mojito_language_code` | ✓ | Platform language code (e.g. `en`). | | `status` | ✓ | `draft` or `active`. | | `visibility` | ✓ | Who can access it, e.g. `merchant_invite`. | | `description` | – | Short persona description shown to the candidate on the pre-session poster. **Candidate-visible — keep to max 2 sentences, plain UTF-8 text (no Markdown or HTML).** Never AI-generated (personas run no generation); omit it and the poster shows no description. | | `persona_role_avatar` | ✓ | The role the **avatar** plays. **Candidate-visible** ("Role of the agent" on the poster) — keep to max 2 sentences. | | `persona_role_user` | ✓ | The role the **candidate** plays. **Candidate-visible** ("Your role" on the poster) — keep to max 2 sentences. | | `opening_line` | – | The avatar's **first spoken line** (the literal words it says to open the scene, in character). Omit and it defaults to a generic "Hello" — set it for anything other than a neutral greeting. | | `persona_avatar_who_is` | – | Who the avatar represents: name, role, context and personality, woven together with what drives them underneath — motive, fear, what they refuse to move past until it is heard, and what they only learn when told. One continuous description of a person; **no labelled subsections**. | | `persona_avatar_knowledge` | – | The private facts the avatar may use: numbers, dates, names, the objections it will raise. Personal details it should only share after the conversation has progressed go here too, with the timing written **inline** rather than as a labelled subsection. Those personal details must never be something the candidate has to extract in order to reach the goal. | | `persona_avatar_progress` | – | **How the conversation is allowed to move forward.** Plain text whose first line is either `Mode: turning point` (a scene about resistance) or `Mode: steps` (a conversation run to a protocol), followed by that mode's labelled lines — one per line. See [Progression](#progression). Omit it and the avatar has no arc: it tends to either concede on the first polite question or never concede at all. | | `persona_avatar_end_conditions` | – | When the avatar should end the session. Write it to **refer back to** `persona_avatar_progress` rather than restate it: wrap up once progress is complete (turning point unlocked and a plan accepted, or the `Done when` state reached), or once the conversation has clearly broken down. | | `candidate_expectations` | – | What the person must achieve, and what a strong performance looks like (≤ 2100 chars). Technically optional, but this is the yardstick the session is scored against — it is passed to the grader as the goal of the session. Omit it and the scoring has nothing to measure the transcript against, so set it on anything you intend to assess. | | `portal` | – | **Decide this first.** `interview` for anything that assesses or screens candidates (recruiter-visible, invited, merchant-billed, attempt-capped). `coaching` is the **default when omitted** and creates the coaching-portal practice persona instead — so pass `interview` explicitly for recruiting use cases. See [Two variants](#two-variants). | | `interview_attempts` | – | Allowed candidate attempts (1-20), default `3` — the same field and behaviour as on `POST /job-interview-create`. **Only meaningful when `portal` is `interview`**; coaching personas are unlimited. | | `welcome_message`, `thank_you_message` | – | Candidate-facing messages spoken before the role-play starts and shown after it ends — **set these; the defaults are generic.** `welcome_message` sets the scene; the avatar's first in-character line is `opening_line`, which follows it. | Common optional fields also apply: `code`, `cover_image_url`, `interview_location`, `max_duration` (seconds, default `1200`), `recording`, `recording_full_session`, `result_view`, `interview_conversation_speed`, `candidate_video_introduction`, `tags`, `recruiter_profile_id`, `merchant_id`, and `is_embedded`. On the **interview role-play** variant (`portal: "interview"`), `max_duration`, `recording`, and `recording_full_session` drive the merchant-credit cost exactly as they do on a standard interview. ## Progression `persona_avatar_progress` is what stops a role-play from being either trivially easy or unwinnable. It is one plain-text value: the first line picks the mode, and the following lines are that mode's labels, one per line. **Use one mode, not both.** Pick **turning point** for a scene built on resistance the candidate has to work through, and **steps** for a difficult conversation the candidate is expected to run to a protocol. ```text Mode: turning point theme={null} Mode: turning point Initial hold: what the avatar will not budge on at the start. Unlocks when: the specific, observable thing the candidate must do. After unlock: how the avatar behaves once it happens. Hard limits: what it never agrees to, regardless. No goalposts: once unlocked it stays unlocked; no new obstacle is invented. Gates: which later personal details stay unsaid until after unlock. ``` ```text Mode: steps theme={null} Mode: steps Framework: the protocol being assessed. Steps: the ordered steps the candidate is expected to take. Done when: the observable state that ends the scene. Hard limits: what the avatar never agrees to, regardless. Gates: which later personal details stay unsaid until progress is made. ``` Two rules make the difference between a scenario that assesses something and one that does not: * **`Unlocks when` / `Done when` must be observable.** "The rep asks about the missed deliveries" is something an assessor can point at in the transcript. "The rep builds rapport" is not, and the avatar will apply it inconsistently. * **No moving goalposts.** Once the candidate has earned progress, the avatar must not invent a fresh obstacle. Without the `No goalposts` line, a role-play that is supposed to be winnable often is not. The `Gates` line is the link back to `persona_avatar_knowledge`: anything listed there should be one of the later personal details you wrote in that field, and none of them should be required to reach the goal. The same progression is also fed to the grader, so it scores whether the candidate actually did the thing that was meant to unlock progress — not whether the avatar happened to soften. ## 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.