Create a role-play persona

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. The avatar template you pick decides voice-only or avatar: see 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`

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.
Candidates are invited normally. Use the standard invitation flow (POST /job-interview-register-users) to generate links or send email invites — see Invite candidates.
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.
Attempts are capped. interview_attempts limits how many times a candidate may take the role-play; it defaults to 3.

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.

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

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

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.

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.

Portal branding

Two variants

Key fields

Progression

Next steps

Invite candidates

Review results

​Two variants

​Key fields

​Progression

​Next steps

Invite candidates

Review results

Two variants

Key fields

Progression

Next steps