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

# KoviClient Python SDK Reference — Kovi by Techeval

> Complete reference for the KoviClient class—constructor, schedule_interview() method, all parameters, return values, and error handling.

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

<ParamField path="api_key" type="string" required>
  Your Techeval platform API key. Retrieve this from the **Settings → API** section of your [Techeval dashboard](https://techeval.ai). Always load this value from an environment variable or secrets manager — never hardcode it.
</ParamField>

```python constructor.py theme={null}
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

```python schedule_interview_signature.py theme={null}
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

<ParamField path="job_id" type="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.
</ParamField>

<ParamField path="candidate_name" type="string" required>
  Full name of the candidate as it should appear in the scorecard and communications (e.g. `"Jane Doe"`).
</ParamField>

<ParamField path="candidate_email" type="string" required>
  Candidate's email address. Kovi sends the interview link to this address automatically after scheduling.
</ParamField>

<ParamField path="mobile_number" type="string" required>
  Candidate's phone number including country code (e.g. `"+91-9999999999"`). Used for SMS notifications and proctoring identity verification.
</ParamField>

<ParamField path="role" type="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.
</ParamField>

<ParamField path="interview_type" type="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 |
</ParamField>

<ParamField path="evaluation_level" type="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 |
</ParamField>

<ParamField path="tech_stack" type="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.
</ParamField>

<ParamField path="duration" type="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).
</ParamField>

<ParamField path="pass_score" type="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.**
</ParamField>

<ParamField path="deadline_hours" type="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.
</ParamField>

***

## 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:**

```python get_interview_url.py theme={null}
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.

```python error_handling.py theme={null}
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](https://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 |

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


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