---
title: "Trigger AI screening interview"
method: POST
path: "/api/public/v1/screening"
tags: ["Public API v1 — Screening", "Public API v1 — AI Screening"]
---

# Trigger AI screening interview

`POST /api/public/v1/screening`

## 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/screening`
- Auth: HTTP bearer

Launch an AI-powered screening interview for a candidate. Two modes:

**Phone mode:** AI bot calls the candidate's phone immediately. Requires `candidate_phone` in E.164 format.

**Video mode:** Creates a video room and emails the candidate a join link. Candidate clicks the link to start the AI interview. Pass `send_invite: false` to skip our email and send `join_url` yourself; `invite_sent` in the response says which happened.

The AI bot conducts a 15-30 minute structured screening based on the job description. After the call ends, the recording is automatically transcribed and analyzed. Poll `GET /interviews/{id}` or register a webhook for `interview.analyzed` to get results.

**Repeat screenings.** A second screening of the same candidate on the same role is told every question the interviewer asked in that candidate's earlier completed interviews on the role, and does not re-ask them. The topics may overlap; the questions will not.

## Request body

- ScreeningRequest: Trigger an AI screening interview for a candidate.
  - `candidate_name` string, required: Full name of the candidate.
  - `candidate_email` string, required: Candidate's email address. Used for deduplication and video mode invites.
  - `candidate_phone` string, nullable: Candidate's phone number in E.164 format. Required for phone mode.
  - `role` string, required: Job title the candidate is being screened for.
  - `job_role_id` string, nullable: Exact role id to screen 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_description` string, required: Full job description text. The AI bot uses this to tailor screening questions.
  - `mode` string: Screening mode: 'phone' (AI calls candidate) or 'video' (candidate joins Daily.co room via email link).
  - `resume_text` string, nullable: Candidate's resume as plain text. Improves question relevance and gap analysis.
  - `company_name` string, nullable: Company name for the AI bot's introduction. Defaults to organization name.
  - `screening_questions` string[], nullable: Custom screening questions to include in the interview.
  - `metadata` object, nullable: Custom metadata to attach to this screening interview.
  - `return_url` string, nullable: Video mode only, and 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 screening.
  - `send_invite` boolean: Video mode only. 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`. Rejected in phone mode: the call is the contact, and there is nothing to withhold.

## Response `201`

Successful Response

- ScreeningResponse: Response after triggering a screening interview.
  - `interview_id` string, required: Interview ID. Use to poll status via GET /interviews/{id}.
  - `candidate_id` string, required: Candidate ID for future submissions.
  - `status` string, required: 'initiated' (phone) or 'scheduled' (video).
  - `mode` string, required: 'phone' or 'video'.
  - `join_url` string, nullable: For video mode: URL the candidate uses to join the screening room.
  - `invite_sent` boolean, nullable: Video mode: 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. Null in phone mode (the call is the contact).
  - `message` string, required: Human-readable status 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)