Schedule Assessment Calls

Api to 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

{
  "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

{
  "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

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": "[phone]",
          "email": "[e-mail]",
          "company": {
            "name": "InnovateX",
            "description": "AI-powered software tools."
          }
        }
      }
    ]
  }'

---