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

# Score Card Templates

> Define and manage the scoring rubric for an interview

## Overview

A score card template defines the scoring rubric (topics, weights, and rubric descriptions)
used to evaluate candidates for an [interview](/api-reference/interviews). Each interview has
at most one active template. Templates are addressed under their interview:

```
/qsi/gather/interviews/{interviewId}/score-card-template
```

<Callout type="info">
  Topic `weight` is provided as a number from `0` to `100`. You can also create a scorecard
  inline when creating an interview via the `scoreCardTopics` field on
  [`POST /interviews`](/api-reference/interviews).
</Callout>

## Get Score Card Template

**Endpoint:** `GET /qsi/gather/interviews/{interviewId}/score-card-template`

<ParamField path="interviewId" type="string" required>
  UUID of the interview.
</ParamField>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "scoreCardTemplate": {
        "id": "template-uuid",
        "interviewId": "interview-uuid",
        "topics": [
          {
            "topic": "System Design",
            "weight": 60,
            "description": "Evaluate system design ability",
            "lookingFor": ["Scalability", "Trade-off analysis"],
            "scoreDescriptions": {
              "level1": "Limited",
              "level3": "Adequate",
              "level5": "Exceptional"
            }
          }
        ],
        "version": 1,
        "isActive": true,
        "createdAt": "2026-01-15T00:00:00Z",
        "updatedAt": "2026-01-15T00:00:00Z"
      }
    },
    "meta": { "requestId": "req-uuid", "timestamp": "2026-01-15T00:00:00Z" }
  }
  ```
</CodeGroup>

## Create Score Card Template

**Endpoint:** `POST /qsi/gather/interviews/{interviewId}/score-card-template`

<ParamField path="interviewId" type="string" required>
  UUID of the interview.
</ParamField>

<ParamField name="topics" type="object[]" required>
  Scorecard topics. Each topic contains:

  * `topic` (string) — topic name
  * `weight` (number) — relative weight, `0`–`100`
  * `description` (string, optional)
  * `lookingFor` (string\[], optional)
  * `scoreDescriptions` (object, optional) — `{ level1, level3, level5 }`
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST \
      https://api.prod.qualifi.hr/qsi/gather/interviews/{interviewId}/score-card-template \
      -H "x-api-key: ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "topics": [
          {
            "topic": "System Design",
            "weight": 60,
            "lookingFor": ["Scalability"],
            "scoreDescriptions": {
              "level1": "Limited",
              "level3": "Adequate",
              "level5": "Exceptional"
            }
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      `https://api.prod.qualifi.hr/qsi/gather/interviews/${interviewId}/score-card-template`,
      {
        method: 'POST',
        headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' },
        body: JSON.stringify({
          topics: [
            { topic: 'System Design', weight: 60, lookingFor: ['Scalability'] }
          ]
        })
      }
    );
    const { data } = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.post(
        f'https://api.prod.qualifi.hr/qsi/gather/interviews/{interview_id}/score-card-template',
        headers={'x-api-key': api_key, 'Content-Type': 'application/json'},
        json={'topics': [{'topic': 'System Design', 'weight': 60, 'lookingFor': ['Scalability']}]}
    )
    data = response.json()
    ```
  </Tab>
</Tabs>

## Update Score Card Template

**Endpoint:** `PATCH /qsi/gather/interviews/{interviewId}/score-card-template`

<ParamField path="interviewId" type="string" required>
  UUID of the interview.
</ParamField>

<ParamField name="topics" type="object[]" required>
  Replacement set of scorecard topics (same shape as Create).
</ParamField>

## Delete Score Card Template

**Endpoint:** `DELETE /qsi/gather/interviews/{interviewId}/score-card-template`

<ParamField path="interviewId" type="string" required>
  UUID of the interview.
</ParamField>

## Generate Score Card Template

Generate a suggested scorecard for the interview from its questions and job description.

**Endpoint:** `POST /qsi/gather/interviews/{interviewId}/score-card-template/generate`

<ParamField path="interviewId" type="string" required>
  UUID of the interview.
</ParamField>

## Suggest Topics

Suggest scorecard topics without persisting them.

**Endpoint:** `POST /qsi/gather/score-card-templates/suggest-topics`

<Callout type="info">
  This endpoint is not interview-scoped — it returns suggested topics you can review and then
  submit via Create or Update.
</Callout>

## Related Resources

<CardGroup cols={2}>
  <Card title="Interviews" icon="file-text" href="/api-reference/interviews">
    Create interviews and attach scorecards inline
  </Card>

  <Card title="Replicas" icon="user-circle" href="/api-reference/replicas">
    Avatars for AI interviewers
  </Card>
</CardGroup>