--- title: "Schedule an AI-led (brain) interview" method: POST path: "/api/public/v1/interviews/schedule/brain" tags: ["Public API v1 — Scheduling", "Public API v1 — Scheduling"] --- # Schedule an AI-led (brain) interview `POST /api/public/v1/interviews/schedule/brain` ## 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/brain` - Auth: HTTP bearer Schedule a structured interview where TheBetterHire's brain agent is the interviewer — no human required. The candidate receives an invitation email with a join link; at the scheduled time they click through and converse with the brain via voice. Results are available via GET /interviews/{id} after the session ends. **On demand:** omit `scheduled_at` and the join link is live the moment it is created — the candidate starts when they click. An on-demand interview takes the same lengths as a scheduled one. Pass `send_invite: false` to skip our email and send `join_url` to the candidate yourself; `invite_sent` in the response says which happened. **Requirements:** - A job role with a competency rubric: create one with POST /job-roles, or pass the `job_role_id` of a role whose `interview_ready` is true on GET /job-roles/{id}. - Duration must be 45, 60, or 90 minutes; 30 is also accepted for a behavioural interview on an entry-level role. - Resume text is required so the brain can verify claims and tailor questions. If the rubric doesn't fit the chosen duration, returns 400 with a recruiter-friendly explanation suggesting a longer slot or trimmed rubric. ## Request body - BrainScheduleInterviewRequest: Schedule an AI-led brain interview. The brain agent (powered by TheBetterHire's voice loop) IS the interviewer — no human needed. The candidate joins via a token-based URL and the brain conducts a structured interview against the job role's competency rubric. - `candidate_name` string, required - `candidate_email` string, required - `role` string, required: Job title shown to the candidate. Used for the invitation email and dashboard label. - `job_role_id` string, required: UUID of a job role *with a competency rubric*. Brain interviews require a rubric to plan the conversation. POST /job-roles creates one (rubric extracted from the JD) and reports whether the role is interview-ready; GET /job-roles lists the ones you have. (A prior interview's `job_role_id` on GET /interviews/{id} works too.) - `scheduled_at` string, nullable: Interview start time (ISO 8601 UTC). Must be in the future when given. Omit for an ON-DEMAND interview: the join link is live the moment it is created and the candidate starts when they click. Nothing downstream reads the slot — the join page never gates on it — so the only difference is what the record and the invite say. - `duration_minutes` integer: 45, 60, or 90 minutes — on demand or scheduled alike. A behavioural interview for an entry-level role (experience_level `entry`) also accepts 30. Skill rounds stay at 45, 60, or 90. - `resume_text` string, required - `framework_code` string, nullable: Interview framework (bei, cbi, topgrading). Defaults to the job role's framework. - `notes` string, nullable - `metadata` object, nullable - `send_invite` boolean: Set false to skip BetterHire's invitation email and deliver `join_url` to the candidate yourself — for integrations that own the candidate conversation. The response reports `invite_sent`. - `return_url` string, nullable: Only for organisations whose candidate journey is integrator-owned (Settings → Appearance → Candidate Journey). When the call ends the candidate's browser is sent here with `?interview_id=` appended, instead of BetterHire's thank-you screen. Must be https. Overrides the organisation's default return address for this interview. Same rules as `return_url` on POST /screening. - `skill_id` string, nullable: Optional: run this as a specialist SKILL round (e.g. 'system_design') instead of a behavioral interview. The brain conducts a collaborative skill assessment and scores it against that skill's rubric. GET /skills lists the valid ids with their names, aliases and rubrics. Omit for a standard behavioral interview. - `plan_round_id` string, nullable: Optional: the role assessment-plan round this interview fulfils (a round_id from the role's assessment_plan). The snapshot is derived server-side and stamped on the interview for progress display. Descriptive only — never gates scheduling order. - `use_earlier_round_questions` boolean: Follow up on what earlier rounds found. When true, the AI interviewer is given this candidate's open questions for this job role from any earlier round (screening follow-ups, interview follow-ups, prep questions) and works the best of them into the interview, one per topic. `earlier_round_questions` in the response says how many were loaded. Behavioural interviews only: ignored, with a warning, when `skill_id` is set. ## Response `201` Successful Response - BrainScheduleInterviewResponse: Response after scheduling a brain interview. - `interview_id` string, required - `candidate_id` string, required - `status` string, required: 'scheduled'. - `scheduled_at` string, required - `join_url` string, required: URL the candidate uses to join the brain interview — at the scheduled time, or at once when `on_demand` is true. - `duration_minutes` integer, required - `message` string, required - `invite_sent` boolean: Whether BetterHire emailed the candidate the join link. False when `send_invite` was false, when the email could not be sent, and always in the sandbox — deliver `join_url` yourself in those cases. - `on_demand` boolean: True when the request carried no `scheduled_at`: the join link is live now, the record holds no slot, and `scheduled_at` above is the moment it went live. - `warnings` string[]: Things the interview will do that you may not expect; the request still succeeded. Today: a `skill_id` that is not marked for entry-level roles, booked on an entry-level role (GET /skills `suitable_for_entry`). The round runs, calibrated to entry level. Also: `use_earlier_round_questions` found no open questions, or was ignored because `skill_id` is set. - `earlier_round_questions` integer: How many open questions from earlier rounds were loaded for the AI interviewer (`use_earlier_round_questions`). 0 when not asked. ## 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)