Call
Generate AI Call Script
POST
/
ai
/
generate-script
curl --request POST \
--url https://api.tidyhire.app/api/public/v1/ai/generate-script \
--header 'x-tidyhire-api-key: <token>' \
--header 'Content-Type: application/json' \
--data '{
"company_name": "Acme Corp",
"prompt": "Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.",
"questions": [
"How many years of experience do you have with Node.js?",
"Have you worked with microservices architecture?"
],
"faqs": [
{
"question": "What is the salary range?",
"answer": "The range is $120k - $180k depending on experience."
}
]
}'
fetch('https://api.tidyhire.app/api/public/v1/ai/generate-script', {
method: 'POST',
headers: {
'x-tidyhire-api-key': '<token>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
company_name: 'Acme Corp',
prompt:
'Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.',
questions: [
'How many years of experience do you have with Node.js?',
'Have you worked with microservices architecture?',
],
faqs: [
{
question: 'What is the salary range?',
answer: 'The range is $120k - $180k depending on experience.',
},
],
}),
})
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error('Error:', error));
<?php
$url = 'https://api.tidyhire.app/api/public/v1/ai/generate-script';
$data = [
'company_name' => 'Acme Corp',
'prompt' => 'Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.',
'questions' => [
'How many years of experience do you have with Node.js?',
'Have you worked with microservices architecture?'
],
'faqs' => [
[
'question' => 'What is the salary range?',
'answer' => 'The range is $120k - $180k depending on experience.'
]
]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'x-tidyhire-api-key: <token>',
'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
url := "https://api.tidyhire.app/api/public/v1/ai/generate-script"
payload := map[string]interface{}{
"company_name": "Acme Corp",
"prompt": "Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.",
"questions": []string{
"How many years of experience do you have with Node.js?",
"Have you worked with microservices architecture?",
},
"faqs": []map[string]string{
{
"question": "What is the salary range?",
"answer": "The range is $120k - $180k depending on experience.",
},
},
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("x-tidyhire-api-key", "<token>")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error:", err)
return
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
public class GenerateScript {
public static void main(String[] args) {
try {
URL url = new URL("https://api.tidyhire.app/api/public/v1/ai/generate-script");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("x-tidyhire-api-key", "<token>");
con.setRequestProperty("Content-Type", "application/json");
con.setDoOutput(true);
String jsonInputString = "{\n" +
" \"company_name\": \"Acme Corp\",\n" +
" \"prompt\": \"Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.\",\n" +
" \"questions\": [\n" +
" \"How many years of experience do you have with Node.js?\",\n" +
" \"Have you worked with microservices architecture?\"\n" +
" ],\n" +
" \"faqs\": [{\n" +
" \"question\": \"What is the salary range?\",\n" +
" \"answer\": \"The range is $120k - $180k depending on experience.\"\n" +
" }]\n" +
"}";
try (OutputStream os = con.getOutputStream()) {
byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
}
int status = con.getResponseCode();
System.out.println("Response Status: " + status);
} catch (Exception e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'json'
require 'uri'
uri = URI('https://api.tidyhire.app/api/public/v1/ai/generate-script')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request['x-tidyhire-api-key'] = '<token>'
request['Content-Type'] = 'application/json'
request.body = {
company_name: 'Acme Corp',
prompt: 'Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.',
questions: [
'How many years of experience do you have with Node.js?',
'Have you worked with microservices architecture?'
],
faqs: [
{
question: 'What is the salary range?',
answer: 'The range is $120k - $180k depending on experience.'
}
]
}.to_json
response = http.request(request)
puts response.body
{
"success": true,
"data": {
"instructions": "You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role.",
"extract_variables": [
{
"label": "Years of Experience",
"type": "integer",
"description": "How many years of professional experience does the candidate have?",
"format_example": "5"
}
]
}
}
This endpoint is AI-powered and rate limited to 5 requests/minute. It generates AI call instructions and a structured data extraction plan based on your company details, task prompt, questions, and FAQs.
What it returns
- instructions — AI behavior instructions for the call. Pass directly to Initiate AI Call as
instructions. - extract_variables — Structured data fields the AI should extract during the call. Pass directly to Initiate AI Call as
extract_variables.
curl --request POST \
--url https://api.tidyhire.app/api/public/v1/ai/generate-script \
--header 'x-tidyhire-api-key: <token>' \
--header 'Content-Type: application/json' \
--data '{
"company_name": "Acme Corp",
"prompt": "Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.",
"questions": [
"How many years of experience do you have with Node.js?",
"Have you worked with microservices architecture?"
],
"faqs": [
{
"question": "What is the salary range?",
"answer": "The range is $120k - $180k depending on experience."
}
]
}'
fetch('https://api.tidyhire.app/api/public/v1/ai/generate-script', {
method: 'POST',
headers: {
'x-tidyhire-api-key': '<token>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
company_name: 'Acme Corp',
prompt:
'Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.',
questions: [
'How many years of experience do you have with Node.js?',
'Have you worked with microservices architecture?',
],
faqs: [
{
question: 'What is the salary range?',
answer: 'The range is $120k - $180k depending on experience.',
},
],
}),
})
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error('Error:', error));
<?php
$url = 'https://api.tidyhire.app/api/public/v1/ai/generate-script';
$data = [
'company_name' => 'Acme Corp',
'prompt' => 'Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.',
'questions' => [
'How many years of experience do you have with Node.js?',
'Have you worked with microservices architecture?'
],
'faqs' => [
[
'question' => 'What is the salary range?',
'answer' => 'The range is $120k - $180k depending on experience.'
]
]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'x-tidyhire-api-key: <token>',
'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
url := "https://api.tidyhire.app/api/public/v1/ai/generate-script"
payload := map[string]interface{}{
"company_name": "Acme Corp",
"prompt": "Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.",
"questions": []string{
"How many years of experience do you have with Node.js?",
"Have you worked with microservices architecture?",
},
"faqs": []map[string]string{
{
"question": "What is the salary range?",
"answer": "The range is $120k - $180k depending on experience.",
},
},
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("x-tidyhire-api-key", "<token>")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error:", err)
return
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
public class GenerateScript {
public static void main(String[] args) {
try {
URL url = new URL("https://api.tidyhire.app/api/public/v1/ai/generate-script");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("x-tidyhire-api-key", "<token>");
con.setRequestProperty("Content-Type", "application/json");
con.setDoOutput(true);
String jsonInputString = "{\n" +
" \"company_name\": \"Acme Corp\",\n" +
" \"prompt\": \"Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.\",\n" +
" \"questions\": [\n" +
" \"How many years of experience do you have with Node.js?\",\n" +
" \"Have you worked with microservices architecture?\"\n" +
" ],\n" +
" \"faqs\": [{\n" +
" \"question\": \"What is the salary range?\",\n" +
" \"answer\": \"The range is $120k - $180k depending on experience.\"\n" +
" }]\n" +
"}";
try (OutputStream os = con.getOutputStream()) {
byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
}
int status = con.getResponseCode();
System.out.println("Response Status: " + status);
} catch (Exception e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'json'
require 'uri'
uri = URI('https://api.tidyhire.app/api/public/v1/ai/generate-script')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request['x-tidyhire-api-key'] = '<token>'
request['Content-Type'] = 'application/json'
request.body = {
company_name: 'Acme Corp',
prompt: 'Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.',
questions: [
'How many years of experience do you have with Node.js?',
'Have you worked with microservices architecture?'
],
faqs: [
{
question: 'What is the salary range?',
answer: 'The range is $120k - $180k depending on experience.'
}
]
}.to_json
response = http.request(request)
puts response.body
{
"success": true,
"data": {
"instructions": "You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role.",
"extract_variables": [
{
"label": "Years of Experience",
"type": "integer",
"description": "How many years of professional experience does the candidate have?",
"format_example": "5"
}
]
}
}
Authorizations
string | header
required
API key of the form
<token>, passed as the x-tidyhire-api-key header.Body
string
required
Name of the company.Example:
"Acme Corp"string
required
The main task or goal for the AI call. Describes what the AI should accomplish.Example:
"Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems."string[]
Specific questions the AI should ask during the call.Example:
["How many years of experience do you have with Node.js?"]
object[]
boolean
If
true, the AI automatically ends the call when a candidate is disqualified based on screening criteria. Defaults to false.Response
AI call script generated successfullyboolean
Indicates if the request was successful. Example:
trueobject
Show child attributes
Show child attributes
string
Generated AI behavior instructions for the call.
object[]
Common Errors
- 400 Bad Request
- 401 Unauthorized
- 422 Validation Error
- 429 Too Many Requests
Reason: The request body is not valid JSON.
{
"success": false,
"message": "Invalid JSON in request body"
}
Reason: Missing or invalid
x-tidyhire-api-key header.{
"success": false,
"message": "Unauthorized, Please reach out at support@tidyhire.app"
}
Reason: Missing or invalid fields — each entry in
errors points to a specific field.{
"success": false,
"message": "Validation error: Prompt is required",
"errors": [
{ "path": "prompt", "message": "Prompt is required" }
]
}
Reason: More than 5 requests in a minute.
{
"success": false,
"message": "Too many requests, please try again later"
}
Was this page helpful?
⌘I
curl --request POST \
--url https://api.tidyhire.app/api/public/v1/ai/generate-script \
--header 'x-tidyhire-api-key: <token>' \
--header 'Content-Type: application/json' \
--data '{
"company_name": "Acme Corp",
"prompt": "Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.",
"questions": [
"How many years of experience do you have with Node.js?",
"Have you worked with microservices architecture?"
],
"faqs": [
{
"question": "What is the salary range?",
"answer": "The range is $120k - $180k depending on experience."
}
]
}'
fetch('https://api.tidyhire.app/api/public/v1/ai/generate-script', {
method: 'POST',
headers: {
'x-tidyhire-api-key': '<token>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
company_name: 'Acme Corp',
prompt:
'Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.',
questions: [
'How many years of experience do you have with Node.js?',
'Have you worked with microservices architecture?',
],
faqs: [
{
question: 'What is the salary range?',
answer: 'The range is $120k - $180k depending on experience.',
},
],
}),
})
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error('Error:', error));
<?php
$url = 'https://api.tidyhire.app/api/public/v1/ai/generate-script';
$data = [
'company_name' => 'Acme Corp',
'prompt' => 'Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.',
'questions' => [
'How many years of experience do you have with Node.js?',
'Have you worked with microservices architecture?'
],
'faqs' => [
[
'question' => 'What is the salary range?',
'answer' => 'The range is $120k - $180k depending on experience.'
]
]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'x-tidyhire-api-key: <token>',
'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
url := "https://api.tidyhire.app/api/public/v1/ai/generate-script"
payload := map[string]interface{}{
"company_name": "Acme Corp",
"prompt": "Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.",
"questions": []string{
"How many years of experience do you have with Node.js?",
"Have you worked with microservices architecture?",
},
"faqs": []map[string]string{
{
"question": "What is the salary range?",
"answer": "The range is $120k - $180k depending on experience.",
},
},
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("x-tidyhire-api-key", "<token>")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error:", err)
return
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
public class GenerateScript {
public static void main(String[] args) {
try {
URL url = new URL("https://api.tidyhire.app/api/public/v1/ai/generate-script");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("x-tidyhire-api-key", "<token>");
con.setRequestProperty("Content-Type", "application/json");
con.setDoOutput(true);
String jsonInputString = "{\n" +
" \"company_name\": \"Acme Corp\",\n" +
" \"prompt\": \"Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.\",\n" +
" \"questions\": [\n" +
" \"How many years of experience do you have with Node.js?\",\n" +
" \"Have you worked with microservices architecture?\"\n" +
" ],\n" +
" \"faqs\": [{\n" +
" \"question\": \"What is the salary range?\",\n" +
" \"answer\": \"The range is $120k - $180k depending on experience.\"\n" +
" }]\n" +
"}";
try (OutputStream os = con.getOutputStream()) {
byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
}
int status = con.getResponseCode();
System.out.println("Response Status: " + status);
} catch (Exception e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'json'
require 'uri'
uri = URI('https://api.tidyhire.app/api/public/v1/ai/generate-script')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request['x-tidyhire-api-key'] = '<token>'
request['Content-Type'] = 'application/json'
request.body = {
company_name: 'Acme Corp',
prompt: 'Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems.',
questions: [
'How many years of experience do you have with Node.js?',
'Have you worked with microservices architecture?'
],
faqs: [
{
question: 'What is the salary range?',
answer: 'The range is $120k - $180k depending on experience.'
}
]
}.to_json
response = http.request(request)
puts response.body
{
"success": true,
"data": {
"instructions": "You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role.",
"extract_variables": [
{
"label": "Years of Experience",
"type": "integer",
"description": "How many years of professional experience does the candidate have?",
"format_example": "5"
}
]
}
}