Public API v1
Public API v1

Submit interview for analysis

Submit an interview for AI-powered analysis. Two input modes:

Mode 1 (meeting link): Provide meeting_url + scheduled_at. BetterHire bot joins the meeting, records, transcribes, and analyzes.

Rate limit: 50 requests/hour per API key.

Mode 2 (recording URL): Provide recording_url. BetterHire transcribes and analyzes the existing recording.

Poll GET /interviews/{id} or register a webhook to be notified when complete.

post/api/public/v1/interviews

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
  • Auth: HTTP bearer

Request body

meeting_urlstring nullable

URL of the meeting to join and record (Mode 1). BetterHire bot will join at the scheduled time, record the interview, then transcribe and analyze automatically. Currently supports Google Meet URLs.

meeting_platformstring nullable

Platform of the meeting. Required when using meeting_url. Supported: 'google_meet'. Zoom and Teams coming soon.

scheduled_atstring nullable

ISO 8601 datetime when the meeting starts. Required when using meeting_url. The bot joins approximately 2 minutes after this time.

recording_urlstring nullable

URL of an existing interview recording (Mode 2). Supports S3/GCS presigned URLs or any publicly accessible URL. Formats: mp3, wav, m4a, webm, ogg, mp4.

candidate_idstring nullable

BetterHire candidate ID from a previous submission. If provided, candidate_name and candidate_email are optional — we already know who they are. Returned in every POST response for reuse in subsequent interviews.

candidate_namestring nullable

Full name of the candidate. Required on first submission (when no candidate_id).

candidate_emailstring nullable

Candidate's email. Used for deduplication — same email = same candidate across interviews.

rolestring required

Job role the candidate is being interviewed for.

job_descriptionstring required

Full job description text. BetterHire uses this to extract competencies and score the candidate against the actual role requirements.

resume_textstring nullable

Candidate's resume as plain text. Recommended — allows the AI to cross-reference interview responses with claimed experience and skills. Without it, analysis is based solely on the transcript.

interview_typestring nullable

Type of interview. Helps BetterHire choose the right analysis approach. One of: 'technical', 'behavioral', 'culture_fit', 'screening', 'general'. If not provided, defaults to 'general' (AI infers from transcript).

frameworkstring nullable

Interview framework for analysis (optional, for power users). One of: 'BEI' (Behavioral Event Interview), 'CBI' (Competency-Based Interview), 'topgrading'. Overrides interview_type mapping if provided.

metadataobject nullable

Arbitrary key-value metadata to attach to this interview. Returned in all subsequent responses. Use for your own internal IDs, tags, etc.

Example request

{
  "meeting_url": "https://meet.google.com/abc-defg-hij",
  "meeting_platform": "google_meet",
  "scheduled_at": "2026-03-28T14:00:00Z",
  "recording_url": "https://storage.example.com/interviews/recording-001.mp3",
  "candidate_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "candidate_name": "Priya Sharma",
  "candidate_email": "priya@example.com",
  "role": "Senior Backend Engineer",
  "interview_type": "technical",
  "framework": "BEI",
  "metadata": {
    "ats_candidate_id": "gh-12345",
    "stage": "technical"
  }
}

Response

Successful Response

idstring required

Unique interview ID. Use this to poll for status and retrieve results.

candidate_idstring required

Candidate ID. Store this — use it for subsequent interviews and to request debriefs.

statusstring required

Initial status (always 'pending').

input_modestring required

'meeting' if a bot will join the call, or 'recording' if processing an uploaded recording.

messagestring required

Human-readable confirmation message.

Example response

{
  "status": "pending",
  "input_mode": "recording"
}

Changes

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