---
description: Api to schedule assessment calls
---

# Schedule Assessment Calls

### **Endpoint**

`POST /api/assessment`

#### **Description**

Schedules one or more assessment calls between an agent and a candidate. This may be used for technical interviews, screening assessments, or behavioral evaluations.

***

### **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": [
    {
      "title": "string",
      "agent_name": "string",
      "scheduled_at": "string",
      "custom_prompt": "string",
      "timezone": "string",
      "candidate": {
        "name": "string",
        "phoneNumber": "string",
        "email": "string",
        "company": {
          "name": "string",
          "description": "string"
        }
      }
    }
  ]
}
```

#### **Field Descriptions**

**Top-Level**

| Field   | Type             | Required | Description                                 |
| ------- | ---------------- | -------- | ------------------------------------------- |
| `calls` | Array of Objects | Yes      | A list of assessment calls to be scheduled. |

**`calls[]` Fields**

| Field           | Type              | Required | Description                                     |
| --------------- | ----------------- | -------- | ----------------------------------------------- |
| `title`         | String            | Yes      | Title of the assessment (e.g., "Tech Round 1"). |
| `agent_name`    | String            | Yes      | Name of the interviewer or agent.               |
| `scheduled_at`  | String (ISO 8601) | Yes      | Date/time when the call is scheduled.           |
| `custom_prompt` | String            | No       | Optional custom question or prompt.             |
| `timezone`      | String            | Yes      | Timezone in which the interview is scheduled.   |

**`candidate`**

| Field         | Type   | Required | Description                 |
| ------------- | ------ | -------- | --------------------------- |
| `name`        | String | Yes      | Full name of the candidate. |
| `phoneNumber` | String | Yes      | Candidate’s contact number. |
| `email`       | String | Yes      | Candidate’s email address.  |

**`company`**

| Field         | Type   | Required | Description                                    |
| ------------- | ------ | -------- | ---------------------------------------------- |
| `name`        | String | Yes      | Name of the company conducting the assessment. |
| `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                                 |
| ---------------- | ------- | ------------------------------------------- |
| `success`        | Boolean | Indicates if the operation was successful.  |
| `message`        | String  | General status message.                     |
| `data`           | Array   | List of individual call scheduling results. |
| `data[].message` | String  | Status message for each call.               |
| `data[].callId`  | String  | Unique identifier of the scheduled call.    |
| `timestamp`      | String  | Timestamp of the response (ISO 8601).       |

***

### **Example cURL Request**

```bash
curl -X POST http://localhost:3900/api/assessment \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "calls": [
      {
        "title": "Frontend Developer Assessment",
        "agent_name": "Alice Johnson",
        "scheduled_at": "2025-05-23T13:00:00Z",
        "custom_prompt": "Focus on system design.",
        "timezone": "UTC",
        "candidate": {
          "name": "Bob Lee",
          "phoneNumber": "+19876543210",
          "email": "bob@example.com",
          "company": {
            "name": "InnovateX",
            "description": "AI-powered software tools."
          }
        }
      }
    ]
  }'
```

***
