Skip to main content
POST
Use the Create Interviewer API to set up a new Interviewer from your ATS or internal tools instead of the dashboard. Send the same settings you would fill in on the dashboard, and you get back the new Interviewer’s ID and public link.
Rate limit: 5 requests per minute per API key. This limit is shared with Update an Interviewer. Requests over the limit return 429 Too Many Requests.
Each API field maps to a step in the Create an AI Interviewer dashboard workflow. Use the table below to see which fields correspond to each step.

Dashboard field reference

Payload structure

string
required
Interviewer title. Must contain 1–255 characters.
string
required
Interviewer role. Must contain 1–255 characters.
string
required
Interviewer description, including responsibilities, requirements, and benefits. Must contain 1–50,000 characters.
string
required
Language code for the interview: english, hindi, spanish, french, chinese, german, italian, japanese, korean, portuguese, dutch, ukrainian, malay, indonesian, arabic, or vietnamese.
boolean
required
Whether video responses are required.
Days until the interview link expires. Minimum 1 and maximum 365.
The following message fields support template variables like {fullName}, {firstName}, {jobTitle}, and {jobRole}, which are automatically replaced during the interview.
string
required
Introduction message shown to Candidates. Must contain 1–1,000 characters.
string
required
Ice breaker question. Maximum 500 characters. The field is required but can be an empty string.
string
required
Closing message shown to Candidates. Must contain 1–500 characters.
object
required
Configuration for manual, resume, and skills question sections. Set manual.enabled to true when you send customQuestions, and set resume.enabled to true when resumeRequired is true.
string
Interview instructions. Maximum 5,000 characters.
string
default:"web_call"
web_call, phone_only, or both. Phone modes require Twilio phone call credentials configured for your Company. When phone_only, videoRequired must be false.
boolean
Whether a resume is required.
boolean
Whether a portfolio is required.
string
public or private.
boolean
Whether the Interviewer is visible to Candidates.
boolean
Whether the Interviewer is archived on creation.
number
Minimum years of experience.
number
Maximum years of experience.
string
full-time, part-time, contract, or intern.
string
default:"remote"
remote, onsite, or hybrid. Onsite and hybrid Interviewers require country, city, and zipcode.
string
Country. Required for onsite and hybrid Interviewers. Maximum 255 characters.
string
City. Required for onsite and hybrid Interviewers. Maximum 255 characters.
string
Postal code. Required for onsite and hybrid Interviewers. Maximum 20 characters.
string
Additional Interviewer context. Maximum 200 words and 5,000 characters. Required when candidateQuestioning is true.
boolean
Whether Candidates can ask the AI Interviewer questions. Requires context.
boolean
Whether Candidates can opt out of the interview.
number
default:"10"
Duration in minutes. Minimum 10 and maximum 60.
boolean
default:"true"
Whether the interview requires a desktop device.
boolean
default:"true"
Whether Candidates see live captions and the transcript during the interview.
number
Number of retakes allowed. Minimum 0 and maximum 3.
object[]
Custom interview questions with evaluation criteria.
object[]
Screening questions shown before the interview.
object[]
Questions shown after the interview.
object[]
Interviewer tags for categorization. Each tag has a label (1–100 characters) and up to 20 options. Maximum 25 tags.
string
URL to an introduction video. Maximum 500 characters.
string
URL where Candidates are redirected after the interview, or an empty string. Maximum 2,048 characters.
object
Webhook destination and subscribed interview events.

Screening question fields

Each screeningQuestions item uses the following fields: Numeric comparisons are inclusive. For a range, expectedAnswer must be less than expectedAnswerMax.

Webhook configuration

Use webhookConfig to register a webhook destination when creating the Interviewer. Webhooks require a Pro plan.
Both url and events are required when webhookConfig is supplied. Duplicate or unsupported events are rejected.

Response

The endpoint returns 201 Created with the Interviewer ID, title, and public link. When webhookConfig is supplied, it also returns the registered endpoint and signing secret.
Store the signing secret securely and use it to verify webhook signatures. See Webhook events for the data each event sends. The webhookConfig property is omitted when no webhook configuration is supplied. If webhook setup fails, the Interviewer isn’t kept: InterviewFlowAI deletes it and returns an error. Retry the whole request.
Best Practice: Use this endpoint to create Interviewers programmatically from your ATS or internal tools whenever a new position opens. You can then use the returned id in subsequent ingest-candidate API calls.