Create Interviewer API

The Create Interviewer API allows you to programmatically create Interviewers with full interview configuration.

Rate limit: 5 requests per minute per API key. This limit is shared with the Update Interviewer API. 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

Dashboard step	API fields
Role details	`title`, `role`, `jobDescription`, `experienceMin`, `experienceMax`, `jobType`, `locationType`, `country`, `city`, `zipcode`, `context`, `tags`
Interview settings	`interviewLanguage`, `interviewDuration`, `linkExpirationDays`, `retakesAllowed`, `videoRequired`, `portfolioRequired`, `desktopOnly`, `introVideoUrl`, `introductionMessage`, `iceBreaker`, `closingMessage`, `postInterviewQuestions`
Application form	`screeningQuestions`
Question settings	`customQuestionConfig`
Questions	`customQuestions`

Payload structure

Field	Type	Required	Description
`title`	string	✅ Yes	Interviewer title (1–255 characters).
`role`	string	✅ Yes	Interviewer role (1–255 characters).
`jobDescription`	string	✅ Yes	Interviewer job description, including responsibilities, requirements, and benefits.
`interviewLanguage`	string	✅ Yes	Language code for the interview (`english`, `hindi`, `spanish`, `french`, `chinese`, `german`, `italian`, `japanese`, `korean`, `portuguese`, `dutch`, `ukrainian`).
`videoRequired`	boolean	✅ Yes	Whether video responses are required.
`linkExpirationDays`	number	✅ Yes	Days until the interview link expires (1–365).

The following message fields support template variables like {fullName}, {firstName}, {jobTitle}, and {jobRole}, which are automatically replaced during the interview.

Field	Type	Required	Description
`introductionMessage`	string	✅ Yes	Introduction message shown to candidates (1–1000 chars).
`iceBreaker`	string	✅ Yes	Ice breaker question (max 500 chars). Optional — can be omitted.
`closingMessage`	string	✅ Yes	Closing message shown to candidates (1–500 chars).
`customQuestionConfig`	object	✅ Yes	Configuration for manual, resume, and skills question sections.
`instructions`	string	❌ No	Interview instructions.
`interviewMode`	string	❌ No	`web_call` (default), `phone_only`, or `both`.
`resumeRequired`	boolean	❌ No	Whether a resume is required.
`portfolioRequired`	boolean	❌ No	Whether a portfolio is required.
`viewStatus`	string	❌ No	`public` or `private`.
`showToJobSeekers`	boolean	❌ No	Whether visible to candidates.
`isArchived`	boolean	❌ No	Whether the Interviewer is archived on creation.
`experienceMin`	number	❌ No	Minimum years of experience.
`experienceMax`	number	❌ No	Maximum years of experience.
`jobType`	string	❌ No	`full-time`, `part-time`, or `contract`.
`locationType`	string	❌ No	`remote` (default) or `onsite`. Required fields for onsite: `country`, `city`, `zipcode`.
`country`	string	❌ No	Country (required for onsite).
`city`	string	❌ No	City (required for onsite).
`zipcode`	string	❌ No	Zipcode (required for onsite).
`context`	string	❌ No	Additional Interviewer context (max 200 words).
`interviewDuration`	number	❌ No	Duration in minutes (10–60, default: 10).
`desktopOnly`	boolean	❌ No	Desktop-only interview (default: true).
`retakesAllowed`	number	❌ No	Number of retakes allowed (0–3).
`customQuestions`	array	❌ No	Array of custom interview questions with evaluation criteria.
`screeningQuestions`	array	❌ No	Pre-screening questions shown before the interview.
`postInterviewQuestions`	array	❌ No	Post-interview questions shown after completion.
`tags`	array	❌ No	Interviewer tags for categorization (max 25).
`introVideoUrl`	string	❌ No	URL to an intro video.
`completionRedirectUrl`	string	❌ No	URL where candidates are redirected after completing the interview. Must be a valid HTTP(S) URL.
`webhookConfig`	object	❌ No	Webhook destination and subscribed interview events.

Screening question fields

Each screeningQuestions item uses the following fields:

Field	Type	Description
`question`	string	Question shown to the Candidate.
`type`	string	`numeric`, `text`, or `yesno`.
`expectedAnswer`	string	Numeric target, minimum, or range minimum. Required for every screening question.
`idealAnswerType`	string	Numeric comparison: `min` (default), `max`, `exact`, or `range`.
`expectedAnswerMax`	string	Range maximum. Required when `idealAnswerType` is `range`.
`isRequired`	boolean	Whether the Candidate must answer the question.
`mustHaveQualification`	boolean	Whether a failed answer declines the Candidate.

Numeric comparisons are inclusive. For a range, expectedAnswer must be less than expectedAnswerMax.

{
  "question": "How many years of experience do you have?",
  "type": "numeric",
  "idealAnswerType": "min",
  "expectedAnswer": "5",
  "isRequired": true,
  "mustHaveQualification": true
}

Example request

curl -X POST "https://api.interviewflowai.com/api/external/ingest/job" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "title": "Senior Software Engineer",
    "role": "Backend Developer",
    "jobDescription": "Build scalable backend systems. Requirements: 5+ years of experience with Node.js, AWS, and MongoDB, with strong problem-solving skills. Benefits: Health insurance, 401k, unlimited PTO, remote-first culture, and an annual learning stipend.",
    "interviewLanguage": "english",
    "videoRequired": true,
    "linkExpirationDays": 4,
    "introductionMessage": "Hi {firstName}, I'\''ll be your AI interviewer today. It'\''s a pleasure to meet you! This is a structured interview designed to provide a fair and consistent experience for all candidates. For each question, you'\''ll have about two minutes to respond. If you don'\''t understand a question, you can ask me to repeat it. Are you ready to get started?",
    "iceBreaker": "To start off, could you tell me a little about yourself and what excites you about the {jobTitle} role?",
    "closingMessage": "Thank you for completing the interview. We appreciate the time and effort you have taken to share your experience with us. Your responses will now be reviewed as part of our selection process. If your profile is shortlisted for the next stage, our team will contact you directly. Thank you again for your interest in the opportunity, and we wish you all the best.",
    "customQuestionConfig": {
      "sectionOrder": ["manual", "resume"],
      "manual": { "enabled": true },
      "resume": {
        "enabled": true,
        "maxQuestions": 3,
        "maxDuration": 3,
        "generationInstructions": "Focus on relevant experience from the candidate resume."
      }
    },
    "instructions": "Please ensure you are in a quiet environment with a stable internet connection.",
    "interviewMode": "web_call",
    "resumeRequired": true,
    "portfolioRequired": false,
    "viewStatus": "public",
    "experienceMin": 3,
    "experienceMax": 7,
    "jobType": "full-time",
    "locationType": "remote",
    "context": "This role is part of the core platform team building next-generation hiring tools.",
    "interviewDuration": 20,
    "desktopOnly": true,
    "completionRedirectUrl": "https://yourcompany.com/thank-you",
    "customQuestions": [
      {
        "question": "Describe a challenging project you worked on recently.",
        "generationSource": "manual",
        "evaluationCriteria": {
          "lookingFor": "Clear problem description, technical depth, and impact metrics",
          "strongAnswer": "Articulates the problem, approach, and measurable outcomes with specifics",
          "weakAnswer": "Vague description without technical details or quantifiable results",
          "weight": 5,
          "maxFollowup": 1,
          "maxDuration": 3
        }
      }
    ],
    "tags": [
      { "label": "Department", "options": ["Engineering", "Platform"] },
      { "label": "Seniority", "options": ["Senior"] }
    ],
    "webhookConfig": {
      "url": "https://example.com/webhooks/interviews",
      "events": [
        "interview.created",
        "interview.started",
        "interview.completed",
        "interview.report_available"
      ]
    }
  }'

Webhook configuration

Use webhookConfig to register a webhook destination when creating the Interviewer. Your account must have access to the Svix webhooks feature.

Field	Type	Required	Description
`webhookConfig.url`	string	✅ Yes	HTTP or HTTPS URL that receives webhook deliveries (max 2000 characters).
`webhookConfig.events`	string[]	✅ Yes	One or more unique supported event types.

Both url and events are required when webhookConfig is supplied. Duplicate or unsupported events are rejected.

Event	Trigger
`interview.created`	A new candidate is added to the Interviewer.
`interview.started`	A candidate starts the interview.
`interview.completed`	A candidate completes the interview.
`interview.declined`	A candidate is declined for an interview.
`interview.opted_out`	A candidate opts out of an interview.
`interview.report_available`	The interview report becomes available.

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.

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000101",
    "title": "Senior Software Engineer",
    "jobLink": "https://app.interviewflowai.com/public/00000000-0000-0000-0000-000000000101",
    "webhook": {
      "endpointId": "ep_01JEXAMPLE",
      "url": "https://example.com/webhooks/interviews",
      "events": [
        "interview.created",
        "interview.started",
        "interview.completed",
        "interview.report_available"
      ],
      "secret": "whsec_EXAMPLE"
    }
  },
  "code": 201,
  "message": "Job created successfully"
}

Store the signing secret securely and use it to verify webhook signatures. The webhook property is omitted when no webhook configuration is supplied.

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.

Getting Started

Main

Manage

Settings

Additional Platform Docs

For Candidates

Dashboard field reference

Payload structure

Screening question fields

Example request

Webhook configuration

Response

​Dashboard field reference

​Payload structure

​Screening question fields

​Example request

​Webhook configuration

​Response

Dashboard field reference

Payload structure

Screening question fields

Example request

Webhook configuration

Response