Skip to main content
POST
Use this API to invite one candidate at a time. The endpoint creates the interview, emails the invitation to the candidate, and returns the direct interview link.
Rate limit: 100 requests per minute per API key. Requests over the limit return 429 Too Many Requests.

Request body fields

string
required
Candidate’s full name. Maximum 255 characters. Blank names are rejected.
string
required
Candidate’s email address. The value is normalized to lowercase.
string
required
The UUID of the Interviewer to create the interview under. Archived Interviewers are rejected.
string
shortlisted or draft. If omitted, public Interviewers default to shortlisted and private Interviewers default to draft.
string
A publicly accessible URL to the Candidate’s resume (PDF). InterviewFlowAI downloads the file and stores it as a PDF. If the download fails, the interview is still created, without a resume, and no error is returned.
string[]
Skill names used to generate skill-based custom interview questions. If generation fails, the request returns 500 “Failed to generate skill test questions”.
object[]
Candidate-specific custom questions to attach to the interview.
object
Custom Candidate fields configured in InterviewFlowAI.
object
External reference data such as ATS IDs. metadata.phoneNumber sets the Candidate’s phone number.

Response

Behavior

Use this endpoint when your ATS, CRM, or internal system also needs the interview link, for example to store it on the candidate record.