Public API v1 — Scheduling
Public API v1 — Scheduling

Schedule a human interview with AI recording

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.

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

Request body

candidate_namestring required

Full name of the candidate.

candidate_emailstring required

Candidate's email address. Calendar invite will be sent here.

rolestring required

Job title the candidate is interviewing for.

job_role_idstring 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_descriptionstring required

Full job description. Used to extract competencies for AI analysis after the interview.

scheduled_atstring required

Interview start time in ISO 8601 format (UTC). Must be in the future.

interviewer_emailstring required

Email of the person conducting the interview. Calendar invite sent to them.

duration_minutesinteger

Interview duration in minutes.

meeting_urlstring nullable

Existing Google Meet URL. If not provided and Google Calendar is connected, one is created automatically.

resume_textstring required

Candidate's resume as plain text. Required for AI analysis — used to verify claims, identify skill gaps, and score competencies after the interview.

notesstring nullable

Notes for the interviewer or internal reference.

metadataobject nullable

Custom metadata to attach to this interview.

Example request

{
  "candidate_name": "Raj Patel",
  "candidate_email": "raj.patel@example.com",
  "role": "Senior Backend Engineer",
  "job_role_id": "9ebd749c-3462-437a-8a17-81395b772568",
  "scheduled_at": "2026-04-05T14:00:00Z",
  "interviewer_email": "marcus@company.com",
  "meeting_url": "https://meet.google.com/abc-defg-hij"
}

Response

Successful Response

interview_idstring required

Interview ID. Use to check results after the meeting.

candidate_idstring required

Candidate ID for debrief and comparison.

statusstring required

'scheduled'.

scheduled_atstring required

Confirmed interview time (ISO 8601).

meeting_urlstring nullable

Google Meet URL. Null if no calendar connected and no URL provided.

messagestring required

Human-readable status message.

Changes

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