POST /interviews — Kovi Interview Schedule Endpoint

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.

Request Body Parameters

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.

string

required

The full name of the candidate (e.g., "Jane Smith"). Displayed in the scorecard and dashboard.

string

required

The candidate’s email address (e.g., "jane@example.com"). Used to identify the candidate and associate their scorecard.

string

required

The candidate’s mobile number in international format (e.g., "+1-5550001234"). Used for session recovery notifications.

string

required

The job role or title being interviewed for (e.g., "AI Engineer", "Backend Developer"). Kovi uses this to tailor the interview content.

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

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

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"]).

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.

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.

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).

Example Request

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
  }'

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')}")

Response

A successful 201 Created response returns the following fields:

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.

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").

string

The current status of the interview. Always "scheduled" on creation.

string

ISO 8601 timestamp indicating when the interview link will expire, calculated from deadline_hours (e.g., "2025-09-15T14:30:00Z").

Example response:

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

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.

Overview

Interviews

Scorecards

POST /interviews — Kovi Interview Schedule Endpoint

Request Body Parameters

Example Request

Response

Error Codes

​Request Body Parameters

​Example Request

​Response

​Error Codes

Request Body Parameters

Example Request

Response

Error Codes