[Interviews] Create a role-play persona: an avatar that plays a defined role in a free-form conversation instead of a scored Q&A interview. `portal` selects between two different products: `portal="interview"` builds a SIMULATED PERSONA a recruiter invites candidates to — scored, billed to merchant credits, and listed with the recruiter's other results; `portal="coaching"` (THE DEFAULT) builds a coaching persona learners start themselves from the catalogue, paid per second from their own coaching minutes and never visible to recruiters. Hiring, screening and assessment use `portal="interview"`. `persona_role_avatar`/`persona_role_user` set the roles and `opening_line` the avatar's first spoken line (default: a generic 'Hello'). Full-session recording (recording_full_session) and a longer max_duration raise the credit cost.
Every argument in full, with examples: get_tool_reference.
View input schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Persona / session name."
},
"interview_template_id": {
"type": "string",
"minLength": 1,
"format": "uuid",
"description": "Id of the interview template (avatar) the persona uses."
},
"mojito_language_code": {
"type": "string",
"enum": [
"ar",
"bg",
"zh",
"hr",
"cs",
"da",
"nl",
"en",
"fil",
"fi",
"fr",
"de",
"el",
"hi",
"hu",
"id",
"it",
"ja",
"ko",
"ms",
"no",
"pl",
"pt",
"br",
"ro",
"ru",
"sk",
"es",
"sv",
"ta",
"th",
"tr",
"uk",
"vi"
],
"description": "Platform language code used for the conversation."
},
"status": {
"type": "string",
"enum": [
"draft",
"active"
],
"description": "Lifecycle status of the interview. Values: `draft`: Created but not published | `active`: candidates can run it."
},
"visibility": {
"type": "string",
"enum": [
"merchant_public",
"merchant_invite",
"merchant_unlisted"
],
"description": "Who can discover and access the interview. Values: `merchant_public`: Listed on the merchant's public interview list | `merchant_invite`: only candidates explicitly invited | `merchant_unlisted`: Reachable only via a direct link."
},
"description": {
"type": [
"string",
"null"
],
"description": "Short persona description shown to the candidate on the pre-session poster. Unlike create_interview, personas run no AI generation, so this is never auto-generated: null or blank, the poster shows no description; a value frames the scene."
},
"persona_role_avatar": {
"type": "string",
"minLength": 1,
"description": "The role the AI avatar plays."
},
"persona_role_user": {
"type": "string",
"minLength": 1,
"description": "The role the candidate (mentee) plays."
},
"persona_avatar_who_is": {
"type": [
"string",
"null"
],
"description": "Who the avatar represents: name, role, context, personality, woven with what drives them underneath (motive, fear, what they refuse until heard, what they do not know until told)."
},
"persona_avatar_knowledge": {
"type": [
"string",
"null"
],
"description": "Private facts the avatar can use (numbers, dates, names, objections), plus any personal details shareable only after progress and only if natural — timing written inline, not as labelled subsections. Those personal details are never required for the goal."
},
"persona_avatar_end_conditions": {
"type": [
"string",
"null"
],
"description": "When the avatar should end the session."
},
"persona_avatar_progress": {
"type": [
"string",
"null"
],
"description": "How the conversation moves forward — one plain-text value starting with `Mode: turning point` (resistance) or `Mode: steps` (difficult conversation protocol), then the labelled lines for that mode (Initial hold / Unlocks when / … or Framework / Steps / …), including a Gates line stating that later personal details from persona_avatar_knowledge are shared only once progress is earned."
},
"opening_line": {
"type": [
"string",
"null"
],
"description": "The avatar's opening line — the FIRST thing it says out loud when the session starts, before the candidate has said anything. If omitted, the platform inserts a generic default (\"Hello\"), a neutral greeting."
},
"candidate_expectations": {
"type": [
"string",
"null"
],
"maxLength": 2100,
"description": "Mentee assessment goals — free-text describing what the candidate is expected to achieve (max 2100 chars)."
},
"recording": {
"type": [
"string",
"null"
],
"enum": [
"audio_first_5_answers",
"audio_all",
"video_all",
"video_first_5_answers",
"none",
null
],
"description": "Cheating/proctoring detection mode for candidate answers — this is NOT a full session recording. Omit, null or `none` to disable. Values: `audio_first_5_answers`: Audio-only cheating detection, first 5 answers only | `audio_all`: Audio-only cheating detection on every answer | `video_all`: Audio + video cheating detection on every answer | `video_first_5_answers`: Audio + video cheating detection, first 5 answers only | `none`: No cheating detection."
},
"recording_full_session": {
"type": [
"string",
"null"
],
"enum": [
"audio_all",
"video_all",
"none",
null
],
"description": "Full interview-session recording (includes the avatar and voice) produced as a single file. Omit, null or `none` to disable. Values: `audio_all`: Record the whole session audio | `video_all`: Record the whole session video + audio | `none`: No full-session recording."
},
"environment": {
"type": "string",
"enum": [
"production",
"uat",
"development",
"demo"
],
"description": "Which of your webhook environments results from this interview are delivered to. Defaults to production. Values: `production`: Live hiring | `uat`: User-acceptance testing - an isolated environment for pre-release verification | `development`: Development/testing | `demo`: Demonstrations and sales trials."
},
"result_view": {
"type": [
"string",
"null"
],
"enum": [
"none",
"minimal",
"minimal_with_score",
"advanced",
"full",
"full_expand_scores",
null
],
"description": "Result screen shown to the candidate after finishing. With any value other than `none`, the candidate sees a results screen where they can provide feedback, record an intro video and edit the transcript, and must then submit the result; the value sets how much score/result detail is shown. Values: `none`: No results screen at all | `minimal`: Minimal results layout, no score shown | `minimal_with_score`: Minimal results layout including the overall score | `advanced`: Advanced results layout with more detail | `full`: Full results layout with all sections | `full_expand_scores`: Full results with every score breakdown expanded."
},
"interview_conversation_speed": {
"type": [
"string",
"null"
],
"enum": [
"slower",
"normal",
"faster",
"fluent",
null
],
"description": "Conversation pace of the AI avatar. Omit/null keeps the template default pace. Values: `slower`: The avatar speaks more slowly | `normal`: Default speaking pace | `faster`: The avatar speaks more quickly for a snappier conversation | `fluent`: Talking pace: the avatar answers 300 ms after the candidate stops speaking."
},
"candidate_video_introduction": {
"type": [
"string",
"null"
],
"enum": [
"hidden",
"optional",
"required",
null
],
"description": "Whether a candidate video introduction is optional or required."
},
"max_duration": {
"type": [
"number",
"null"
],
"description": "Maximum conversation duration in seconds. Defaults to 1200 (20 min) when omitted."
},
"code": {
"type": [
"string",
"null"
],
"description": "Optional external code/reference for the persona."
},
"cover_image_url": {
"type": [
"string",
"null"
],
"description": "Cover image URL."
},
"interview_location": {
"type": [
"string",
"null"
],
"description": "Optional location label shown for the session."
},
"merchant_id": {
"type": [
"string",
"null"
],
"description": "Merchant id. Admin / sub-merchant callers only; otherwise taken from your token."
},
"recruiter_profile_id": {
"type": [
"string",
"null"
],
"description": "Profile id of the recruiter owning this persona. A user of the company who is not read only: an owner, recruiter or admin from list_users."
},
"welcome_message": {
"type": [
"string",
"null"
],
"description": "Custom welcome message spoken to the candidate before the role-play starts; omitting it leaves a generic platform default."
},
"thank_you_message": {
"type": [
"string",
"null"
],
"description": "Custom thank-you message shown after the session; omitting it leaves a generic platform default."
},
"tags": {
"items": {
"type": "string"
},
"type": [
"array",
"null"
],
"description": "Free-form tags stored on the persona. Only `active` sessions with visibility `merchant_public` (or the platform's own `public`) are listed."
},
"portal": {
"type": [
"string",
"null"
],
"enum": [
"coaching",
"interview",
null
],
"description": "Left out, it is `coaching`. Values: `interview`: a scored role-play a recruiter invites candidates to, billed to merchant credits, attempts capped | `coaching`: a practice persona learners start from the catalogue, paid from their own coaching minutes, never visible to recruiters."
},
"interview_attempts": {
"type": [
"number",
"null"
],
"maximum": 20,
"minimum": 1,
"description": "Allowed candidate attempts (1-20), defaulting to 3. Only meaningful when `portal` is `interview`; coaching personas are unlimited."
},
"is_embedded": {
"type": [
"boolean",
"null"
],
"description": "Set true when the persona will be embedded as an iframe on an external page. A signed coaching embed (name, email, signature) signs the visitor in as a learner of that portal, and the session is charged to the merchant's interview credits on completion, not to the learner's coaching credits; it cannot start while the merchant has none."
},
"llm_model": {
"type": "string",
"description": "Your model id, e.g. \"claude-opus-4-8\"; \"unknown\" if unsure. For analytics."
},
"conversation_id": {
"type": "string",
"description": "The conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics."
}
},
"required": [
"name",
"interview_template_id",
"mojito_language_code",
"status",
"visibility",
"persona_role_avatar",
"persona_role_user"
]
}