Interview Invite

curl --request POST \
  --url https://api.tidyhire.app/api/public/v1/interview/invite \
  --header 'Content-Type: application/json' \
  --header 'x-tidyhire-api-key: <api-key>' \
  --data '
{
  "ats_job_id": "ats-job-12345",
  "job_title": "Senior Software Engineer",
  "job_description": "We are looking for a Senior Software Engineer to join our team and build scalable backend services.",
  "min_experience": 3,
  "max_experience": 5,
  "seniority_level": "Senior",
  "work_type": "Remote",
  "employment_type": "Full Time",
  "location": "New York, NY",
  "skills_required": [
    "JavaScript",
    "Node.js",
    "MongoDB"
  ],
  "skills_good_to_have": [
    "TypeScript",
    "Redis",
    "Docker"
  ],
  "candidates": [
    {
      "id": "ats-candidate-001",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890"
    }
  ],
  "interview_questions": [
    {
      "id": "a1b2c3d4e5f60123456789abcdef0123",
      "question": "Tell me about a production application you led. What architecture choices did you make?",
      "type": "verbal"
    }
  ],
  "interview_settings": {
    "cutoff_score": 50,
    "interview_duration": "30 Minutes"
  }
}
'

import requests

url = "https://api.tidyhire.app/api/public/v1/interview/invite"

payload = {
    "ats_job_id": "ats-job-12345",
    "job_title": "Senior Software Engineer",
    "job_description": "We are looking for a Senior Software Engineer to join our team and build scalable backend services.",
    "min_experience": 3,
    "max_experience": 5,
    "seniority_level": "Senior",
    "work_type": "Remote",
    "employment_type": "Full Time",
    "location": "New York, NY",
    "skills_required": ["JavaScript", "Node.js", "MongoDB"],
    "skills_good_to_have": ["TypeScript", "Redis", "Docker"],
    "candidates": [
        {
            "id": "ats-candidate-001",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "phone": "+1234567890"
        }
    ],
    "interview_questions": [
        {
            "id": "a1b2c3d4e5f60123456789abcdef0123",
            "question": "Tell me about a production application you led. What architecture choices did you make?",
            "type": "verbal"
        }
    ],
    "interview_settings": {
        "cutoff_score": 50,
        "interview_duration": "30 Minutes"
    }
}
headers = {
    "x-tidyhire-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-tidyhire-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ats_job_id: 'ats-job-12345',
    job_title: 'Senior Software Engineer',
    job_description: 'We are looking for a Senior Software Engineer to join our team and build scalable backend services.',
    min_experience: 3,
    max_experience: 5,
    seniority_level: 'Senior',
    work_type: 'Remote',
    employment_type: 'Full Time',
    location: 'New York, NY',
    skills_required: ['JavaScript', 'Node.js', 'MongoDB'],
    skills_good_to_have: ['TypeScript', 'Redis', 'Docker'],
    candidates: [
      {
        id: 'ats-candidate-001',
        name: 'John Doe',
        email: 'john.doe@example.com',
        phone: '+1234567890'
      }
    ],
    interview_questions: [
      {
        id: 'a1b2c3d4e5f60123456789abcdef0123',
        question: 'Tell me about a production application you led. What architecture choices did you make?',
        type: 'verbal'
      }
    ],
    interview_settings: {cutoff_score: 50, interview_duration: '30 Minutes'}
  })
};

fetch('https://api.tidyhire.app/api/public/v1/interview/invite', 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.tidyhire.app/api/public/v1/interview/invite",
  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([
    'ats_job_id' => 'ats-job-12345',
    'job_title' => 'Senior Software Engineer',
    'job_description' => 'We are looking for a Senior Software Engineer to join our team and build scalable backend services.',
    'min_experience' => 3,
    'max_experience' => 5,
    'seniority_level' => 'Senior',
    'work_type' => 'Remote',
    'employment_type' => 'Full Time',
    'location' => 'New York, NY',
    'skills_required' => [
        'JavaScript',
        'Node.js',
        'MongoDB'
    ],
    'skills_good_to_have' => [
        'TypeScript',
        'Redis',
        'Docker'
    ],
    'candidates' => [
        [
                'id' => 'ats-candidate-001',
                'name' => 'John Doe',
                'email' => 'john.doe@example.com',
                'phone' => '+1234567890'
        ]
    ],
    'interview_questions' => [
        [
                'id' => 'a1b2c3d4e5f60123456789abcdef0123',
                'question' => 'Tell me about a production application you led. What architecture choices did you make?',
                'type' => 'verbal'
        ]
    ],
    'interview_settings' => [
        'cutoff_score' => 50,
        'interview_duration' => '30 Minutes'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-tidyhire-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.tidyhire.app/api/public/v1/interview/invite"

	payload := strings.NewReader("{\n  \"ats_job_id\": \"ats-job-12345\",\n  \"job_title\": \"Senior Software Engineer\",\n  \"job_description\": \"We are looking for a Senior Software Engineer to join our team and build scalable backend services.\",\n  \"min_experience\": 3,\n  \"max_experience\": 5,\n  \"seniority_level\": \"Senior\",\n  \"work_type\": \"Remote\",\n  \"employment_type\": \"Full Time\",\n  \"location\": \"New York, NY\",\n  \"skills_required\": [\n    \"JavaScript\",\n    \"Node.js\",\n    \"MongoDB\"\n  ],\n  \"skills_good_to_have\": [\n    \"TypeScript\",\n    \"Redis\",\n    \"Docker\"\n  ],\n  \"candidates\": [\n    {\n      \"id\": \"ats-candidate-001\",\n      \"name\": \"John Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"phone\": \"+1234567890\"\n    }\n  ],\n  \"interview_questions\": [\n    {\n      \"id\": \"a1b2c3d4e5f60123456789abcdef0123\",\n      \"question\": \"Tell me about a production application you led. What architecture choices did you make?\",\n      \"type\": \"verbal\"\n    }\n  ],\n  \"interview_settings\": {\n    \"cutoff_score\": 50,\n    \"interview_duration\": \"30 Minutes\"\n  }\n}")

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

	req.Header.Add("x-tidyhire-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.tidyhire.app/api/public/v1/interview/invite")
  .header("x-tidyhire-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ats_job_id\": \"ats-job-12345\",\n  \"job_title\": \"Senior Software Engineer\",\n  \"job_description\": \"We are looking for a Senior Software Engineer to join our team and build scalable backend services.\",\n  \"min_experience\": 3,\n  \"max_experience\": 5,\n  \"seniority_level\": \"Senior\",\n  \"work_type\": \"Remote\",\n  \"employment_type\": \"Full Time\",\n  \"location\": \"New York, NY\",\n  \"skills_required\": [\n    \"JavaScript\",\n    \"Node.js\",\n    \"MongoDB\"\n  ],\n  \"skills_good_to_have\": [\n    \"TypeScript\",\n    \"Redis\",\n    \"Docker\"\n  ],\n  \"candidates\": [\n    {\n      \"id\": \"ats-candidate-001\",\n      \"name\": \"John Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"phone\": \"+1234567890\"\n    }\n  ],\n  \"interview_questions\": [\n    {\n      \"id\": \"a1b2c3d4e5f60123456789abcdef0123\",\n      \"question\": \"Tell me about a production application you led. What architecture choices did you make?\",\n      \"type\": \"verbal\"\n    }\n  ],\n  \"interview_settings\": {\n    \"cutoff_score\": 50,\n    \"interview_duration\": \"30 Minutes\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tidyhire.app/api/public/v1/interview/invite")

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

request = Net::HTTP::Post.new(url)
request["x-tidyhire-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ats_job_id\": \"ats-job-12345\",\n  \"job_title\": \"Senior Software Engineer\",\n  \"job_description\": \"We are looking for a Senior Software Engineer to join our team and build scalable backend services.\",\n  \"min_experience\": 3,\n  \"max_experience\": 5,\n  \"seniority_level\": \"Senior\",\n  \"work_type\": \"Remote\",\n  \"employment_type\": \"Full Time\",\n  \"location\": \"New York, NY\",\n  \"skills_required\": [\n    \"JavaScript\",\n    \"Node.js\",\n    \"MongoDB\"\n  ],\n  \"skills_good_to_have\": [\n    \"TypeScript\",\n    \"Redis\",\n    \"Docker\"\n  ],\n  \"candidates\": [\n    {\n      \"id\": \"ats-candidate-001\",\n      \"name\": \"John Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"phone\": \"+1234567890\"\n    }\n  ],\n  \"interview_questions\": [\n    {\n      \"id\": \"a1b2c3d4e5f60123456789abcdef0123\",\n      \"question\": \"Tell me about a production application you led. What architecture choices did you make?\",\n      \"type\": \"verbal\"\n    }\n  ],\n  \"interview_settings\": {\n    \"cutoff_score\": 50,\n    \"interview_duration\": \"30 Minutes\"\n  }\n}"

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

{
  "success": true,
  "data": {
    "project_id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "job_url": "https://jobs.tidyhire.app/company/acme/job/64a1b2c3d4e5f6a7b8c9d0e2",
    "project_url": "https://platform.tidyhire.app/app/projects/64a1b2c3d4e5f6a7b8c9d0e1",
    "interviews": [
      {
        "id": "64a1b2c3d4e5f6a7b8c9d0e3",
        "candidate_id": "ats-candidate-001",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "status": "success",
        "message": "Interview invitation is being processed"
      }
    ]
  }
}

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "errors": [
    {
      "field": "candidates.0.name",
      "message": "Candidate name must be at least 3 characters"
    }
  ]
}

{
  "success": false,
  "code": "UNKNOWN_ERROR",
  "message": "Something went wrong."
}

POST

api

public

interview

invite

Interview Invite

curl --request POST \
  --url https://api.tidyhire.app/api/public/v1/interview/invite \
  --header 'Content-Type: application/json' \
  --header 'x-tidyhire-api-key: <api-key>' \
  --data '
{
  "ats_job_id": "ats-job-12345",
  "job_title": "Senior Software Engineer",
  "job_description": "We are looking for a Senior Software Engineer to join our team and build scalable backend services.",
  "min_experience": 3,
  "max_experience": 5,
  "seniority_level": "Senior",
  "work_type": "Remote",
  "employment_type": "Full Time",
  "location": "New York, NY",
  "skills_required": [
    "JavaScript",
    "Node.js",
    "MongoDB"
  ],
  "skills_good_to_have": [
    "TypeScript",
    "Redis",
    "Docker"
  ],
  "candidates": [
    {
      "id": "ats-candidate-001",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890"
    }
  ],
  "interview_questions": [
    {
      "id": "a1b2c3d4e5f60123456789abcdef0123",
      "question": "Tell me about a production application you led. What architecture choices did you make?",
      "type": "verbal"
    }
  ],
  "interview_settings": {
    "cutoff_score": 50,
    "interview_duration": "30 Minutes"
  }
}
'

import requests

url = "https://api.tidyhire.app/api/public/v1/interview/invite"

payload = {
    "ats_job_id": "ats-job-12345",
    "job_title": "Senior Software Engineer",
    "job_description": "We are looking for a Senior Software Engineer to join our team and build scalable backend services.",
    "min_experience": 3,
    "max_experience": 5,
    "seniority_level": "Senior",
    "work_type": "Remote",
    "employment_type": "Full Time",
    "location": "New York, NY",
    "skills_required": ["JavaScript", "Node.js", "MongoDB"],
    "skills_good_to_have": ["TypeScript", "Redis", "Docker"],
    "candidates": [
        {
            "id": "ats-candidate-001",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "phone": "+1234567890"
        }
    ],
    "interview_questions": [
        {
            "id": "a1b2c3d4e5f60123456789abcdef0123",
            "question": "Tell me about a production application you led. What architecture choices did you make?",
            "type": "verbal"
        }
    ],
    "interview_settings": {
        "cutoff_score": 50,
        "interview_duration": "30 Minutes"
    }
}
headers = {
    "x-tidyhire-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-tidyhire-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ats_job_id: 'ats-job-12345',
    job_title: 'Senior Software Engineer',
    job_description: 'We are looking for a Senior Software Engineer to join our team and build scalable backend services.',
    min_experience: 3,
    max_experience: 5,
    seniority_level: 'Senior',
    work_type: 'Remote',
    employment_type: 'Full Time',
    location: 'New York, NY',
    skills_required: ['JavaScript', 'Node.js', 'MongoDB'],
    skills_good_to_have: ['TypeScript', 'Redis', 'Docker'],
    candidates: [
      {
        id: 'ats-candidate-001',
        name: 'John Doe',
        email: 'john.doe@example.com',
        phone: '+1234567890'
      }
    ],
    interview_questions: [
      {
        id: 'a1b2c3d4e5f60123456789abcdef0123',
        question: 'Tell me about a production application you led. What architecture choices did you make?',
        type: 'verbal'
      }
    ],
    interview_settings: {cutoff_score: 50, interview_duration: '30 Minutes'}
  })
};

fetch('https://api.tidyhire.app/api/public/v1/interview/invite', 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.tidyhire.app/api/public/v1/interview/invite",
  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([
    'ats_job_id' => 'ats-job-12345',
    'job_title' => 'Senior Software Engineer',
    'job_description' => 'We are looking for a Senior Software Engineer to join our team and build scalable backend services.',
    'min_experience' => 3,
    'max_experience' => 5,
    'seniority_level' => 'Senior',
    'work_type' => 'Remote',
    'employment_type' => 'Full Time',
    'location' => 'New York, NY',
    'skills_required' => [
        'JavaScript',
        'Node.js',
        'MongoDB'
    ],
    'skills_good_to_have' => [
        'TypeScript',
        'Redis',
        'Docker'
    ],
    'candidates' => [
        [
                'id' => 'ats-candidate-001',
                'name' => 'John Doe',
                'email' => 'john.doe@example.com',
                'phone' => '+1234567890'
        ]
    ],
    'interview_questions' => [
        [
                'id' => 'a1b2c3d4e5f60123456789abcdef0123',
                'question' => 'Tell me about a production application you led. What architecture choices did you make?',
                'type' => 'verbal'
        ]
    ],
    'interview_settings' => [
        'cutoff_score' => 50,
        'interview_duration' => '30 Minutes'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-tidyhire-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.tidyhire.app/api/public/v1/interview/invite"

	payload := strings.NewReader("{\n  \"ats_job_id\": \"ats-job-12345\",\n  \"job_title\": \"Senior Software Engineer\",\n  \"job_description\": \"We are looking for a Senior Software Engineer to join our team and build scalable backend services.\",\n  \"min_experience\": 3,\n  \"max_experience\": 5,\n  \"seniority_level\": \"Senior\",\n  \"work_type\": \"Remote\",\n  \"employment_type\": \"Full Time\",\n  \"location\": \"New York, NY\",\n  \"skills_required\": [\n    \"JavaScript\",\n    \"Node.js\",\n    \"MongoDB\"\n  ],\n  \"skills_good_to_have\": [\n    \"TypeScript\",\n    \"Redis\",\n    \"Docker\"\n  ],\n  \"candidates\": [\n    {\n      \"id\": \"ats-candidate-001\",\n      \"name\": \"John Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"phone\": \"+1234567890\"\n    }\n  ],\n  \"interview_questions\": [\n    {\n      \"id\": \"a1b2c3d4e5f60123456789abcdef0123\",\n      \"question\": \"Tell me about a production application you led. What architecture choices did you make?\",\n      \"type\": \"verbal\"\n    }\n  ],\n  \"interview_settings\": {\n    \"cutoff_score\": 50,\n    \"interview_duration\": \"30 Minutes\"\n  }\n}")

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

	req.Header.Add("x-tidyhire-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.tidyhire.app/api/public/v1/interview/invite")
  .header("x-tidyhire-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ats_job_id\": \"ats-job-12345\",\n  \"job_title\": \"Senior Software Engineer\",\n  \"job_description\": \"We are looking for a Senior Software Engineer to join our team and build scalable backend services.\",\n  \"min_experience\": 3,\n  \"max_experience\": 5,\n  \"seniority_level\": \"Senior\",\n  \"work_type\": \"Remote\",\n  \"employment_type\": \"Full Time\",\n  \"location\": \"New York, NY\",\n  \"skills_required\": [\n    \"JavaScript\",\n    \"Node.js\",\n    \"MongoDB\"\n  ],\n  \"skills_good_to_have\": [\n    \"TypeScript\",\n    \"Redis\",\n    \"Docker\"\n  ],\n  \"candidates\": [\n    {\n      \"id\": \"ats-candidate-001\",\n      \"name\": \"John Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"phone\": \"+1234567890\"\n    }\n  ],\n  \"interview_questions\": [\n    {\n      \"id\": \"a1b2c3d4e5f60123456789abcdef0123\",\n      \"question\": \"Tell me about a production application you led. What architecture choices did you make?\",\n      \"type\": \"verbal\"\n    }\n  ],\n  \"interview_settings\": {\n    \"cutoff_score\": 50,\n    \"interview_duration\": \"30 Minutes\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tidyhire.app/api/public/v1/interview/invite")

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

request = Net::HTTP::Post.new(url)
request["x-tidyhire-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ats_job_id\": \"ats-job-12345\",\n  \"job_title\": \"Senior Software Engineer\",\n  \"job_description\": \"We are looking for a Senior Software Engineer to join our team and build scalable backend services.\",\n  \"min_experience\": 3,\n  \"max_experience\": 5,\n  \"seniority_level\": \"Senior\",\n  \"work_type\": \"Remote\",\n  \"employment_type\": \"Full Time\",\n  \"location\": \"New York, NY\",\n  \"skills_required\": [\n    \"JavaScript\",\n    \"Node.js\",\n    \"MongoDB\"\n  ],\n  \"skills_good_to_have\": [\n    \"TypeScript\",\n    \"Redis\",\n    \"Docker\"\n  ],\n  \"candidates\": [\n    {\n      \"id\": \"ats-candidate-001\",\n      \"name\": \"John Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"phone\": \"+1234567890\"\n    }\n  ],\n  \"interview_questions\": [\n    {\n      \"id\": \"a1b2c3d4e5f60123456789abcdef0123\",\n      \"question\": \"Tell me about a production application you led. What architecture choices did you make?\",\n      \"type\": \"verbal\"\n    }\n  ],\n  \"interview_settings\": {\n    \"cutoff_score\": 50,\n    \"interview_duration\": \"30 Minutes\"\n  }\n}"

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

{
  "success": true,
  "data": {
    "project_id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "job_url": "https://jobs.tidyhire.app/company/acme/job/64a1b2c3d4e5f6a7b8c9d0e2",
    "project_url": "https://platform.tidyhire.app/app/projects/64a1b2c3d4e5f6a7b8c9d0e1",
    "interviews": [
      {
        "id": "64a1b2c3d4e5f6a7b8c9d0e3",
        "candidate_id": "ats-candidate-001",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "status": "success",
        "message": "Interview invitation is being processed"
      }
    ]
  }
}

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "errors": [
    {
      "field": "candidates.0.name",
      "message": "Candidate name must be at least 3 characters"
    }
  ]
}

{
  "success": false,
  "code": "UNKNOWN_ERROR",
  "message": "Something went wrong."
}

Use the same ats_job_id across multiple requests to invite candidates to an existing job.

Candidate Custom Fields

Each candidate object accepts an optional custom_fields object containing key-value pairs. These fields are stored on the candidate record.

Example Request

{
  "ats_job_id": "ats-job-12345",
  "job_title": "Senior Software Engineer",
  "job_description": "We are looking for a Senior Software Engineer to join our team and build scalable backend services.",
  "min_experience": 3,
  "max_experience": 5,
  "seniority_level": "Senior",
  "work_type": "Remote",
  "employment_type": "Full Time",
  "location": "New York, NY",
  "skills_required": ["JavaScript", "Node.js", "MongoDB"],
  "skills_good_to_have": ["TypeScript", "Redis", "Docker"],
  "interview_settings": {
    "cutoff_score": 50,
    "interview_duration": "30 Minutes"
  },
  "candidates": [
    {
      "id": "ats-candidate-001",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "custom_fields": {
        "years_of_experience": "5",
        "current_company": "Acme Corp"
      }
    }
  ]
}

Example Response

{
  "success": true,
  "data": {
    "project_id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "job_url": "https://jobs.tidyhire.app/company/acme/job/64a1b2c3d4e5f6a7b8c9d0e2",
    "project_url": "https://platform.tidyhire.app/app/projects/64a1b2c3d4e5f6a7b8c9d0e1",
    "interviews": [
      {
        "id": "64a1b2c3d4e5f6a7b8c9d0e3",
        "candidate_id": "ats-candidate-001",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "status": "success",
        "message": "Interview invitation is being processed"
      }
    ]
  }
}

Authorizations

x-tidyhire-api-key

string

header

required

Your Tidyhire API key

Body

application/json

ats_job_id

string

required

A unique job identifier from your ATS to link this job. If a project with this ats_job_id already exists, candidates are added to it. Otherwise a new project and job are created.

Required string length: 1 - 200

Example:

"ats-job-12345"

job_title

string

required

The title of the job position. Hyperlinks are not allowed in this field.

Minimum string length: 1

Example:

"Senior Software Engineer"

job_description

string

required

A detailed description of the job role and responsibilities. Hyperlinks are not allowed in this field.

Minimum string length: 1

Example:

"We are looking for a Senior Software Engineer to join our team and build scalable backend services."

min_experience

number

required

Minimum years of experience required.

Example:

3

max_experience

number

required

Maximum years of experience required.

Example:

5

seniority_level

enum<string>

required

Seniority level for the role.

Available options:

Entry,

Mid,

Senior,

Lead,

Principal,

Staff

Example:

"Senior"

work_type

enum<string>

required

Work arrangement type.

Available options:

Remote,

On Site,

Hybrid

Example:

"Remote"

employment_type

enum<string>

required

Type of employment.

Available options:

Full Time,

Part Time,

Contract,

Freelance

Example:

"Full Time"

location

string

required

Job location.

Minimum string length: 1

Example:

"New York, NY"

skills_required

string[]

required

List of required skills. Minimum 3 skills.

Minimum array length: 3

Example:

["JavaScript", "Node.js", "MongoDB"]

skills_good_to_have

string[]

required

List of preferred skills. Minimum 3 skills.

Minimum array length: 3

Example:

["TypeScript", "Redis", "Docker"]

candidates

object[]

required

List of candidates to invite. Minimum 1 candidate.

Minimum array length: 1

Show child attributes

interview_questions

object[]

Pre-generated interview questions. If provided, AI question generation is skipped.

Option 1
Option 2

Show child attributes

interview_settings

object

Show child attributes

Response

Success.

success

boolean

Example:

true

data

object

Show child attributes

Last modified on July 23, 2026

API

API Key

Interview

Call

AI

Interview Invite

Candidate Custom Fields

Example Request

Example Response

Authorizations

Body

Response

​Candidate Custom Fields

​Example Request

​Example Response

Authorizations

Body

Response

Candidate Custom Fields

Example Request

Example Response