> ## 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 an Interviewer

> Create an Interviewer with its full interview setup.

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.

> [!NOTE]
>
> **Rate limit:** 5 requests per minute per API key. This limit is shared with [Update an Interviewer](https://docs.interviewflowai.com/api-reference/interviewers/update.md). Requests over the limit return `429 Too Many Requests`.

Each API field maps to a step in the [Create an AI Interviewer](https://docs.interviewflowai.com/interview-automation/create-an-ai-interviewer/overview.md) dashboard workflow. Use the table below to see which fields correspond to each step.

## Dashboard field reference

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

## Payload structure

**title** `string` *required*

Interviewer title. Must contain 1–255 characters.

**role** `string` *required*

Interviewer role. Must contain 1–255 characters.

**jobDescription** `string` *required*

Interviewer description, including responsibilities, requirements, and benefits. Must contain 1–50,000 characters.

**interviewLanguage** `string` *required*

Language code for the interview: `english`, `hindi`, `spanish`, `french`, `chinese`, `german`, `italian`, `japanese`, `korean`, `portuguese`, `dutch`, `ukrainian`, `malay`, `indonesian`, `arabic`, or `vietnamese`.

**videoRequired** `boolean` *required*

Whether video responses are required.

**linkExpirationDays** `number` *required*

Days until the interview link expires. Minimum `1` and maximum `365`.

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

**introductionMessage** `string` *required*

Introduction message shown to Candidates. Must contain 1–1,000 characters.

**iceBreaker** `string` *required*

Ice breaker question. Maximum 500 characters. The field is required but can be an empty string.

**closingMessage** `string` *required*

Closing message shown to Candidates. Must contain 1–500 characters.

**customQuestionConfig** `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`.

**instructions** `string`

Interview instructions. Maximum 5,000 characters.

**interviewMode** `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`.

**resumeRequired** `boolean`

Whether a resume is required.

**portfolioRequired** `boolean`

Whether a portfolio is required.

**viewStatus** `string`

`public` or `private`.

**showToJobSeekers** `boolean`

Whether the Interviewer is visible to Candidates.

**isArchived** `boolean`

Whether the Interviewer is archived on creation.

**experienceMin** `number`

Minimum years of experience.

**experienceMax** `number`

Maximum years of experience.

**jobType** `string`

`full-time`, `part-time`, `contract`, or `intern`.

**locationType** `string` (default: remote)

`remote`, `onsite`, or `hybrid`. Onsite and hybrid Interviewers require `country`, `city`, and `zipcode`.

**country** `string`

Country. Required for onsite and hybrid Interviewers. Maximum 255 characters.

**city** `string`

City. Required for onsite and hybrid Interviewers. Maximum 255 characters.

**zipcode** `string`

Postal code. Required for onsite and hybrid Interviewers. Maximum 20 characters.

**context** `string`

Additional Interviewer context. Maximum 200 words and 5,000 characters. Required when `candidateQuestioning` is `true`.

**candidateQuestioning** `boolean`

Whether Candidates can ask the AI Interviewer questions. Requires `context`.

**candidateOptOutEnabled** `boolean`

Whether Candidates can opt out of the interview.

**interviewDuration** `number` (default: 10)

Duration in minutes. Minimum `10` and maximum `60`.

**desktopOnly** `boolean` (default: true)

Whether the interview requires a desktop device.

**showCaptions** `boolean` (default: true)

Whether Candidates see live captions and the transcript during the interview.

**retakesAllowed** `number`

Number of retakes allowed. Minimum `0` and maximum `3`.

**customQuestions** `object[]`

Custom interview questions with evaluation criteria.

**screeningQuestions** `object[]`

Screening questions shown before the interview.

**postInterviewQuestions** `object[]`

Questions shown after the interview.

**tags** `object[]`

Interviewer tags for categorization. Each tag has a `label` (1–100 characters) and up to 20 `options`. Maximum 25 tags.

**introVideoUrl** `string`

URL to an introduction video. Maximum 500 characters.

**completionRedirectUrl** `string`

URL where Candidates are redirected after the interview, or an empty string. Maximum 2,048 characters.

**webhookConfig** `object`

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. 1–200 characters. |
| `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`.

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

```bash cURL 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",
    "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. Webhooks require a Pro plan.

| 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. |

> [!NOTE]
>
> 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. |
| `assessment.shortlisted` | A candidate is shortlisted for an assessment. |
| `assessment.started` | A candidate starts an assessment. |
| `assessment.completed` | A candidate completes an assessment. |

## 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.

```json 201 theme={null}
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000101",
    "title": "Senior Software Engineer",
    "jobLink": "https://app.interviewflowai.com/public/00000000-0000-0000-0000-000000000101",
    "webhookConfig": {
      "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](https://docs.interviewflowai.com/api-reference/webhook-events.md#receive-events). See [Webhook events](https://docs.interviewflowai.com/api-reference/webhook-events.md) 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.

| Status | Message | Cause |
| - | - | - |
| `503` | Webhook configuration is currently unavailable | The webhook service isn't configured or reachable. |
| `502` | Failed to configure webhook | The webhook destination couldn't be registered. The Interviewer was rolled back. |

> [!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 `id` in subsequent ingest-candidate API calls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.