Skip to main content
POST
/
api
/
public
/
v1
/
ai
/
generate-script
Generate AI Call Script
curl --request POST \
  --url https://api.tidyhire.app/api/public/v1/ai/generate-script \
  --header 'Content-Type: application/json' \
  --header 'x-tidyhire-api-key: <api-key>' \
  --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."
    },
    {
      "question": "Is this remote?",
      "answer": "Yes, fully remote."
    }
  ]
}
'
{
  "success": true,
  "data": {
    "instructions": "You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role. Ask about their experience with distributed systems.",
    "extract_variables": [
      {
        "label": "Years of Experience",
        "description": "How many years of professional experience does the candidate have?",
        "format_example": "5 years",
        "choices": [
          "<string>"
        ]
      }
    ]
  }
}
This endpoint is AI-powered. 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. These can be passed directly to the Initiate AI Call endpoint as the instructions field.
  • extract_variables — Structured data fields the AI should extract during the call. These can be passed directly to the Initiate AI Call endpoint as the extract_variables field.

​
Example Request

{
  "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?",
    "Describe a challenging system design problem you have solved."
  ],
  "faqs": [
    {
      "question": "What is the salary range?",
      "answer": "The range is $120k - $180k depending on experience."
    },
    {
      "question": "Is this remote?",
      "answer": "Yes, fully remote."
    },
    {
      "question": "What is the interview process?",
      "answer": "There will be a technical round followed by a system design discussion."
    }
  ]
}

​
Example Response

{
  "success": true,
  "data": {
    "instructions": "You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role. Ask about their experience with distributed systems, Node.js, and microservices architecture. Be professional and friendly. If candidates ask about salary, mention the range is $120k - $180k depending on experience. If they ask about remote work, confirm it is fully remote.",
    "extract_variables": [
      {
        "label": "Years of Experience",
        "type": "integer",
        "description": "How many years of professional experience does the candidate have?",
        "format_example": "5"
      },
      {
        "label": "Node.js Experience",
        "type": "boolean",
        "description": "Does the candidate have experience with Node.js?",
        "format_example": "true"
      },
      {
        "label": "Microservices Experience",
        "type": "string",
        "description": "Describe the candidate's experience with microservices architecture.",
        "format_example": "Built and maintained a microservices-based e-commerce platform"
      }
    ]
  }
}

Authorizations

​
x-tidyhire-api-key
string
header
required

Your Tidyhire API key

Body

application/json
​
company_name
string
required

Name of the company.

Minimum string length: 1
Example:

"Acme Corp"

​
prompt
string
required

The main task or goal for the AI call. Describes what the AI should accomplish.

Minimum string length: 1
Example:

"Screen candidates for the Senior Software Engineer position and assess their experience with distributed systems."

​
questions
string[]

Specific questions the AI should ask during the call.

Minimum string length: 1
Example:
[
  "How many years of experience do you have with Node.js?",
  "Have you worked with microservices architecture?"
]
​
faqs
object[]

Frequently asked questions and their answers to help the AI respond accurately.

Example:
[
  {
    "question": "What is the salary range?",
    "answer": "The range is $120k - $180k depending on experience."
  },
  {
    "question": "Is this remote?",
    "answer": "Yes, fully remote."
  }
]

Response

Success.

​
success
boolean
Example:

true

​
data
object
Last modified on May 29, 2026