Skip to main content
POST
Use this API to invite up to 50 candidates to one Interviewer in a single request. InterviewFlowAI creates an interview for each candidate and emails them their invitation, either right away or after a delay you choose.
Rate limit: 100 requests per minute per API key. Requests over the limit return 429 Too Many Requests.

Payload structure

string
required
The UUID of the Interviewer to invite Candidates to. The Interviewer must belong to your Company. If the Interviewer is archived, the interviews are still created but no invitation emails are sent.
string
shortlisted or draft. Controls the onboarding experience.
object[]
required
Candidates to invite. Minimum 1 and maximum 50 per request.
string
required
Candidate’s full name, 1–255 characters.
string
required
Candidate’s email address. The value is normalized to lowercase.
string[]
Skills used to generate skill-based questions for this Candidate, such as nodejs, aws, and mongodb.
object[]
Candidate-specific questions. Each item needs question and evaluationCriteria (lookingFor, strongAnswer, weakAnswer, weight 1–10, maxFollowup 0–2, and optional maxDuration 0.5–10 minutes).
object
Custom key-value fields to tag against the Candidate, such as scores or flags.
object
External reference data, such as an ATS ID or phone number. This data is not used in scoring. The keys teamtailor, ashby, workable and recruitcrm are reserved for built-in integrations and are removed from API requests.
number
Whole number of hours to delay the invitation email. Minimum 1 and maximum 96. Omit to send immediately.

Status routing

Default behavior (when status is omitted)

Response

The endpoint returns 201 Created when at least one Candidate is invited, otherwise 200 OK. Each Candidate appears in one of three lists.
Best Practice: Trigger this API call automatically when a candidate reaches a specific stage in your ATS (e.g. “Phone Screen” or “AI Interview”).