Schedule Hiring Calls

Api to schedule automated hiring calls

Hiring API Documentation

Endpoint

POST /api/hiring

Description

This endpoint is used to schedule one or more hiring-related calls between an agent and an applicant. Each call includes details such as the role, interview time, applicant information, and optional custom prompts.

---

Authentication

This endpoint requires an API key.

Required Header

Header	Value	Description
x-api-key	{token}	API key provided for authentication.

---

Request Headers

Header	Value	Description
accept	*/*	Accepts any content type.
Content-Type	application/json	Specifies JSON format for the request.
x-api-key	{token}	Required. Your API authentication key.

---

Request Body

JSON Structure

{
  "calls": [
    {
      "role": "string",
      "agent_name": "string",
      "scheduled_at": "string",
      "custom_prompt": "string",
      "timezone": "string",
      "applicant": {
        "name": "string",
        "phoneNumber": "string",
        "email": "string",
        "interview_details": {
          "years_of_experience": "string",
          "required_skills": [
            "string"
          ]
        },
        "company": {
          "name": "string",
          "description": "string"
        }
      }
    }
  ]
}

Fields

Top-Level

Field	Type	Required	Description
calls	Array of Objects	Yes	A list of calls to be scheduled.

calls[]

Field	Type	Required	Description
role	String	Yes	The job role the applicant is being interviewed for.
agent_name	String	Yes	Name of the agent conducting the interview.
scheduled_at	String (ISO 8601)	No	Scheduled date and time of the call (e.g., "2025-05-20T14:00:00Z").
custom_prompt	String	No	Custom prompt or question to be asked during the interview.
timezone	String	No	Timezone for the interview schedule (e.g., "America/New_York").

applicant

Field	Type	Required	Description
name	String	Yes	Full name of the applicant.
phoneNumber	String	Yes	Applicant’s phone number.
email	String	Yes	Applicant’s email address.

interview_details

Field	Type	Required	Description
years_of_experience	String	Yes	Number of years of relevant experience.
required_skills	Array of Strings	Yes	List of skills required for the role.

company

Field	Type	Required	Description
name	String	Yes	Name of the company conducting the interview.
description	String	No	Description of the company.

---

Response

Success Response

{
  "success": true,
  "message": "Calls scheduled successfully",
  "data": [
    {
      "message": "Call scheduled successfully",
      "callId": "682bb205f919c505e9cb871"
    }
  ],
  "timestamp": "2025-05-19T23:04:38.115Z"
}

Field	Type	Description
message	String	Success message.
data	Array	List of scheduled calls with their IDs and statuses.

---

Error Responses

400 Bad Request

{
  "error": "Invalid input. Missing required fields."
}

500 Internal Server Error

{
  "error": "An unexpected error occurred."
}

---

Example cURL Request

curl -X POST http://localhost:3900/api/hiring \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "calls": [
      {
        "role": "Software Engineer",
        "agent_name": "John Doe",
        "scheduled_at": "2025-05-22T15:00:00Z",
        "custom_prompt": "Discuss microservices experience",
        "timezone": "UTC",
        "applicant": {
          "name": "Jane Smith",
          "phoneNumber": "[phone]",
          "email": "[e-mail]",
          "interview_details": {
            "years_of_experience": "5",
            "required_skills": ["Node.js", "React", "AWS"]
          },
          "company": {
            "name": "TechCorp",
            "description": "A fast-growing cloud platform"
          }
        }
      }
    ]
  }'