Get interview definition
get_interview_definitionRead-onlyIdempotent
[Interviews] Get the definition/configuration of an interview (position), including its ordered questions array. The questions come back in the same format create_interview_from_questions accepts, so you can read an interview here, change the array, and send it to update_interview. Each question's id identifies it — keep the ids you did not mean to change.
Retrieves the interview definition for a given interview-definition id or position id. Returns the compiled calc_definition_json, the ordered questions array (in the same format job-interview-create-from-array accepts, so it round-trips into job-interview-update) plus basic metadata. Access is subject to the caller's row-level security.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| position_id | Yes | Identifier of either an interview definition (single-stage) or a position definition (multi-stage). The function resolves whichever matches. | |
| conversation_id | No | Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Caller-supplied external code/reference. | |
| name | Yes | Interview or position name. | |
| slug | Yes | URL slug of the public listing, when one was generated. | |
| tags | Yes | Free-form tags. Also the coaching-catalogue mapping key: a catalogue directory lists this session when its `tags_interview_set_filter` is a subset of these tags. Null for multi-stage positions. | |
| type | Yes | Interview type. Null for multi-stage positions. | |
| stage | Yes | Hiring-pipeline stage. Null for multi-stage positions. | |
| status | Yes | Lifecycle status of the interview/position. | |
| questions | Yes | The interview questions, in the order they are asked, in the same format job-interview-create-from-array accepts — so this array can be edited and sent straight back to job-interview-update, or used to create a copy of this interview. Each `id` is the question's real identifier: send it back unchanged and the question keeps its existing record (and with it its answer rules and any rendered avatar video). The welcome, thank-you and instructional-video steps are NOT included — they are not questions in this format, and job-interview-update leaves them untouched. Null for multi-stage positions, whose questions live on the individual interview stages. | |
| recording | Yes | Per-answer recording mode. Null for multi-stage positions. | |
| coach_plan | Yes | Coaching-plan stage this session belongs to. Null for multi-stage positions and for sessions outside any plan. | |
| created_at | Yes | ||
| updated_at | Yes | ||
| visibility | Yes | Who can see and access the interview/position. | |
| description | Yes | Short description. | |
| environment | Yes | Which webhook environment this interview's results are delivered to. Null for multi-stage positions, whose stages each carry their own. | |
| merchant_id | Yes | Owning merchant id. | |
| result_view | Yes | Result view level. Null for multi-stage positions. | |
| type_credit | Yes | Credit bucket the interview draws from. Null for multi-stage positions. | |
| max_duration | Yes | Live session limit in seconds. Null for multi-stage positions. | |
| is_multistage | Yes | True when the id resolved to a multi-stage position rather than a single interview. | |
| is_voice_only | Yes | Convenience flag derived from interview_template_type: true when voice-only (`interactive_elevenlabs`), false when avatar-based, null when the template type could not be resolved. | |
| max_followups | Yes | Maximum number of AI follow-up questions; null uses the template default. Null for multi-stage positions. | |
| result_scoring | No | Resolved result-scoring config (update field `custom_scoring`; its `max_retries` is the update field `interview_attempts`). Null means the platform defaults apply. Null for multi-stage positions. | |
| cover_image_url | Yes | Cover image URL. | |
| interview_salary | Yes | Salary range shown for the position. | |
| _mcp_instructions | No | Server-issued metadata for this conversation. | |
| interview_location | Yes | Location (create field `location`). | |
| creation_parameters | No | The creation parameters recorded at build time (interview_type, interview_tone, interview_length, additional_context, include_rapport_question, include_closing_prompt, knowledge_base_store_id, seniority_level, hiring_for_company). | |
| calc_definition_json | No | The compiled interview definition JSON (structure varies by interview type). | |
| country_availability | No | Portal availability by the candidate's country: {countries_allowed?: string[], countries_allowed_eu?: boolean, countries_blocked?: string[], countries_blocked_eu?: boolean} (ISO 3166-1 alpha-2, EU = EU + EEA + Switzerland; blocked wins), judged by the candidate's IP on the portal; invited candidates keep access. Null = not used, every country. Set it with job-interview-update. | |
| interview_department | Yes | Department the position belongs to. | |
| mojito_language_code | Yes | Platform (mojito) language code. | |
| recruiter_profile_id | Yes | Profile id of the recruiter owning this interview/position. | |
| speech_language_code | Yes | Azure speech language code. Null for multi-stage positions. | |
| speech_language_name | Yes | Azure speech language display name. Null for multi-stage positions. | |
| interview_template_id | Yes | Interview template id. For multi-stage positions this is the first interview step's template. | |
| candidate_expectations | Yes | Free-text candidate expectations. Null for multi-stage positions. | |
| pdf_export_auto_config | No | Auto-PDF-report options applied when the interview completes; null when auto-export is off. Null for multi-stage positions. | |
| recording_full_session | Yes | Full-session recording mode. Null for multi-stage positions. | |
| required_pronunciation | Yes | Whether a pronunciation assessment is required. Null for multi-stage positions. | |
| interview_template_type | Yes | Type of the linked interview template. `interactive_elevenlabs` is voice-only; the others (`interactive_spatius`, `interactive_heygen`, `offline_heygen`, `offline_elai`, `offline_synthesia`) are avatar-based. Null when the template could not be resolved. | |
| knowledge_base_store_id | Yes | Linked knowledge base store id. Null for multi-stage positions. | |
| questions_random_subset | Yes | Fraction of the questions actually asked (0.01-0.9); null asks all of them. Null for multi-stage positions. | |
| interview_available_till | Yes | ISO date/time after which the interview is no longer available to candidates. Null means always available. | |
| interview_description_long | Yes | Long description (create/update field `description_long`). Rendered as Markdown on the candidate-facing position page — formatting guide: https://developer.jobmojito.com/cookbooks/format-content-with-markdown | |
| candidate_expectations_json | No | Structured candidate expectations JSON — the scoring rubric. Null for multi-stage positions. | |
| candidate_video_introduction | Yes | Whether a candidate video introduction is hidden/optional/required. Null for multi-stage positions. | |
| interview_conversation_speed | Yes | Conversation pace of the AI avatar (slower/normal/faster). Null keeps the template default. Null for multi-stage positions. | |
| result_enable_edit_transcript | Yes | Whether the candidate may edit the transcript on the result view. Null for multi-stage positions. | |
| candidate_notification_channel | Yes | SMS / WhatsApp candidate notifications: null = off, reminders = with both e-mail reminders, last_reminder = only with the final reminder, all = invitation + reminders + pre-screening accepted. |