> ## 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: 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' '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 authorization failures and 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 position description. position_description_long: type: string nullable: true description: Full / long position description. 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 used to scale generated questions. 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. 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. profile_interview_id: type: string description: Candidate profile_interview id. interview_url: type: string description: URL the candidate should open to continue. 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. 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 access token, passed as `Authorization: Bearer `.' ````