> ## 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 an interview for a candidate and return an access token URL > Creates (or resolves an existing) position and interview for a merchant, enrols the candidate, runs pre-screening, and returns a tokenised interview URL. Position fields are required only when position_def_set_id is not provided. ## OpenAPI ````yaml https://cool.jobmojito.com/functions/v1/openapi post /job-interview-create-for-candidate-with-token openapi: 3.1.0 info: title: JobMojito API version: 1.0.0 description: >- Public API for JobMojito, served by Supabase Edge Functions. Authenticate with a Supabase JWT access token via the Authorization header. servers: - url: https://cool.jobmojito.com/functions/v1 description: Production security: [] tags: - name: Interviews description: >- Create, configure and manage interview / coaching / assessment definitions. - name: Coaching catalogue description: >- Directories (pages) of the coaching portal catalogue that group coaching sessions and carry custom content pages. - name: Results description: >- Interview results, transcripts, reports, re-attempt requests and analytics. - name: Candidates description: List and manage candidates. - name: Knowledge base description: Upload documents used to generate knowledge-base interviews. - name: Resume & Form verification description: Pre-screen candidates from resumes and forms. - name: Admin description: >- Account administration — invite team/coaching users, manage sub-merchants and avatar templates. paths: /job-interview-create-for-candidate-with-token: post: tags: - Interviews summary: Create an interview for a candidate and return an access token URL description: >- Creates (or resolves an existing) position and interview for a merchant, enrols the candidate, runs pre-screening, and returns a tokenised interview URL. Position fields are required only when position_def_set_id is not provided. requestBody: required: true content: application/json: schema: $ref: >- #/components/schemas/JobInterviewCreateForCandidateWithTokenRequest responses: '200': description: >- Candidate enrolled. Decision status, ids, and a tokenised interview URL. content: application/json: schema: $ref: >- #/components/schemas/JobInterviewCreateForCandidateWithTokenResponse '401': description: Missing, expired or invalid access token. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Your token is not allowed to use this endpoint (it is not a merchant, merchant owner or admin token). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: The requested position_def_set_id could not be found. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Validation error (missing/invalid fields, unresolved merchant/language/template). content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Server error (includes unhandled exceptions). content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: JobInterviewCreateForCandidateWithTokenRequest: type: object properties: position_def_set_id: type: string nullable: true description: >- Existing position_def_set id. When provided, the position is looked up instead of created, and position_name/position_location/position_country_code/mojito_language_code become optional. example: 00000000-0000-0000-0000-000000000000 position_external_id: type: string nullable: true description: External position code used to look up an existing position. example: JOB-123 interview_template_id: type: string nullable: true description: >- Interview template id to base the interview on. Defaults to the platform template when omitted. example: 5d8ea38b-eec4-4866-aa6c-b2ea5bc6e45b merchant_id: type: string nullable: true description: >- Merchant id. Only honoured for admin / sub-merchant tokens; otherwise the token merchant is used. example: 28106cba-1c27-4e53-b149-32113e5e8e31 position_name: type: string nullable: true description: >- Position / job title. Required when position_def_set_id is not provided. example: Entry level coffee boy position_location: type: string nullable: true description: >- Position location. Required when position_def_set_id is not provided. example: remote position_country_code: type: string nullable: true description: >- ISO country code of the position. Required when position_def_set_id is not provided. example: SK mojito_language_code: type: string nullable: true 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: >- Interview language code (one of the platform-languages.json codes). Required when position_def_set_id is not provided. example: en position_description: type: string nullable: true description: >- Short, two-sentence position description shown to the candidate. Provide it to use it as-is; leave it null/blank and it is AI-generated from the position name and any other context. position_description_long: type: string nullable: true description: >- Full position description in Markdown (Job Purpose, Responsibilities, Required & Preferred Qualifications). Provide it to use it as-is; leave it null/blank and it is AI-generated. Rendered as Markdown on the candidate-facing position page, including chips, callouts, cards, columns and buttons — formatting guide: https://developer.jobmojito.com/cookbooks/format-content-with-markdown candidate_name: type: string minLength: 1 description: Candidate full name. example: John candidate_email: type: string minLength: 1 description: Candidate email (used as auth identity). example: peterson6@hello.com candidate_country_code: type: string minLength: 1 description: ISO country code of the candidate. example: HR candidate_resume: type: string minLength: 1 description: Candidate resume parsed text. example: Curriculum Vitae ... candidate_external_id: type: string nullable: true description: External candidate id stored on the profile. candidate_linkedin_url: type: string nullable: true description: Candidate LinkedIn URL. candidate_video_introduction: type: string nullable: true enum: - optional - required description: Whether a candidate video introduction is optional or required. interview_attempts: type: number nullable: true minimum: 1 maximum: 20 description: Number of allowed interview attempts (1-20). example: 3 seniority_level: type: string nullable: true enum: - entry-level - intermediate - senior - managerial - director - executive description: Seniority level of the position. Auto-detected when omitted. result_view: type: string nullable: true enum: - none - minimal - minimal_with_score - advanced - full - full_expand_scores description: >- How interview results are shown to the candidate. Defaults to minimal. custom_scoring: type: object nullable: true additionalProperties: nullable: true description: Optional custom scoring overrides merged with platform defaults. use_enhanced_expectations: type: boolean nullable: true description: Reserved flag for enhanced candidate expectations generation. include_rapport_question: type: boolean nullable: true description: Include an opening rapport question. Defaults to false. include_closing_prompt: type: boolean nullable: true description: Include a closing prompt. Defaults to true. instructional_video: type: boolean nullable: true description: Show an instructional video before the interview. Defaults to false. instructional_video_custom_text: type: string nullable: true description: Custom text shown with the instructional video. welcome_message: type: string nullable: true description: Custom welcome message for the interview. thank_you_message: type: string nullable: true description: Custom thank-you message shown after the interview. max_duration: type: number nullable: true description: >- Maximum interview duration in seconds. Scopes how many questions are generated and is stored on the interview as the live session limit and the basis for the credit multiplier. Defaults to 1200 (20 minutes) when omitted. example: 1200 is_embedded: type: boolean nullable: true description: >- Set true when the interview will be embedded as an iframe on an external page. Ensures an embed key exists and returns embed_id/embed_signing_key, used to authenticate/sign the iframe embed. interview_department: type: string nullable: true description: Department the position belongs to. example: Engineering interview_salary: type: string nullable: true description: Salary range shown for the position. example: $80k - $100k interview_available_till: type: string nullable: true description: >- ISO date/time after which the interview is no longer available to candidates. null keeps it always available. example: '2026-12-31' interview_conversation_speed: type: string nullable: true enum: - slower - normal - faster description: >- Conversation pace of the AI avatar. Omit/null keeps the template default pace. Options — `slower`: The avatar speaks more slowly — easier to follow for non-native speakers. | `normal`: Default speaking pace. | `faster`: The avatar speaks more quickly for a snappier conversation.. example: normal environment: type: string enum: - production - uat - development - demo description: >- Which of your webhook environments results from this interview are delivered to. Defaults to production. Options — `production`: Live hiring. Results reach the webhooks configured as production. This is the default when the field is omitted. | `uat`: User-acceptance testing - an isolated environment for pre-release verification. | `development`: Development/testing. Use for interviews created by a test or preview app so their results never reach the production webhook. | `demo`: Demonstrations and sales trials.. example: production max_followups: type: integer nullable: true minimum: 0 maximum: 999 description: >- Maximum number of AI follow-up questions. 0 disables follow-ups; presets are 0-3 (none/low/normal/high) and custom values start at 4; null uses the template default (Normal). example: 2 questions_random_subset: type: number nullable: true minimum: 0.01 maximum: 0.9 description: >- Ask only a random subset of the questions, expressed as a fraction between 0.01 and 0.9 (e.g. 0.5 = 50%). null asks all questions. example: 0.5 required_pronunciation: type: boolean nullable: true description: >- Require pronunciation assessment (restricts to pronunciation-capable languages). Defaults to false. example: false result_enable_edit_transcript: type: boolean nullable: true description: Allow editing the transcript on the result view. Defaults to true. example: true tags: type: array nullable: true items: type: string description: Free-form tags stored on the interview. example: - engineering - remote recruiter_profile_id: type: string nullable: true description: >- Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant. hiring_for_company: type: object nullable: true properties: name: type: string nullable: true description: >- End-employer name. Omit/null when hiring for yourself, 'undisclosed' for an unnamed external client, or the client's company name. example: Unimo Enterprises description: type: string nullable: true description: >- Short description of the end employer, used as background context by the agent. example: >- Unimo Enterprises is a leading logistics and supply chain solutions provider. location: type: string nullable: true description: Primary location of the end employer. example: Sri Lanka sector: type: string nullable: true description: Industry / sector of the end employer. example: Logistics and Supply Chain company_size: type: string nullable: true description: Approximate headcount of the end employer. example: 100-200 description: >- Who the position is really for. Omit/null (or an object with name null/blank) when hiring for yourself; { name: 'undisclosed' } for an unnamed external client; or { name: '' } plus optional description/location/sector/company_size for a named client. Stored in creation_parameters.hiring_for_company. example: name: undisclosed pdf_export_auto_config: type: object nullable: true properties: 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: Report language code (a platform-languages.json code). example: en contact_details: type: boolean description: Include candidate contact details. ai_recruiter_assessment: type: boolean description: Include the AI recruiter assessment. ai_scoring_rubric: type: boolean description: Include the AI scoring rubric. analytics: type: boolean description: Include analytics. files: type: boolean description: Include uploaded candidate files. transcript: type: boolean description: Include the interview transcript. answer_recording: type: boolean description: Include per-answer recordings. session_recording: type: boolean description: Include the full-session recording. group_by_question: type: boolean description: Group transcript answers by expected question. template: type: string enum: - classic - modern - one_pager description: >- Report layout: classic, modern, or one_pager. Omit for the merchant default (modern when unset). description: >- Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export. required: - candidate_name - candidate_email - candidate_country_code - candidate_resume JobInterviewCreateForCandidateWithTokenResponse: type: object properties: status: type: string enum: - ai_accept - recruiter_accept - recruiter_action - ai_reject - recruiter_reject - already-applied description: Decision / lifecycle status for the candidate against this position. position_def_set_id: type: string description: Created/resolved position id. interview_def_set_id: type: string description: >- Created/resolved interview definition set id: the position's first interview step. Absent when the position has no interview step. profile_interview_id: type: string description: Candidate profile_interview id. interview_url: type: string description: >- URL the candidate should open to continue: the interview of the current interview step, otherwise the application page (pre-screening outcome, meeting booking, waiting for the recruiter). reason: type: string description: Human-readable reason, present on reject / already-applied branches. embed_id: type: string description: Embed id, present only when is_embedded=true. embed_signing_key: type: string description: Embed signing key, present only when is_embedded=true. steps: type: array items: type: object properties: position_def_step_id: type: string description: Position step definition id. sequence_no: type: number description: Order of the step in the position process. index: type: number description: 1-based index of the step. type: type: string enum: - pre-screening - interview - meeting - invited description: Step type. name: type: string description: Step label (custom name, or the default label of its type). custom_name: type: string nullable: true description: Custom step name, null when the default label applies. advance: type: string nullable: true description: >- How the candidate moves on after this step is accepted: 'auto' or 'manual'. position_result_step_id: type: string nullable: true description: The candidate's step id, null while the step is not reached. status: type: string nullable: true description: Status of the candidate's step. decision_status: type: string nullable: true description: >- Decision on the step (candidate_action, recruiter_action, ai_accept, recruiter_reject, ...). is_current: type: boolean nullable: true description: Whether this is the candidate's current step. state: type: string enum: - done - rejected - current - waiting - scheduled - upcoming description: Progress state of the step for this candidate. score: type: number nullable: true description: >- Score of the step (interview score, pre-screening score), when available. start_at: type: string nullable: true description: When the candidate reached the step (ISO 8601). decided_at: type: string nullable: true description: When the step was decided (ISO 8601). interview_set_id: type: string nullable: true description: Interview definition of an interview step. interview_pre_screening_id: type: string nullable: true description: Pre-screening definition of a pre-screening step. interview_result_id: type: string nullable: true description: Interview result of an interview step. interview_result_pre_screening_id: type: string nullable: true description: Pre-screening result of a pre-screening step. interview_attempts: type: number nullable: true description: Number of interview attempts on the step. recruiter_notes: type: string nullable: true description: Recruiter notes on the step. meeting: type: object nullable: true properties: booking_id: type: string nullable: true booking_status: type: string nullable: true slot_id: type: string nullable: true start_at: type: string nullable: true duration_minutes: type: number nullable: true location: type: string nullable: true meeting_url: type: string nullable: true instructions: type: string nullable: true cutoff_at: type: string nullable: true description: Booking details of a meeting step; null for other step types. required: - position_def_step_id - sequence_no - index - type - name - position_result_step_id - status - decision_status - state description: >- The candidate's progress through the position's steps (pre-screening, interviews, meetings), in order. required: - status - interview_url description: >- Result of creating (or resolving) the position and enrolling the candidate. Fields present depend on the decision branch. Error: type: object properties: error: type: string example: Field is required. name: type: string example: interview_result_id required: - error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Supabase JWT — `Authorization: Bearer `.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.