Initiate AI Call
curl --request POST \
--url https://api.tidyhire.app/api/public/v1/call/initiate \
--header 'Content-Type: application/json' \
--header 'x-tidyhire-api-key: <api-key>' \
--data '
{
"ats_job_id": "ats-job-12345",
"candidates": [
{
"id": "ats-candidate-001",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+917873476062"
}
],
"instructions": "You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.",
"first_message": "Hello {{candidate_first_name}}, this is {{sender_company}} calling.",
"assistant_settings": {
"tools": [
"<string>"
],
"min_endpointing_delay": 123,
"max_endpointing_delay": 123
},
"extract_variables": [
{
"label": "Years of Experience",
"type": "integer",
"description": "How many years of professional experience does the candidate have?",
"format_example": "5",
"choices": [
"1-3",
"4-6",
"7-10",
"10+"
]
}
],
"call_settings": {
"retry_policy": {
"conditions": [
"missed",
"declined"
],
"intervals": [
{
"type": "delay",
"duration": 15,
"unit": "minutes"
}
]
},
"working_hours": {
"enabled": true,
"monday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"tuesday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"wednesday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"thursday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"friday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"saturday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"sunday": [
{
"start_minute": 540,
"end_minute": 1020
}
]
},
"whatsapp_notifications": {}
},
"schedule_at": "2026-05-27T10:00:00Z"
}
'import requests
url = "https://api.tidyhire.app/api/public/v1/call/initiate"
payload = {
"ats_job_id": "ats-job-12345",
"candidates": [
{
"id": "ats-candidate-001",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+917873476062"
}
],
"instructions": "You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.",
"first_message": "Hello {{candidate_first_name}}, this is {{sender_company}} calling.",
"assistant_settings": {
"tools": ["<string>"],
"min_endpointing_delay": 123,
"max_endpointing_delay": 123
},
"extract_variables": [
{
"label": "Years of Experience",
"type": "integer",
"description": "How many years of professional experience does the candidate have?",
"format_example": "5",
"choices": ["1-3", "4-6", "7-10", "10+"]
}
],
"call_settings": {
"retry_policy": {
"conditions": ["missed", "declined"],
"intervals": [
{
"type": "delay",
"duration": 15,
"unit": "minutes"
}
]
},
"working_hours": {
"enabled": True,
"monday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"tuesday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"wednesday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"thursday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"friday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"saturday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"sunday": [
{
"start_minute": 540,
"end_minute": 1020
}
]
},
"whatsapp_notifications": {}
},
"schedule_at": "2026-05-27T10:00:00Z"
}
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',
candidates: [
{
id: 'ats-candidate-001',
name: 'John Doe',
email: 'john.doe@example.com',
phone: '+917873476062'
}
],
instructions: 'You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.',
first_message: 'Hello {{candidate_first_name}}, this is {{sender_company}} calling.',
assistant_settings: {tools: ['<string>'], min_endpointing_delay: 123, max_endpointing_delay: 123},
extract_variables: [
{
label: 'Years of Experience',
type: 'integer',
description: 'How many years of professional experience does the candidate have?',
format_example: '5',
choices: ['1-3', '4-6', '7-10', '10+']
}
],
call_settings: {
retry_policy: {
conditions: ['missed', 'declined'],
intervals: [{type: 'delay', duration: 15, unit: 'minutes'}]
},
working_hours: {
enabled: true,
monday: [{start_minute: 540, end_minute: 1020}],
tuesday: [{start_minute: 540, end_minute: 1020}],
wednesday: [{start_minute: 540, end_minute: 1020}],
thursday: [{start_minute: 540, end_minute: 1020}],
friday: [{start_minute: 540, end_minute: 1020}],
saturday: [{start_minute: 540, end_minute: 1020}],
sunday: [{start_minute: 540, end_minute: 1020}]
},
whatsapp_notifications: {}
},
schedule_at: '2026-05-27T10:00:00Z'
})
};
fetch('https://api.tidyhire.app/api/public/v1/call/initiate', 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/call/initiate",
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',
'candidates' => [
[
'id' => 'ats-candidate-001',
'name' => 'John Doe',
'email' => 'john.doe@example.com',
'phone' => '+917873476062'
]
],
'instructions' => 'You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.',
'first_message' => 'Hello {{candidate_first_name}}, this is {{sender_company}} calling.',
'assistant_settings' => [
'tools' => [
'<string>'
],
'min_endpointing_delay' => 123,
'max_endpointing_delay' => 123
],
'extract_variables' => [
[
'label' => 'Years of Experience',
'type' => 'integer',
'description' => 'How many years of professional experience does the candidate have?',
'format_example' => '5',
'choices' => [
'1-3',
'4-6',
'7-10',
'10+'
]
]
],
'call_settings' => [
'retry_policy' => [
'conditions' => [
'missed',
'declined'
],
'intervals' => [
[
'type' => 'delay',
'duration' => 15,
'unit' => 'minutes'
]
]
],
'working_hours' => [
'enabled' => true,
'monday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'tuesday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'wednesday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'thursday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'friday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'saturday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'sunday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
]
],
'whatsapp_notifications' => [
]
],
'schedule_at' => '2026-05-27T10:00:00Z'
]),
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/call/initiate"
payload := strings.NewReader("{\n \"ats_job_id\": \"ats-job-12345\",\n \"candidates\": [\n {\n \"id\": \"ats-candidate-001\",\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+917873476062\"\n }\n ],\n \"instructions\": \"You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.\",\n \"first_message\": \"Hello {{candidate_first_name}}, this is {{sender_company}} calling.\",\n \"assistant_settings\": {\n \"tools\": [\n \"<string>\"\n ],\n \"min_endpointing_delay\": 123,\n \"max_endpointing_delay\": 123\n },\n \"extract_variables\": [\n {\n \"label\": \"Years of Experience\",\n \"type\": \"integer\",\n \"description\": \"How many years of professional experience does the candidate have?\",\n \"format_example\": \"5\",\n \"choices\": [\n \"1-3\",\n \"4-6\",\n \"7-10\",\n \"10+\"\n ]\n }\n ],\n \"call_settings\": {\n \"retry_policy\": {\n \"conditions\": [\n \"missed\",\n \"declined\"\n ],\n \"intervals\": [\n {\n \"type\": \"delay\",\n \"duration\": 15,\n \"unit\": \"minutes\"\n }\n ]\n },\n \"working_hours\": {\n \"enabled\": true,\n \"monday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"tuesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"wednesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"thursday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"friday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"saturday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"sunday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ]\n },\n \"whatsapp_notifications\": {}\n },\n \"schedule_at\": \"2026-05-27T10:00:00Z\"\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/call/initiate")
.header("x-tidyhire-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"ats_job_id\": \"ats-job-12345\",\n \"candidates\": [\n {\n \"id\": \"ats-candidate-001\",\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+917873476062\"\n }\n ],\n \"instructions\": \"You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.\",\n \"first_message\": \"Hello {{candidate_first_name}}, this is {{sender_company}} calling.\",\n \"assistant_settings\": {\n \"tools\": [\n \"<string>\"\n ],\n \"min_endpointing_delay\": 123,\n \"max_endpointing_delay\": 123\n },\n \"extract_variables\": [\n {\n \"label\": \"Years of Experience\",\n \"type\": \"integer\",\n \"description\": \"How many years of professional experience does the candidate have?\",\n \"format_example\": \"5\",\n \"choices\": [\n \"1-3\",\n \"4-6\",\n \"7-10\",\n \"10+\"\n ]\n }\n ],\n \"call_settings\": {\n \"retry_policy\": {\n \"conditions\": [\n \"missed\",\n \"declined\"\n ],\n \"intervals\": [\n {\n \"type\": \"delay\",\n \"duration\": 15,\n \"unit\": \"minutes\"\n }\n ]\n },\n \"working_hours\": {\n \"enabled\": true,\n \"monday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"tuesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"wednesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"thursday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"friday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"saturday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"sunday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ]\n },\n \"whatsapp_notifications\": {}\n },\n \"schedule_at\": \"2026-05-27T10:00:00Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tidyhire.app/api/public/v1/call/initiate")
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 \"candidates\": [\n {\n \"id\": \"ats-candidate-001\",\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+917873476062\"\n }\n ],\n \"instructions\": \"You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.\",\n \"first_message\": \"Hello {{candidate_first_name}}, this is {{sender_company}} calling.\",\n \"assistant_settings\": {\n \"tools\": [\n \"<string>\"\n ],\n \"min_endpointing_delay\": 123,\n \"max_endpointing_delay\": 123\n },\n \"extract_variables\": [\n {\n \"label\": \"Years of Experience\",\n \"type\": \"integer\",\n \"description\": \"How many years of professional experience does the candidate have?\",\n \"format_example\": \"5\",\n \"choices\": [\n \"1-3\",\n \"4-6\",\n \"7-10\",\n \"10+\"\n ]\n }\n ],\n \"call_settings\": {\n \"retry_policy\": {\n \"conditions\": [\n \"missed\",\n \"declined\"\n ],\n \"intervals\": [\n {\n \"type\": \"delay\",\n \"duration\": 15,\n \"unit\": \"minutes\"\n }\n ]\n },\n \"working_hours\": {\n \"enabled\": true,\n \"monday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"tuesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"wednesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"thursday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"friday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"saturday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"sunday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ]\n },\n \"whatsapp_notifications\": {}\n },\n \"schedule_at\": \"2026-05-27T10:00:00Z\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"project_id": "64a1b2c3d4e5f6a7b8c9d0e1",
"project_url": "https://platform.tidyhire.app/app/projects/64a1b2c3d4e5f6a7b8c9d0e1",
"calls": [
{
"id": "64a1b2c3d4e5f6a7b8c9d0e4",
"candidate_id": "ats-candidate-001",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+917873476062",
"status": "success",
"message": "Call initiated"
}
]
}
}{
"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,
"message": "Unauthorized",
"error": "INVALID_API_KEY"
}{
"success": false,
"code": "UNKNOWN_ERROR",
"message": "Something went wrong."
}Call
Initiate AI Call
Triggers direct AI calls to candidates for a RIA campaign project. Each candidate receives an outbound AI call with the configured script. Candidates are created on-the-fly if they do not already exist.
POST
/
api
/
public
/
v1
/
call
/
initiate
Initiate AI Call
curl --request POST \
--url https://api.tidyhire.app/api/public/v1/call/initiate \
--header 'Content-Type: application/json' \
--header 'x-tidyhire-api-key: <api-key>' \
--data '
{
"ats_job_id": "ats-job-12345",
"candidates": [
{
"id": "ats-candidate-001",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+917873476062"
}
],
"instructions": "You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.",
"first_message": "Hello {{candidate_first_name}}, this is {{sender_company}} calling.",
"assistant_settings": {
"tools": [
"<string>"
],
"min_endpointing_delay": 123,
"max_endpointing_delay": 123
},
"extract_variables": [
{
"label": "Years of Experience",
"type": "integer",
"description": "How many years of professional experience does the candidate have?",
"format_example": "5",
"choices": [
"1-3",
"4-6",
"7-10",
"10+"
]
}
],
"call_settings": {
"retry_policy": {
"conditions": [
"missed",
"declined"
],
"intervals": [
{
"type": "delay",
"duration": 15,
"unit": "minutes"
}
]
},
"working_hours": {
"enabled": true,
"monday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"tuesday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"wednesday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"thursday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"friday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"saturday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"sunday": [
{
"start_minute": 540,
"end_minute": 1020
}
]
},
"whatsapp_notifications": {}
},
"schedule_at": "2026-05-27T10:00:00Z"
}
'import requests
url = "https://api.tidyhire.app/api/public/v1/call/initiate"
payload = {
"ats_job_id": "ats-job-12345",
"candidates": [
{
"id": "ats-candidate-001",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+917873476062"
}
],
"instructions": "You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.",
"first_message": "Hello {{candidate_first_name}}, this is {{sender_company}} calling.",
"assistant_settings": {
"tools": ["<string>"],
"min_endpointing_delay": 123,
"max_endpointing_delay": 123
},
"extract_variables": [
{
"label": "Years of Experience",
"type": "integer",
"description": "How many years of professional experience does the candidate have?",
"format_example": "5",
"choices": ["1-3", "4-6", "7-10", "10+"]
}
],
"call_settings": {
"retry_policy": {
"conditions": ["missed", "declined"],
"intervals": [
{
"type": "delay",
"duration": 15,
"unit": "minutes"
}
]
},
"working_hours": {
"enabled": True,
"monday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"tuesday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"wednesday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"thursday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"friday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"saturday": [
{
"start_minute": 540,
"end_minute": 1020
}
],
"sunday": [
{
"start_minute": 540,
"end_minute": 1020
}
]
},
"whatsapp_notifications": {}
},
"schedule_at": "2026-05-27T10:00:00Z"
}
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',
candidates: [
{
id: 'ats-candidate-001',
name: 'John Doe',
email: 'john.doe@example.com',
phone: '+917873476062'
}
],
instructions: 'You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.',
first_message: 'Hello {{candidate_first_name}}, this is {{sender_company}} calling.',
assistant_settings: {tools: ['<string>'], min_endpointing_delay: 123, max_endpointing_delay: 123},
extract_variables: [
{
label: 'Years of Experience',
type: 'integer',
description: 'How many years of professional experience does the candidate have?',
format_example: '5',
choices: ['1-3', '4-6', '7-10', '10+']
}
],
call_settings: {
retry_policy: {
conditions: ['missed', 'declined'],
intervals: [{type: 'delay', duration: 15, unit: 'minutes'}]
},
working_hours: {
enabled: true,
monday: [{start_minute: 540, end_minute: 1020}],
tuesday: [{start_minute: 540, end_minute: 1020}],
wednesday: [{start_minute: 540, end_minute: 1020}],
thursday: [{start_minute: 540, end_minute: 1020}],
friday: [{start_minute: 540, end_minute: 1020}],
saturday: [{start_minute: 540, end_minute: 1020}],
sunday: [{start_minute: 540, end_minute: 1020}]
},
whatsapp_notifications: {}
},
schedule_at: '2026-05-27T10:00:00Z'
})
};
fetch('https://api.tidyhire.app/api/public/v1/call/initiate', 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/call/initiate",
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',
'candidates' => [
[
'id' => 'ats-candidate-001',
'name' => 'John Doe',
'email' => 'john.doe@example.com',
'phone' => '+917873476062'
]
],
'instructions' => 'You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.',
'first_message' => 'Hello {{candidate_first_name}}, this is {{sender_company}} calling.',
'assistant_settings' => [
'tools' => [
'<string>'
],
'min_endpointing_delay' => 123,
'max_endpointing_delay' => 123
],
'extract_variables' => [
[
'label' => 'Years of Experience',
'type' => 'integer',
'description' => 'How many years of professional experience does the candidate have?',
'format_example' => '5',
'choices' => [
'1-3',
'4-6',
'7-10',
'10+'
]
]
],
'call_settings' => [
'retry_policy' => [
'conditions' => [
'missed',
'declined'
],
'intervals' => [
[
'type' => 'delay',
'duration' => 15,
'unit' => 'minutes'
]
]
],
'working_hours' => [
'enabled' => true,
'monday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'tuesday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'wednesday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'thursday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'friday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'saturday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
],
'sunday' => [
[
'start_minute' => 540,
'end_minute' => 1020
]
]
],
'whatsapp_notifications' => [
]
],
'schedule_at' => '2026-05-27T10:00:00Z'
]),
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/call/initiate"
payload := strings.NewReader("{\n \"ats_job_id\": \"ats-job-12345\",\n \"candidates\": [\n {\n \"id\": \"ats-candidate-001\",\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+917873476062\"\n }\n ],\n \"instructions\": \"You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.\",\n \"first_message\": \"Hello {{candidate_first_name}}, this is {{sender_company}} calling.\",\n \"assistant_settings\": {\n \"tools\": [\n \"<string>\"\n ],\n \"min_endpointing_delay\": 123,\n \"max_endpointing_delay\": 123\n },\n \"extract_variables\": [\n {\n \"label\": \"Years of Experience\",\n \"type\": \"integer\",\n \"description\": \"How many years of professional experience does the candidate have?\",\n \"format_example\": \"5\",\n \"choices\": [\n \"1-3\",\n \"4-6\",\n \"7-10\",\n \"10+\"\n ]\n }\n ],\n \"call_settings\": {\n \"retry_policy\": {\n \"conditions\": [\n \"missed\",\n \"declined\"\n ],\n \"intervals\": [\n {\n \"type\": \"delay\",\n \"duration\": 15,\n \"unit\": \"minutes\"\n }\n ]\n },\n \"working_hours\": {\n \"enabled\": true,\n \"monday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"tuesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"wednesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"thursday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"friday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"saturday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"sunday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ]\n },\n \"whatsapp_notifications\": {}\n },\n \"schedule_at\": \"2026-05-27T10:00:00Z\"\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/call/initiate")
.header("x-tidyhire-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"ats_job_id\": \"ats-job-12345\",\n \"candidates\": [\n {\n \"id\": \"ats-candidate-001\",\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+917873476062\"\n }\n ],\n \"instructions\": \"You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.\",\n \"first_message\": \"Hello {{candidate_first_name}}, this is {{sender_company}} calling.\",\n \"assistant_settings\": {\n \"tools\": [\n \"<string>\"\n ],\n \"min_endpointing_delay\": 123,\n \"max_endpointing_delay\": 123\n },\n \"extract_variables\": [\n {\n \"label\": \"Years of Experience\",\n \"type\": \"integer\",\n \"description\": \"How many years of professional experience does the candidate have?\",\n \"format_example\": \"5\",\n \"choices\": [\n \"1-3\",\n \"4-6\",\n \"7-10\",\n \"10+\"\n ]\n }\n ],\n \"call_settings\": {\n \"retry_policy\": {\n \"conditions\": [\n \"missed\",\n \"declined\"\n ],\n \"intervals\": [\n {\n \"type\": \"delay\",\n \"duration\": 15,\n \"unit\": \"minutes\"\n }\n ]\n },\n \"working_hours\": {\n \"enabled\": true,\n \"monday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"tuesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"wednesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"thursday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"friday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"saturday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"sunday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ]\n },\n \"whatsapp_notifications\": {}\n },\n \"schedule_at\": \"2026-05-27T10:00:00Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tidyhire.app/api/public/v1/call/initiate")
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 \"candidates\": [\n {\n \"id\": \"ats-candidate-001\",\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+917873476062\"\n }\n ],\n \"instructions\": \"You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems.\",\n \"first_message\": \"Hello {{candidate_first_name}}, this is {{sender_company}} calling.\",\n \"assistant_settings\": {\n \"tools\": [\n \"<string>\"\n ],\n \"min_endpointing_delay\": 123,\n \"max_endpointing_delay\": 123\n },\n \"extract_variables\": [\n {\n \"label\": \"Years of Experience\",\n \"type\": \"integer\",\n \"description\": \"How many years of professional experience does the candidate have?\",\n \"format_example\": \"5\",\n \"choices\": [\n \"1-3\",\n \"4-6\",\n \"7-10\",\n \"10+\"\n ]\n }\n ],\n \"call_settings\": {\n \"retry_policy\": {\n \"conditions\": [\n \"missed\",\n \"declined\"\n ],\n \"intervals\": [\n {\n \"type\": \"delay\",\n \"duration\": 15,\n \"unit\": \"minutes\"\n }\n ]\n },\n \"working_hours\": {\n \"enabled\": true,\n \"monday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"tuesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"wednesday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"thursday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"friday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"saturday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ],\n \"sunday\": [\n {\n \"start_minute\": 540,\n \"end_minute\": 1020\n }\n ]\n },\n \"whatsapp_notifications\": {}\n },\n \"schedule_at\": \"2026-05-27T10:00:00Z\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"project_id": "64a1b2c3d4e5f6a7b8c9d0e1",
"project_url": "https://platform.tidyhire.app/app/projects/64a1b2c3d4e5f6a7b8c9d0e1",
"calls": [
{
"id": "64a1b2c3d4e5f6a7b8c9d0e4",
"candidate_id": "ats-candidate-001",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+917873476062",
"status": "success",
"message": "Call initiated"
}
]
}
}{
"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,
"message": "Unauthorized",
"error": "INVALID_API_KEY"
}{
"success": false,
"code": "UNKNOWN_ERROR",
"message": "Something went wrong."
}Use the same
ats_job_id across multiple requests to call additional candidates on an existing campaign project.Dynamic Variables
Bothfirst_message and instructions support variable substitution using the {{variable_name}} syntax.
first_message is optional and defaults to "Hello" if not provided.
Built-in Variables
These are automatically resolved from the candidate, project, and sender context:| Variable | Description |
|---|---|
{{candidate_first_name}} | Candidate’s first name |
{{candidate_last_name}} | Candidate’s last name |
{{candidate_full_name}} | Candidate’s full name |
{{candidate_email}} | Candidate’s email |
{{candidate_phone}} | Candidate’s phone number |
{{sender_first_name}} | Sender’s first name |
{{sender_last_name}} | Sender’s last name |
{{sender_full_name}} | Sender’s full name |
{{sender_company}} | Company name (from job or sender profile) |
WhatsApp Template Variables
When usingwhatsapp_notifications, the template_variables object accepts two value types:
- Built-in resolver reference —
{"body_1": "{{candidate_first_name}}"}resolves automatically using candidate/job/sender data. - Literal text —
{"body_2": "Thursday, 21 May 2026, 6:00 PM..."}is passed through as-is.
Candidate Custom Fields
Each candidate object accepts an optionalcustom_fields object containing key-value pairs. These fields are stored on the candidate record.
Working Hours
Whenschedule_at is not provided, calls are scheduled immediately. Use call_settings.working_hours to restrict when calls can be placed.
enabled:true(default) orfalseto bypass working-hours checks.- Each day is a list of shifts with
start_minuteandend_minutein minutes from midnight UTC. - If the current time is outside all configured shifts, the call is delayed until the start of the next available shift.
schedule_atis always respected as-is and skips working-hours adjustment.
Example Request
{
"ats_job_id": "ats-job-12345",
"candidates": [
{
"id": "ats-candidate-001",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+917873476062",
"custom_fields": {
"years_of_experience": "5",
"current_company": "Acme Corp"
}
}
],
"instructions": "You are a recruiter for {{sender_company}}. Greet the candidate and screen them about their experience with distributed systems.",
"extract_variables": [
{
"label": "Years of Experience",
"type": "integer",
"description": "How many years of professional experience does the candidate have?"
}
],
"call_settings": {
"retry_policy": {
"conditions": ["missed", "declined"],
"intervals": [
{
"type": "delay",
"duration": 15,
"unit": "minutes"
}
]
},
"working_hours": {
"enabled": true,
"monday": [{ "start_minute": 540, "end_minute": 1020 }],
"tuesday": [{ "start_minute": 540, "end_minute": 1020 }],
"wednesday": [{ "start_minute": 540, "end_minute": 1020 }],
"thursday": [{ "start_minute": 540, "end_minute": 1020 }],
"friday": [{ "start_minute": 540, "end_minute": 1020 }],
"saturday": [],
"sunday": []
},
"whatsapp_notifications": {
"pre_call": {
"template_name": "interview_reminder",
"template_variables": {
"body_1": "{{candidate_first_name}}",
"body_2": "Thursday, 21 May 2026, 6:00 PM – 8:45 PM (Networking Dinner included)",
"body_3": "Citymax Business Bay, Dubai",
"button_Yes": "Awesome! Here's the registration link to complete your payment and confirm your seat: https://luma.com/al5h68ce",
"button_No": "Thanks for letting us know. We'll miss you this time, but we'll keep you updated on future events."
}
},
"fallback": {
"template_name": "call_fallback",
"template_variables": {
"body_1": "{{candidate_first_name}}",
"body_2": "We tried calling you about the position but couldn't reach you. Please reply with your availability."
}
}
}
},
"schedule_at": "2026-05-27T10:00:00Z"
}
Example Response
{
"success": true,
"data": {
"project_id": "64a1b2c3d4e5f6a7b8c9d0e1",
"project_url": "https://platform.tidyhire.app/app/projects/64a1b2c3d4e5f6a7b8c9d0e1",
"calls": [
{
"id": "64a1b2c3d4e5f6a7b8c9d0e4",
"candidate_id": "ats-candidate-001",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+917873476062",
"status": "success",
"message": "Call initiated"
}
]
}
}
Authorizations
Your Tidyhire API key
Body
application/json
A unique job identifier from your ATS. Must match a RIA campaign project.
Required string length:
1 - 200Example:
"ats-job-12345"
List of candidates to call. Minimum 1, maximum 50 per request.
Required array length:
1 - 50 elementsShow child attributes
Show child attributes
AI behavior instructions for the call. Supports the same built-in variable substitution as first_message.
Minimum string length:
1Example:
"You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems."
Opening message the AI speaks when the candidate answers. Optional — defaults to "Hello". Supports built-in variables like {{candidate_first_name}} and {{sender_company}}.
Minimum string length:
1Example:
"Hello {{candidate_first_name}}, this is {{sender_company}} calling."
AI assistant configuration for the call. Defaults to a female English voice with standard recruiter behaviour. Book a call with the team to customize.
Show child attributes
Show child attributes
Optional data points to extract from the conversation. The AI will attempt to capture these values during the call.
Show child attributes
Show child attributes
Optional retry policy, working hours, and WhatsApp notification configuration.
Show child attributes
Show child attributes
ISO 8601 datetime to schedule the call for later. If omitted, the call is initiated immediately.
Example:
"2026-05-27T10:00:00Z"
Last modified on August 11, 2026
Was this page helpful?
⌘I