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

# Kovi Webhook Scorecard Payload: Full Field Reference

> Full reference for the Kovi webhook scorecard JSON payload—all fields, types, and example values sent to your endpoint after each interview.

Every time a Kovi interview finishes, a JSON payload is sent to your webhook endpoint. This reference documents every field in that payload so you can map it correctly to your ATS or data store.

## Example Payload

```json scorecard_payload.json theme={null}
{
  "candidate_id": "cnd_98765",
  "final_score": 7.2,
  "passed_threshold": true,
  "proctoring_flags": {
    "tab_switches": 0,
    "ai_copilot_detected": false,
    "disconnects": 1
  },
  "strengths": ["Database Scaling", "Microservices Architecture"],
  "weaknesses": ["CI/CD Pipeline Configuration"],
  "transcript_url": "https://techeval.ai/dash/transcripts/cnd_98765"
}
```

## Payload Fields

<ResponseField name="candidate_id" type="string" required>
  Unique identifier for this candidate interview session. Use this value to correlate the incoming scorecard with the candidate record in your ATS or database.

  <Tip>
    Store the `candidate_id` from the webhook payload alongside your internal candidate record so you can retrieve transcripts and re-query scorecards from the dashboard later.
  </Tip>
</ResponseField>

<ResponseField name="final_score" type="float" required>
  Overall evaluation score on a **0–10 scale**, calculated from Kovi's strict grading rubric across all interview segments. A highly capable candidate typically scores around **6.5**. Kovi recommends setting your pass threshold between **6.3 and 7.5**.
</ResponseField>

<ResponseField name="passed_threshold" type="boolean" required>
  `true` if `final_score` is greater than or equal to the `pass_score` you configured when scheduling the interview. Use this field for automated pipeline routing—advance passing candidates and filter out those who fall below your threshold without manual review.
</ResponseField>

<ResponseField name="proctoring_flags" type="object" required>
  Anti-cheat monitoring results captured throughout the interview session. These fields are evidence indicators to inform your hiring decision—they are **not** automatic disqualifiers. See [Handling Proctoring Flags](#handling-proctoring-flags) for guidance on interpreting them.

  <Expandable title="proctoring_flags fields">
    <ResponseField name="tab_switches" type="integer" required>
      Number of times the candidate switched away from the interview browser tab during the session. Frequent tab switches may indicate the candidate was referencing external resources.
    </ResponseField>

    <ResponseField name="ai_copilot_detected" type="boolean" required>
      Whether Kovi's speech-pattern analysis detected AI tool usage during the interview. When `true`, Kovi identified suspicious patterns—such as unnatural cadence or verbatim recitation—consistent with reading AI-generated answers aloud. Always review the transcript before drawing a conclusion.
    </ResponseField>

    <ResponseField name="disconnects" type="integer" required>
      Number of times the candidate's connection dropped during the session. Kovi auto-saves session state on each disconnect, allowing the candidate to resume. If a candidate disconnects more than twice, HR is automatically notified.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="strengths" type="array[string]" required>
  Technical topics where the candidate demonstrated strong knowledge and clear command. Use these to validate role fit and identify areas where the candidate can contribute immediately.

  **Example:** `["Database Scaling", "Microservices Architecture"]`
</ResponseField>

<ResponseField name="weaknesses" type="array[string]" required>
  Technical topics where the candidate showed knowledge gaps or insufficient depth during the interview. Use these to structure onboarding plans or to flag mismatches against must-have role requirements.

  **Example:** `["CI/CD Pipeline Configuration"]`
</ResponseField>

<ResponseField name="transcript_url" type="string" required>
  URL to the full interview transcript hosted on the Techeval platform. Clicking through requires an active Techeval dashboard login. Review the transcript to validate proctoring flags, audit Kovi's scoring, or share the session with hiring managers.

  **Example:** `https://techeval.ai/dash/transcripts/cnd_98765`
</ResponseField>

## Handling Proctoring Flags

The fields inside `proctoring_flags` are **evidence capture outputs**, not automatic pass/fail verdicts. Kovi's proctoring engine deliberately does not terminate interviews when suspicious behaviour is detected—it continues the session, collects all evidence, and surfaces it in the scorecard so you retain full context for your decision.

Follow this workflow when reviewing flagged scorecards:

* **`ai_copilot_detected: true`** — Kovi's speech-pattern analysis flagged behaviour consistent with AI-assisted answering (e.g., unnatural delivery, reading from generated text). Open the `transcript_url` and listen to the session before acting. A single flag on one question does not necessarily indicate cheating; a consistent pattern across multiple questions is a stronger signal.
* **`tab_switches > 0`** — Cross-reference the count against the candidate's overall performance. A candidate who switches tabs frequently but scores highly may have been switching to an IDE or documentation, which is context-dependent.
* **`disconnects > 0`** — Connection drops are often caused by network instability rather than intentional behaviour. Kovi handles recovery automatically, and the interview continues seamlessly from where it left off.

<Warning>
  Never disqualify a candidate based solely on a proctoring flag. Always review the transcript at `transcript_url` and apply your own judgment before making a hiring decision.
</Warning>

<Note>
  Scorecard data is also accessible in the Techeval dashboard under the candidate's profile page, where you can view scores, flags, and the full transcript in a single view.
</Note>


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