---
title: "Submit interview for analysis"
method: POST
path: "/api/public/v1/interviews"
tags: ["Public API v1", "Public API v1"]
---

# Submit interview for analysis

`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

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.

## Request body

- InterviewSubmitRequest: Submit an interview for AI analysis. Two input modes — provide exactly one of `meeting_url` or `recording_url`: **Mode 1 (meeting link):** BetterHire joins the meeting, records, transcribes, and analyzes. Requires `scheduled_at`. Currently supports Google Meet. **Mode 2 (recording URL):** You provide an existing recording. BetterHire transcribes and analyzes.
  - `meeting_url` string, 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_platform` string, nullable: Platform of the meeting. Required when using `meeting_url`. Supported: 'google_meet'. Zoom and Teams coming soon.
  - `scheduled_at` string, nullable: ISO 8601 datetime when the meeting starts. Required when using `meeting_url`. The bot joins approximately 2 minutes after this time.
  - `recording_url` string, 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_id` string, 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_name` string, nullable: Full name of the candidate. Required on first submission (when no candidate_id).
  - `candidate_email` string, nullable: Candidate's email. Used for deduplication — same email = same candidate across interviews.
  - `role` string, required: Job role the candidate is being interviewed for.
  - `job_description` string, required: Full job description text. BetterHire uses this to extract competencies and score the candidate against the actual role requirements.
  - `resume_text` string, 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_type` string, 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).
  - `framework` string, 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.
  - `metadata` object, nullable: Arbitrary key-value metadata to attach to this interview. Returned in all subsequent responses. Use for your own internal IDs, tags, etc.

## Response `201`

Successful Response

- InterviewSubmitResponse: Response after submitting an interview for analysis.
  - `id` string, required: Unique interview ID. Use this to poll for status and retrieve results.
  - `candidate_id` string, required: Candidate ID. Store this — use it for subsequent interviews and to request debriefs.
  - `status` string, required: Initial status (always 'pending').
  - `input_mode` string, required: 'meeting' if a bot will join the call, or 'recording' if processing an uploaded recording.
  - `message` string, required: Human-readable confirmation 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)