Skip to main content
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"
        }
      ]
    },
    "whatsapp_notifications": {}
  },
  "schedule_at": "2026-05-27T10:00:00Z"
}
'
{
  "success": true,
  "data": {
    "project_id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "calls": [
      {
        "id": "64a1b2c3d4e5f6a7b8c9d0e4",
        "candidate_id": "64a1b2c3d4e5f6a7b8c9d0e2",
        "external_id": "ats-candidate-001",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+917873476062",
        "code": "CALL_SCHEDULED",
        "message": "A call is scheduled for this candidate."
      }
    ]
  }
}
Use the same ats_job_id across multiple requests to call additional candidates on an existing campaign project.

​
Dynamic Variables

Both first_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:
VariableDescription
{{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 using whatsapp_notifications, the template_variables object accepts two value types:
  1. Built-in resolver reference — {"body_1": "{{candidate_first_name}}"} resolves automatically using candidate/job/sender data.
  2. Literal text — {"body_2": "Thursday, 21 May 2026, 6:00 PM..."} is passed through as-is.

​
Example Request

{
  "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}}. 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"
        }
      ]
    },
    "whatsapp_notifications": {
      "pre_call": {
        "template_id": "64a1b2c3d4e5f6a7b8c9d0e1",
        "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_id": "64a1b2c3d4e5f6a7b8c9d0e2",
        "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"
}

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. Must match a RIA campaign project.

Required string length: 1 - 200
Example:

"ats-job-12345"

​
candidates
object[]
required

List of candidates to call. Minimum 1, maximum 50 per request.

Required array length: 1 - 50 elements
​
instructions
string
required

AI behavior instructions for the call. Supports the same built-in variable substitution as first_message.

Minimum string length: 1
Example:

"You are a recruiter for {{sender_company}}. Screen the candidate about their experience with distributed systems."

​
first_message
string
default:Hello

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: 1
Example:

"Hello {{candidate_first_name}}, this is {{sender_company}} calling."

​
assistant_settings
object

AI assistant configuration for the call. Defaults to a female English voice with standard recruiter behaviour. Book a call with the team to customize.

​
extract_variables
object[]

Optional data points to extract from the conversation. The AI will attempt to capture these values during the call.

​
call_settings
object

Optional retry policy and WhatsApp notification configuration.

​
schedule_at
string<date-time>

ISO 8601 datetime to schedule the call for later. If omitted, the call is initiated immediately.

Example:

"2026-05-27T10:00:00Z"

Response

Success.

​
success
boolean
Example:

true

​
data
object
Last modified on June 1, 2026