---
title: "Schedule a human interview with AI recording"
method: POST
path: "/api/public/v1/interviews/schedule"
tags: ["Public API v1 — Scheduling", "Public API v1 — Scheduling"]
---

# Schedule a human interview with AI recording

`POST /api/public/v1/interviews/schedule`

## Request

- Base URL: `https://api.thebetterhire.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.thebetterhire.ai/api/public/v1/interviews/schedule`
- Auth: HTTP bearer

Schedule an interview between a human interviewer and candidate. TheBetterHire bot joins the Google Meet automatically, records the conversation, then transcribes and analyzes it. Results are available via GET /interviews/{id} after the meeting ends.

If Google Calendar is connected, a Meet link is created automatically and calendar invites are sent to both interviewer and candidate.

If no calendar connection, provide a `meeting_url` (Google Meet link) manually.

## Request body

- BackendRoutersPublicSchedulingScheduleInterviewRequest: Schedule a human interview with automatic AI recording.
  - `candidate_name` string, required: Full name of the candidate.
  - `candidate_email` string, required: Candidate's email address. Calendar invite will be sent here.
  - `role` string, required: Job title the candidate is interviewing for.
  - `job_role_id` string, nullable: Exact role id to schedule against. Wins over `role`. Pass this when your org has multiple roles sharing a title — otherwise an ambiguous `role` returns 409 listing the candidate role ids.
  - `job_description` string, required: Full job description. Used to extract competencies for AI analysis after the interview.
  - `scheduled_at` string, required: Interview start time in ISO 8601 format (UTC). Must be in the future.
  - `interviewer_email` string, required: Email of the person conducting the interview. Calendar invite sent to them.
  - `duration_minutes` integer: Interview duration in minutes.
  - `meeting_url` string, nullable: Existing Google Meet URL. If not provided and Google Calendar is connected, one is created automatically.
  - `resume_text` string, required: Candidate's resume as plain text. Required for AI analysis — used to verify claims, identify skill gaps, and score competencies after the interview.
  - `notes` string, nullable: Notes for the interviewer or internal reference.
  - `metadata` object, nullable: Custom metadata to attach to this interview.

## Response `201`

Successful Response

- BackendRoutersPublicSchedulingScheduleInterviewResponse: Response after scheduling an interview.
  - `interview_id` string, required: Interview ID. Use to check results after the meeting.
  - `candidate_id` string, required: Candidate ID for debrief and comparison.
  - `status` string, required: 'scheduled'.
  - `scheduled_at` string, required: Confirmed interview time (ISO 8601).
  - `meeting_url` string, nullable: Google Meet URL. Null if no calendar connected and no URL provided.
  - `message` string, required: Human-readable status message.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api.md) · [All operations](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api/revisions/c8ad03e900ea?raw)