KoviClient Python SDK Reference — Kovi by Techeval

KoviClient is the main entry point for the Kovi Python SDK. It provides methods to schedule interviews and retrieve the resulting interview URL programmatically.

Constructor

`KoviClient(api_key)`

Instantiate the client by passing your Techeval API key. The constructor validates the key format locally but does not make a network request — no credits are consumed at this step.

string

required

Your Techeval platform API key. Retrieve this from the Settings → API section of your Techeval dashboard. Always load this value from an environment variable or secrets manager — never hardcode it.

constructor.py

import os
from kovi import KoviClient

client = KoviClient(api_key=os.environ.get("KOVI_API_KEY"))

`schedule_interview()` Method

Schedule a new AI-conducted interview for a candidate. Kovi generates a unique interview link and emails it directly to the candidate.

Method Signature

schedule_interview_signature.py

client.schedule_interview(
    job_id: str,
    candidate_name: str,
    candidate_email: str,
    mobile_number: str,
    role: str,
    interview_type: str,
    evaluation_level: str,
    tech_stack: list[str],
    duration: int,
    pass_score: float,
    deadline_hours: int
) -> dict

Parameters

string

required

Your job description identifier created in the Techeval dashboard (e.g. "JD-AI-7284"). Kovi uses this to load the associated job description for question generation.

string

required

Full name of the candidate as it should appear in the scorecard and communications (e.g. "Jane Doe").

string

required

Candidate’s email address. Kovi sends the interview link to this address automatically after scheduling.

string

required

Candidate’s phone number including country code (e.g. "+91-9999999999"). Used for SMS notifications and proctoring identity verification.

string

required

Job title for this specific interview round (e.g. "AI Engineer", "Backend Developer", "Staff Engineer"). Kovi tailors question framing and depth to this role.

string

required

The stage of your recruitment pipeline this interview covers. Must be one of:

Value	Description
`"Initial Screening"`	Broad, time-efficient first-round filter
`"Technical Deep Dive"`	In-depth assessment of core engineering skills
`"System Design"`	Architecture and scalability problem-solving
`"Behavioral"`	Situational and competency-based questions
`"Full Stack"`	End-to-end product engineering evaluation

string

required

Candidate seniority level. Controls question complexity and the depth of technical follow-ups. Must be one of:

Value	Audience
`"Junior"`	0–2 years of experience / foundation skills
`"Mid-Level to Senior"`	3–7 years / execution-focused
`"Senior to Architect"`	8+ years / system-wide ownership

list[str]

required

List of technologies Kovi should focus on during the interview (e.g. ["Python", "FastAPI", "PostgreSQL"]). Keep the list specific to your production stack for the most relevant evaluation.

integer

required

Target interview duration in minutes. Maximum: 60 minutes. One credit is consumed per interview regardless of duration (up to the 60-minute cap).

float

required

Minimum score a candidate must achieve to be considered a pass. Kovi grades on a rigorous rubric — a highly capable candidate typically scores around 6.5. Recommended range: 6.3–7.5.

integer

required

Number of hours until the generated interview link expires (e.g. 48 or 72). After expiration, the link becomes inactive and the candidate must be rescheduled.

Return Value

schedule_interview() returns a dict containing the generated interview link on success.

Key	Type	Description
`interviewUrl`	`str`	The unique, time-limited URL to send to the candidate. Kovi also emails this automatically to `candidate_email`.

Extracting the interview URL:

get_interview_url.py

response = client.schedule_interview(
    # ... parameters
)

interview_url = response.get("interviewUrl")
print(f"Send this link to the candidate: {interview_url}")

Error Handling

Wrap every schedule_interview() call in a try/except block. Network errors, authentication failures, and invalid parameters all raise exceptions.

error_handling.py

import os
from kovi import KoviClient

client = KoviClient(api_key=os.environ.get("KOVI_API_KEY"))

try:
    response = client.schedule_interview(
        job_id="JD-AI-7284",
        candidate_name="Jane Doe",
        candidate_email="jane.doe@example.com",
        mobile_number="+91-9999999999",
        role="AI Engineer",
        interview_type="System Design",
        evaluation_level="Mid-Level to Senior",
        tech_stack=["Python", "FastAPI", "LangChain", "PostgreSQL"],
        duration=45,
        pass_score=6.5,
        deadline_hours=72
    )

    print("✅ Interview scheduled successfully!")
    print(f"🔗 Interview URL: {response.get('interviewUrl')}")

except Exception as e:
    print(f"❌ Failed to schedule interview: {e}")

Common Errors

Error	Cause	Resolution
`401 Unauthorized`	Invalid or expired API key	Verify your `KOVI_API_KEY` environment variable matches the key in your Techeval dashboard
`402 Payment Required`	Insufficient interview credits	Top up credits at techeval.ai before scheduling further interviews
`422 Unprocessable Entity`	Invalid parameter value	Check that `interview_type`, `evaluation_level`, and `duration` match the accepted values listed above
`429 Too Many Requests`	Rate limit exceeded	Back off and retry after a delay; do not retry immediately in a tight loop

Do not silently swallow exceptions. Log the full error message so you can diagnose issues and avoid unknowingly losing interview schedules in bulk pipelines.

Get Started

Core Concepts

Guides

Python SDK

Webhooks

KoviClient Python SDK Reference — Kovi by Techeval

Constructor

`KoviClient(api_key)`

`schedule_interview()` Method

Method Signature

Parameters

Return Value

Error Handling

Common Errors

​Constructor

​KoviClient(api_key)

​schedule_interview() Method

​Method Signature

​Parameters

​Return Value

​Error Handling

​Common Errors

Constructor

`KoviClient(api_key)`

`schedule_interview()` Method

Method Signature

Parameters

Return Value

Error Handling

Common Errors