Public API v1 — Screening
Public API v1 — AI Screening

Trigger AI screening interview

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.

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

Request body

candidate_namestring required

Full name of the candidate.

candidate_emailstring required

Candidate's email address. Used for deduplication and video mode invites.

candidate_phonestring nullable

Candidate's phone number in E.164 format. Required for phone mode.

rolestring required

Job title the candidate is being screened for.

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

Full job description text. The AI bot uses this to tailor screening questions.

modestring

Screening mode: 'phone' (AI calls candidate) or 'video' (candidate joins Daily.co room via email link).

resume_textstring nullable

Candidate's resume as plain text. Improves question relevance and gap analysis.

company_namestring nullable

Company name for the AI bot's introduction. Defaults to organization name.

screening_questionsstring[] nullable

Custom screening questions to include in the interview.

metadataobject nullable

Custom metadata to attach to this screening interview.

return_urlstring 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_inviteboolean

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.

Example request

{
  "candidate_name": "Raj Patel",
  "candidate_email": "raj.patel@example.com",
  "candidate_phone": "+919876543210",
  "role": "Senior Backend Engineer",
  "job_role_id": "9ebd749c-3462-437a-8a17-81395b772568",
  "screening_questions": [
    "Why are you looking to leave your current role?",
    "What's your expected compensation?"
  ]
}

Response

Successful Response

interview_idstring required

Interview ID. Use to poll status via GET /interviews/{id}.

candidate_idstring required

Candidate ID for future submissions.

statusstring required

'initiated' (phone) or 'scheduled' (video).

modestring required

'phone' or 'video'.

join_urlstring nullable

For video mode: URL the candidate uses to join the screening room.

invite_sentboolean 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).

messagestring required

Human-readable status message.

Changes

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