> ## Documentation Index
> Fetch the complete documentation index at: https://docs.techeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /interviews — Kovi Interview Schedule Endpoint

> POST /interviews — creates a new Kovi interview session for a candidate. Returns an interviewUrl to share, and consumes one credit on interview start.

Use `POST /interviews` to create a new interview session for a candidate. Kovi returns a unique `interviewUrl` that the candidate uses to start the interview in their browser.

**Endpoint**

```
POST https://api.techeval.ai/v1/interviews
```

**Authentication:** Bearer token required — see [Authentication](/api-reference/authentication).

***

## Request Body Parameters

<ParamField body="job_id" type="string" required>
  The unique identifier for the job description associated with this interview (e.g., `"JD-AI-7284"`). Used to link the interview session to the correct role in your pipeline.
</ParamField>

<ParamField body="candidate_name" type="string" required>
  The full name of the candidate (e.g., `"Jane Smith"`). Displayed in the scorecard and dashboard.
</ParamField>

<ParamField body="candidate_email" type="string" required>
  The candidate's email address (e.g., `"jane@example.com"`). Used to identify the candidate and associate their scorecard.
</ParamField>

<ParamField body="mobile_number" type="string" required>
  The candidate's mobile number in international format (e.g., `"+1-5550001234"`). Used for session recovery notifications.
</ParamField>

<ParamField body="role" type="string" required>
  The job role or title being interviewed for (e.g., `"AI Engineer"`, `"Backend Developer"`). Kovi uses this to tailor the interview content.
</ParamField>

<ParamField body="interview_type" type="string" required>
  The type of interview to conduct. Must be one of:

  * `"Initial Screening"` — High-level role and experience fit
  * `"Technical Deep Dive"` — In-depth technical questions on the specified stack
  * `"System Design"` — Architecture and design problem-solving
  * `"Behavioral"` — Soft skills and situational questions
  * `"Full Stack"` — Combined technical and behavioral evaluation
</ParamField>

<ParamField body="evaluation_level" type="string" required>
  The seniority level to evaluate the candidate at. Controls question complexity and depth. Must be one of:

  * `"Junior"` — Foundation-level questions and fundamentals
  * `"Mid-Level to Senior"` — Execution-focused questions with some architectural depth
  * `"Senior to Architect"` — Architecture, system design, and leadership-level questions
</ParamField>

<ParamField body="tech_stack" type="array[string]" required>
  An array of technologies the interview will focus on. Kovi restricts the dialogue strictly to your specified stack (e.g., `["Python", "FastAPI", "GCP", "LangChain", "PostgreSQL"]`).
</ParamField>

<ParamField body="duration" type="integer" required>
  Maximum interview duration in minutes. Must not exceed **60 minutes**. We recommend 15–30 minutes for screening sessions and 45–60 minutes for deep dives.
</ParamField>

<ParamField body="pass_score" type="float" required>
  The minimum score a candidate must achieve to pass the interview. We recommend setting this between **6.3 and 7.5**. A highly capable candidate typically scores around 6.5.
</ParamField>

<ParamField body="deadline_hours" type="integer" required>
  Number of hours until the interview link expires. After this period, the `interviewUrl` is no longer accessible (e.g., `48` for a 48-hour window, `72` for 72 hours).
</ParamField>

***

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.techeval.ai/v1/interviews \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "job_id": "JD-AI-7284",
      "candidate_name": "Jane Smith",
      "candidate_email": "jane@example.com",
      "mobile_number": "+1-5550001234",
      "role": "AI Engineer",
      "interview_type": "System Design",
      "evaluation_level": "Mid-Level to Senior",
      "tech_stack": [
        "Python",
        "FastAPI",
        "GCP",
        "LangChain",
        "PostgreSQL",
        "Supabase",
        "Pinecone"
      ],
      "duration": 15,
      "pass_score": 6.5,
      "deadline_hours": 72
    }'
  ```

  ```python Python SDK theme={null}
  from kovi import KoviClient

  client = KoviClient(api_key="YOUR_API_KEY")

  response = client.schedule_interview(
      job_id="JD-AI-7284",
      candidate_name="Jane Smith",
      candidate_email="jane@example.com",
      mobile_number="+1-5550001234",
      role="AI Engineer",
      interview_type="System Design",
      evaluation_level="Mid-Level to Senior",
      tech_stack=[
          "Python", "FastAPI", "GCP", "LangChain",
          "PostgreSQL", "Supabase", "Pinecone"
      ],
      duration=15,
      pass_score=6.5,
      deadline_hours=72
  )

  print(f"Interview URL: {response.get('interviewUrl')}")
  ```
</CodeGroup>

***

## Response

A successful `201 Created` response returns the following fields:

<ResponseField name="interview_id" type="string">
  The unique identifier for this interview session (e.g., `"int_a1b2c3d4"`). Use this ID to retrieve the interview status or pass it to your ATS.
</ResponseField>

<ResponseField name="interviewUrl" type="string">
  The URL to share with the candidate. Paste this directly into your outreach email — the candidate opens it in their browser to begin the interview (e.g., `"https://techeval.ai/interview/int_a1b2c3d4"`).
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the interview. Always `"scheduled"` on creation.
</ResponseField>

<ResponseField name="expires_at" type="string">
  ISO 8601 timestamp indicating when the interview link will expire, calculated from `deadline_hours` (e.g., `"2025-09-15T14:30:00Z"`).
</ResponseField>

**Example response:**

```json theme={null}
{
  "interview_id": "int_a1b2c3d4",
  "interviewUrl": "https://techeval.ai/interview/int_a1b2c3d4",
  "status": "scheduled",
  "expires_at": "2025-09-15T14:30:00Z"
}
```

***

## Error Codes

| HTTP Status | Error | Description |
| - | - | - |
| `400` | `bad_request` | The request body is malformed or missing required fields |
| `401` | `unauthorized` | Missing or invalid API key |
| `402` | `insufficient_credits` | Your account does not have enough credits to schedule an interview |
| `422` | `validation_error` | One or more parameter values are invalid (e.g., `duration` exceeds 60) |

<Note>
  One credit is consumed when the candidate **begins** the interview, not when you create the session. Cancelling or letting a link expire does not deduct any credits from your account.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.