Skip to main content
The Create Interviewer API allows you to programmatically create Interviewers with full interview configuration. 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 stepAPI fields
Role detailstitle, role, description, requirements, experienceMin, experienceMax, jobType, locationType, country, city, zipcode, benefits, context, tags
Interview settingsinterviewLanguage, interviewDuration, linkExpirationDays, retakesAllowed, videoRequired, portfolioRequired, desktopOnly, introVideoUrl, introductionMessage, iceBreaker, closingMessage, postInterviewQuestions
Application formscreeningQuestions
Question settingscustomQuestionConfig
QuestionscustomQuestions

​
Payload structure

FieldTypeRequiredDescription
titlestring✅ YesInterviewer title (1–255 characters).
rolestring✅ YesInterviewer role (1–255 characters).
descriptionstring✅ YesInterviewer description.
interviewLanguagestring✅ YesLanguage code for the interview (english, hindi, spanish, french, chinese, german, italian, japanese, korean, portuguese, dutch, ukrainian).
videoRequiredboolean✅ YesWhether video responses are required.
linkExpirationDaysnumber✅ YesDays 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.
FieldTypeRequiredDescription
introductionMessagestring✅ YesIntroduction message shown to candidates (1–1000 chars).
iceBreakerstring✅ YesIce breaker question (max 500 chars). Optional — can be omitted.
closingMessagestring✅ YesClosing message shown to candidates (1–500 chars).
customQuestionConfigobject✅ YesConfiguration for manual, resume, and skills question sections.
requirementsstring❌ NoInterviewer requirements.
instructionsstring❌ NoInterview instructions.
interviewModestring❌ Noweb_call (default), phone_only, or both.
resumeRequiredboolean❌ NoWhether a resume is required.
portfolioRequiredboolean❌ NoWhether a portfolio is required.
viewStatusstring❌ Nopublic or private.
showToJobSeekersboolean❌ NoWhether visible to candidates.
isArchivedboolean❌ NoWhether the Interviewer is archived on creation.
experienceMinnumber❌ NoMinimum years of experience.
experienceMaxnumber❌ NoMaximum years of experience.
jobTypestring❌ Nofull-time, part-time, or contract.
locationTypestring❌ Noremote (default) or onsite. Required fields for onsite: country, city, zipcode.
countrystring❌ NoCountry (required for onsite).
citystring❌ NoCity (required for onsite).
zipcodestring❌ NoZipcode (required for onsite).
benefitsstring❌ NoInterviewer benefits (max 5000 chars).
contextstring❌ NoAdditional Interviewer context (max 200 words).
interviewDurationnumber❌ NoDuration in minutes (10–60, default: 10).
desktopOnlyboolean❌ NoDesktop-only interview (default: true).
retakesAllowednumber❌ NoNumber of retakes allowed (0–3).
customQuestionsarray❌ NoArray of custom interview questions with evaluation criteria.
screeningQuestionsarray❌ NoPre-screening questions shown before the interview.
postInterviewQuestionsarray❌ NoPost-interview questions shown after completion.
tagsarray❌ NoInterviewer tags for categorization (max 25).
introVideoUrlstring❌ NoURL to an intro video.
completionRedirectUrlstring❌ NoURL where candidates are redirected after completing the interview. Must be a valid HTTP(S) URL.

​
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",
    "description": "We are looking for an experienced backend engineer to join our team and build scalable systems.",
    "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."
      }
    },
    "requirements": "5+ years of experience with Node.js, AWS, and MongoDB. Strong problem-solving skills.",
    "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",
    "benefits": "Health insurance, 401k, unlimited PTO, remote-first culture, annual learning stipend.",
    "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"] }
    ]
  }'
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 jobId in subsequent ingest-candidate API calls.