---
description: Api to schedule automated hiring calls
---

# Schedule 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**

```json
{
  "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**

```json
{
  "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**

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

#### **500 Internal Server Error**

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

***

### **Example cURL Request**

```bash
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": "+1234567890",
          "email": "jane@example.com",
          "interview_details": {
            "years_of_experience": "5",
            "required_skills": ["Node.js", "React", "AWS"]
          },
          "company": {
            "name": "TechCorp",
            "description": "A fast-growing cloud platform"
          }
        }
      }
    ]
  }'
```
