> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interviewflowai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Interviewer API

> Create new Interviewers with full interview configuration programmatically.

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](/interview-automation/create-an-ai-interviewer/overview) dashboard workflow. Use the table below to see which fields correspond to each step.

## Dashboard field reference

| Dashboard step                                                                          | API fields                                                                                                                                                                                                                              |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Role details](/interview-automation/create-an-ai-interviewer/role-details)             | `title`, `role`, `description`, `requirements`, `experienceMin`, `experienceMax`, `jobType`, `locationType`, `country`, `city`, `zipcode`, `benefits`, `context`, `tags`                                                                |
| [Interview settings](/interview-automation/create-an-ai-interviewer/interview-settings) | `interviewLanguage`, `interviewDuration`, `linkExpirationDays`, `retakesAllowed`, `videoRequired`, `portfolioRequired`, `desktopOnly`, `introVideoUrl`, `introductionMessage`, `iceBreaker`, `closingMessage`, `postInterviewQuestions` |
| [Application form](/interview-automation/create-an-ai-interviewer/application-form)     | `screeningQuestions`                                                                                                                                                                                                                    |
| [Question settings](/interview-automation/create-an-ai-interviewer/question-settings)   | `customQuestionConfig`                                                                                                                                                                                                                  |
| [Questions](/interview-automation/create-an-ai-interviewer/questions)                   | `customQuestions`                                                                                                                                                                                                                       |

## Payload structure

| Field                | Type    | Required | Description                                                                                                                                                          |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`              | string  | ✅ Yes    | Interviewer title (1–255 characters).                                                                                                                                |
| `role`               | string  | ✅ Yes    | Interviewer role (1–255 characters).                                                                                                                                 |
| `description`        | string  | ✅ Yes    | Interviewer description.                                                                                                                                             |
| `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).                                                                                                                       |

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

| 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.                                  |
| `requirements`           | string  | ❌ No     | Interviewer requirements.                                                                        |
| `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).                                                                   |
| `benefits`               | string  | ❌ No     | Interviewer benefits (max 5000 chars).                                                           |
| `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. |

## Example request

```bash theme={null}
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"] }
    ]
  }'
```

<Tip>
  **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.
</Tip>