Public API v1 — Scheduling
Public API v1 — Scheduling

Schedule an AI-led (brain) interview

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.

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

Request body

candidate_namestring required
candidate_emailstring required
rolestring required

Job title shown to the candidate. Used for the invitation email and dashboard label.

job_role_idstring 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_atstring 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_minutesinteger

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_textstring required
framework_codestring nullable

Interview framework (bei, cbi, topgrading). Defaults to the job role's framework.

notesstring nullable
metadataobject nullable
send_inviteboolean

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_urlstring 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_idstring 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_idstring 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_questionsboolean

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.

Example request

{
  "scheduled_at": "2026-04-30T14:00:00Z"
}

Response

Successful Response

interview_idstring required
candidate_idstring required
statusstring required

'scheduled'.

scheduled_atstring required
join_urlstring required

URL the candidate uses to join the brain interview — at the scheduled time, or at once when on_demand is true.

duration_minutesinteger required
messagestring required
invite_sentboolean

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_demandboolean

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.

warningsstring[]

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_questionsinteger

How many open questions from earlier rounds were loaded for the AI interviewer (use_earlier_round_questions). 0 when not asked.

Changes

No recorded changes to this operation across all 1 revision of this API.