Create Interviewer API

curl --request POST \
  --url https://api.interviewflowai.com/api/external/ingest/job \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "title": "<string>",
  "role": "<string>",
  "jobDescription": "<string>",
  "interviewLanguage": "<string>",
  "videoRequired": true,
  "linkExpirationDays": 123,
  "introductionMessage": "<string>",
  "iceBreaker": "<string>",
  "closingMessage": "<string>",
  "customQuestionConfig": {},
  "instructions": "<string>",
  "interviewMode": "<string>",
  "resumeRequired": true,
  "portfolioRequired": true,
  "viewStatus": "<string>",
  "showToJobSeekers": true,
  "isArchived": true,
  "experienceMin": 123,
  "experienceMax": 123,
  "jobType": "<string>",
  "locationType": "<string>",
  "country": "<string>",
  "city": "<string>",
  "zipcode": "<string>",
  "context": "<string>",
  "interviewDuration": 123,
  "desktopOnly": true,
  "retakesAllowed": 123,
  "customQuestions": [
    {}
  ],
  "screeningQuestions": [
    {}
  ],
  "postInterviewQuestions": [
    {}
  ],
  "tags": [
    {}
  ],
  "introVideoUrl": "<string>",
  "completionRedirectUrl": "<string>",
  "webhookConfig": {}
}
'

import requests

url = "https://api.interviewflowai.com/api/external/ingest/job"

payload = {
    "title": "<string>",
    "role": "<string>",
    "jobDescription": "<string>",
    "interviewLanguage": "<string>",
    "videoRequired": True,
    "linkExpirationDays": 123,
    "introductionMessage": "<string>",
    "iceBreaker": "<string>",
    "closingMessage": "<string>",
    "customQuestionConfig": {},
    "instructions": "<string>",
    "interviewMode": "<string>",
    "resumeRequired": True,
    "portfolioRequired": True,
    "viewStatus": "<string>",
    "showToJobSeekers": True,
    "isArchived": True,
    "experienceMin": 123,
    "experienceMax": 123,
    "jobType": "<string>",
    "locationType": "<string>",
    "country": "<string>",
    "city": "<string>",
    "zipcode": "<string>",
    "context": "<string>",
    "interviewDuration": 123,
    "desktopOnly": True,
    "retakesAllowed": 123,
    "customQuestions": [{}],
    "screeningQuestions": [{}],
    "postInterviewQuestions": [{}],
    "tags": [{}],
    "introVideoUrl": "<string>",
    "completionRedirectUrl": "<string>",
    "webhookConfig": {}
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: '<string>',
    role: '<string>',
    jobDescription: '<string>',
    interviewLanguage: '<string>',
    videoRequired: true,
    linkExpirationDays: 123,
    introductionMessage: '<string>',
    iceBreaker: '<string>',
    closingMessage: '<string>',
    customQuestionConfig: {},
    instructions: '<string>',
    interviewMode: '<string>',
    resumeRequired: true,
    portfolioRequired: true,
    viewStatus: '<string>',
    showToJobSeekers: true,
    isArchived: true,
    experienceMin: 123,
    experienceMax: 123,
    jobType: '<string>',
    locationType: '<string>',
    country: '<string>',
    city: '<string>',
    zipcode: '<string>',
    context: '<string>',
    interviewDuration: 123,
    desktopOnly: true,
    retakesAllowed: 123,
    customQuestions: [{}],
    screeningQuestions: [{}],
    postInterviewQuestions: [{}],
    tags: [{}],
    introVideoUrl: '<string>',
    completionRedirectUrl: '<string>',
    webhookConfig: {}
  })
};

fetch('https://api.interviewflowai.com/api/external/ingest/job', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.interviewflowai.com/api/external/ingest/job",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => '<string>',
    'role' => '<string>',
    'jobDescription' => '<string>',
    'interviewLanguage' => '<string>',
    'videoRequired' => true,
    'linkExpirationDays' => 123,
    'introductionMessage' => '<string>',
    'iceBreaker' => '<string>',
    'closingMessage' => '<string>',
    'customQuestionConfig' => [
        
    ],
    'instructions' => '<string>',
    'interviewMode' => '<string>',
    'resumeRequired' => true,
    'portfolioRequired' => true,
    'viewStatus' => '<string>',
    'showToJobSeekers' => true,
    'isArchived' => true,
    'experienceMin' => 123,
    'experienceMax' => 123,
    'jobType' => '<string>',
    'locationType' => '<string>',
    'country' => '<string>',
    'city' => '<string>',
    'zipcode' => '<string>',
    'context' => '<string>',
    'interviewDuration' => 123,
    'desktopOnly' => true,
    'retakesAllowed' => 123,
    'customQuestions' => [
        [
                
        ]
    ],
    'screeningQuestions' => [
        [
                
        ]
    ],
    'postInterviewQuestions' => [
        [
                
        ]
    ],
    'tags' => [
        [
                
        ]
    ],
    'introVideoUrl' => '<string>',
    'completionRedirectUrl' => '<string>',
    'webhookConfig' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.interviewflowai.com/api/external/ingest/job"

	payload := strings.NewReader("{\n  \"title\": \"<string>\",\n  \"role\": \"<string>\",\n  \"jobDescription\": \"<string>\",\n  \"interviewLanguage\": \"<string>\",\n  \"videoRequired\": true,\n  \"linkExpirationDays\": 123,\n  \"introductionMessage\": \"<string>\",\n  \"iceBreaker\": \"<string>\",\n  \"closingMessage\": \"<string>\",\n  \"customQuestionConfig\": {},\n  \"instructions\": \"<string>\",\n  \"interviewMode\": \"<string>\",\n  \"resumeRequired\": true,\n  \"portfolioRequired\": true,\n  \"viewStatus\": \"<string>\",\n  \"showToJobSeekers\": true,\n  \"isArchived\": true,\n  \"experienceMin\": 123,\n  \"experienceMax\": 123,\n  \"jobType\": \"<string>\",\n  \"locationType\": \"<string>\",\n  \"country\": \"<string>\",\n  \"city\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"context\": \"<string>\",\n  \"interviewDuration\": 123,\n  \"desktopOnly\": true,\n  \"retakesAllowed\": 123,\n  \"customQuestions\": [\n    {}\n  ],\n  \"screeningQuestions\": [\n    {}\n  ],\n  \"postInterviewQuestions\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"introVideoUrl\": \"<string>\",\n  \"completionRedirectUrl\": \"<string>\",\n  \"webhookConfig\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.interviewflowai.com/api/external/ingest/job")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"<string>\",\n  \"role\": \"<string>\",\n  \"jobDescription\": \"<string>\",\n  \"interviewLanguage\": \"<string>\",\n  \"videoRequired\": true,\n  \"linkExpirationDays\": 123,\n  \"introductionMessage\": \"<string>\",\n  \"iceBreaker\": \"<string>\",\n  \"closingMessage\": \"<string>\",\n  \"customQuestionConfig\": {},\n  \"instructions\": \"<string>\",\n  \"interviewMode\": \"<string>\",\n  \"resumeRequired\": true,\n  \"portfolioRequired\": true,\n  \"viewStatus\": \"<string>\",\n  \"showToJobSeekers\": true,\n  \"isArchived\": true,\n  \"experienceMin\": 123,\n  \"experienceMax\": 123,\n  \"jobType\": \"<string>\",\n  \"locationType\": \"<string>\",\n  \"country\": \"<string>\",\n  \"city\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"context\": \"<string>\",\n  \"interviewDuration\": 123,\n  \"desktopOnly\": true,\n  \"retakesAllowed\": 123,\n  \"customQuestions\": [\n    {}\n  ],\n  \"screeningQuestions\": [\n    {}\n  ],\n  \"postInterviewQuestions\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"introVideoUrl\": \"<string>\",\n  \"completionRedirectUrl\": \"<string>\",\n  \"webhookConfig\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.interviewflowai.com/api/external/ingest/job")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"<string>\",\n  \"role\": \"<string>\",\n  \"jobDescription\": \"<string>\",\n  \"interviewLanguage\": \"<string>\",\n  \"videoRequired\": true,\n  \"linkExpirationDays\": 123,\n  \"introductionMessage\": \"<string>\",\n  \"iceBreaker\": \"<string>\",\n  \"closingMessage\": \"<string>\",\n  \"customQuestionConfig\": {},\n  \"instructions\": \"<string>\",\n  \"interviewMode\": \"<string>\",\n  \"resumeRequired\": true,\n  \"portfolioRequired\": true,\n  \"viewStatus\": \"<string>\",\n  \"showToJobSeekers\": true,\n  \"isArchived\": true,\n  \"experienceMin\": 123,\n  \"experienceMax\": 123,\n  \"jobType\": \"<string>\",\n  \"locationType\": \"<string>\",\n  \"country\": \"<string>\",\n  \"city\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"context\": \"<string>\",\n  \"interviewDuration\": 123,\n  \"desktopOnly\": true,\n  \"retakesAllowed\": 123,\n  \"customQuestions\": [\n    {}\n  ],\n  \"screeningQuestions\": [\n    {}\n  ],\n  \"postInterviewQuestions\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"introVideoUrl\": \"<string>\",\n  \"completionRedirectUrl\": \"<string>\",\n  \"webhookConfig\": {}\n}"

response = http.request(request)
puts response.read_body

POST

api

external

ingest

job

Create Interviewer API

curl --request POST \
  --url https://api.interviewflowai.com/api/external/ingest/job \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "title": "<string>",
  "role": "<string>",
  "jobDescription": "<string>",
  "interviewLanguage": "<string>",
  "videoRequired": true,
  "linkExpirationDays": 123,
  "introductionMessage": "<string>",
  "iceBreaker": "<string>",
  "closingMessage": "<string>",
  "customQuestionConfig": {},
  "instructions": "<string>",
  "interviewMode": "<string>",
  "resumeRequired": true,
  "portfolioRequired": true,
  "viewStatus": "<string>",
  "showToJobSeekers": true,
  "isArchived": true,
  "experienceMin": 123,
  "experienceMax": 123,
  "jobType": "<string>",
  "locationType": "<string>",
  "country": "<string>",
  "city": "<string>",
  "zipcode": "<string>",
  "context": "<string>",
  "interviewDuration": 123,
  "desktopOnly": true,
  "retakesAllowed": 123,
  "customQuestions": [
    {}
  ],
  "screeningQuestions": [
    {}
  ],
  "postInterviewQuestions": [
    {}
  ],
  "tags": [
    {}
  ],
  "introVideoUrl": "<string>",
  "completionRedirectUrl": "<string>",
  "webhookConfig": {}
}
'

import requests

url = "https://api.interviewflowai.com/api/external/ingest/job"

payload = {
    "title": "<string>",
    "role": "<string>",
    "jobDescription": "<string>",
    "interviewLanguage": "<string>",
    "videoRequired": True,
    "linkExpirationDays": 123,
    "introductionMessage": "<string>",
    "iceBreaker": "<string>",
    "closingMessage": "<string>",
    "customQuestionConfig": {},
    "instructions": "<string>",
    "interviewMode": "<string>",
    "resumeRequired": True,
    "portfolioRequired": True,
    "viewStatus": "<string>",
    "showToJobSeekers": True,
    "isArchived": True,
    "experienceMin": 123,
    "experienceMax": 123,
    "jobType": "<string>",
    "locationType": "<string>",
    "country": "<string>",
    "city": "<string>",
    "zipcode": "<string>",
    "context": "<string>",
    "interviewDuration": 123,
    "desktopOnly": True,
    "retakesAllowed": 123,
    "customQuestions": [{}],
    "screeningQuestions": [{}],
    "postInterviewQuestions": [{}],
    "tags": [{}],
    "introVideoUrl": "<string>",
    "completionRedirectUrl": "<string>",
    "webhookConfig": {}
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: '<string>',
    role: '<string>',
    jobDescription: '<string>',
    interviewLanguage: '<string>',
    videoRequired: true,
    linkExpirationDays: 123,
    introductionMessage: '<string>',
    iceBreaker: '<string>',
    closingMessage: '<string>',
    customQuestionConfig: {},
    instructions: '<string>',
    interviewMode: '<string>',
    resumeRequired: true,
    portfolioRequired: true,
    viewStatus: '<string>',
    showToJobSeekers: true,
    isArchived: true,
    experienceMin: 123,
    experienceMax: 123,
    jobType: '<string>',
    locationType: '<string>',
    country: '<string>',
    city: '<string>',
    zipcode: '<string>',
    context: '<string>',
    interviewDuration: 123,
    desktopOnly: true,
    retakesAllowed: 123,
    customQuestions: [{}],
    screeningQuestions: [{}],
    postInterviewQuestions: [{}],
    tags: [{}],
    introVideoUrl: '<string>',
    completionRedirectUrl: '<string>',
    webhookConfig: {}
  })
};

fetch('https://api.interviewflowai.com/api/external/ingest/job', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.interviewflowai.com/api/external/ingest/job",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => '<string>',
    'role' => '<string>',
    'jobDescription' => '<string>',
    'interviewLanguage' => '<string>',
    'videoRequired' => true,
    'linkExpirationDays' => 123,
    'introductionMessage' => '<string>',
    'iceBreaker' => '<string>',
    'closingMessage' => '<string>',
    'customQuestionConfig' => [
        
    ],
    'instructions' => '<string>',
    'interviewMode' => '<string>',
    'resumeRequired' => true,
    'portfolioRequired' => true,
    'viewStatus' => '<string>',
    'showToJobSeekers' => true,
    'isArchived' => true,
    'experienceMin' => 123,
    'experienceMax' => 123,
    'jobType' => '<string>',
    'locationType' => '<string>',
    'country' => '<string>',
    'city' => '<string>',
    'zipcode' => '<string>',
    'context' => '<string>',
    'interviewDuration' => 123,
    'desktopOnly' => true,
    'retakesAllowed' => 123,
    'customQuestions' => [
        [
                
        ]
    ],
    'screeningQuestions' => [
        [
                
        ]
    ],
    'postInterviewQuestions' => [
        [
                
        ]
    ],
    'tags' => [
        [
                
        ]
    ],
    'introVideoUrl' => '<string>',
    'completionRedirectUrl' => '<string>',
    'webhookConfig' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.interviewflowai.com/api/external/ingest/job"

	payload := strings.NewReader("{\n  \"title\": \"<string>\",\n  \"role\": \"<string>\",\n  \"jobDescription\": \"<string>\",\n  \"interviewLanguage\": \"<string>\",\n  \"videoRequired\": true,\n  \"linkExpirationDays\": 123,\n  \"introductionMessage\": \"<string>\",\n  \"iceBreaker\": \"<string>\",\n  \"closingMessage\": \"<string>\",\n  \"customQuestionConfig\": {},\n  \"instructions\": \"<string>\",\n  \"interviewMode\": \"<string>\",\n  \"resumeRequired\": true,\n  \"portfolioRequired\": true,\n  \"viewStatus\": \"<string>\",\n  \"showToJobSeekers\": true,\n  \"isArchived\": true,\n  \"experienceMin\": 123,\n  \"experienceMax\": 123,\n  \"jobType\": \"<string>\",\n  \"locationType\": \"<string>\",\n  \"country\": \"<string>\",\n  \"city\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"context\": \"<string>\",\n  \"interviewDuration\": 123,\n  \"desktopOnly\": true,\n  \"retakesAllowed\": 123,\n  \"customQuestions\": [\n    {}\n  ],\n  \"screeningQuestions\": [\n    {}\n  ],\n  \"postInterviewQuestions\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"introVideoUrl\": \"<string>\",\n  \"completionRedirectUrl\": \"<string>\",\n  \"webhookConfig\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.interviewflowai.com/api/external/ingest/job")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"<string>\",\n  \"role\": \"<string>\",\n  \"jobDescription\": \"<string>\",\n  \"interviewLanguage\": \"<string>\",\n  \"videoRequired\": true,\n  \"linkExpirationDays\": 123,\n  \"introductionMessage\": \"<string>\",\n  \"iceBreaker\": \"<string>\",\n  \"closingMessage\": \"<string>\",\n  \"customQuestionConfig\": {},\n  \"instructions\": \"<string>\",\n  \"interviewMode\": \"<string>\",\n  \"resumeRequired\": true,\n  \"portfolioRequired\": true,\n  \"viewStatus\": \"<string>\",\n  \"showToJobSeekers\": true,\n  \"isArchived\": true,\n  \"experienceMin\": 123,\n  \"experienceMax\": 123,\n  \"jobType\": \"<string>\",\n  \"locationType\": \"<string>\",\n  \"country\": \"<string>\",\n  \"city\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"context\": \"<string>\",\n  \"interviewDuration\": 123,\n  \"desktopOnly\": true,\n  \"retakesAllowed\": 123,\n  \"customQuestions\": [\n    {}\n  ],\n  \"screeningQuestions\": [\n    {}\n  ],\n  \"postInterviewQuestions\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"introVideoUrl\": \"<string>\",\n  \"completionRedirectUrl\": \"<string>\",\n  \"webhookConfig\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.interviewflowai.com/api/external/ingest/job")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"<string>\",\n  \"role\": \"<string>\",\n  \"jobDescription\": \"<string>\",\n  \"interviewLanguage\": \"<string>\",\n  \"videoRequired\": true,\n  \"linkExpirationDays\": 123,\n  \"introductionMessage\": \"<string>\",\n  \"iceBreaker\": \"<string>\",\n  \"closingMessage\": \"<string>\",\n  \"customQuestionConfig\": {},\n  \"instructions\": \"<string>\",\n  \"interviewMode\": \"<string>\",\n  \"resumeRequired\": true,\n  \"portfolioRequired\": true,\n  \"viewStatus\": \"<string>\",\n  \"showToJobSeekers\": true,\n  \"isArchived\": true,\n  \"experienceMin\": 123,\n  \"experienceMax\": 123,\n  \"jobType\": \"<string>\",\n  \"locationType\": \"<string>\",\n  \"country\": \"<string>\",\n  \"city\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"context\": \"<string>\",\n  \"interviewDuration\": 123,\n  \"desktopOnly\": true,\n  \"retakesAllowed\": 123,\n  \"customQuestions\": [\n    {}\n  ],\n  \"screeningQuestions\": [\n    {}\n  ],\n  \"postInterviewQuestions\": [\n    {}\n  ],\n  \"tags\": [\n    {}\n  ],\n  \"introVideoUrl\": \"<string>\",\n  \"completionRedirectUrl\": \"<string>\",\n  \"webhookConfig\": {}\n}"

response = http.request(request)
puts response.read_body

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

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.

string

required

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

boolean

required

Whether video responses are required.

number

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. You can omit this field.

string

required

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

object

required

Configuration for manual, resume, and skills question sections.

string

Interview instructions.

string

default:"web_call"

web_call, phone_only, or both.

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, or contract.

string

default:"remote"

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

string

Country. Required for onsite Interviewers.

string

City. Required for onsite Interviewers.

string

Postal code. Required for onsite Interviewers.

string

Additional Interviewer context. Maximum 200 words.

number

default:"10"

Duration in minutes. Minimum 10 and maximum 60.

boolean

default:"true"

Whether the interview requires a desktop device.

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

string

URL to an introduction video.

string

HTTP or HTTPS URL where Candidates are redirected after the interview.

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

Create Interviewer API

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