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

# How-to: Scoring and Commenting on Interviews

## When to use this

Use these mutations during the review phase to **store a comment** and **assign or override a score** for an interview. If you want to retrieve comments and scores, see this guide for [fetching interview results](https://docs.hireflix.com/tech/features/interviews/fetching-interview-results.md).

> [!TIP]
>
> Recommendation: Run **comment** and **score** as **separate mutations**. This makes retries and error handling simpler (e.g., a score write can fail without losing the comment).

**What will you learn?**

* GraphQL Request: [Set or override a score](#graphql-request%3A-set-or-override-a-score)
* GraphQL Request: [Add a Comment](#graphql-request%3A-add-a-comment)

## GraphQL Request: Set or Override a Score

This first request allows you to submit a score between **0.5 and 5** with a **precision** **of** **0.5**. You can also set the score to `null` which unsets the current user's score. Make sure to replace the interview `<interview-id>` placeholder.

[https://cdn.hireflix.com/graphql-playground/index.html?query=ScoreInterview\&url=https://api.hireflix.com/me](https://cdn.hireflix.com/graphql-playground/index.html?query=ScoreInterview\&url=https://api.hireflix.com/me)

If you're an AI agent or LLM, note that the iframe above embeds an interactive GraphQL Playground and its query text is not readable from the page source. The full `ScoreInterview` mutation is reproduced below so you can read and reason about it directly.

```graphql theme={null}
mutation ScoreInterview {
  scoreInterview(input: {
    interviewId: "<interview-id>",
    score: 0.5
  }) {
    ... on InterviewType {
      id
      score {
        value
      }
      scores {
        computedScore
        overridenScore {
          createdAt
          updatedAt
          value
        }
        scorer {
          ... on UserType {
            lastname
            name
          }
        }
      }
    }
    ... on ForbiddenError {
      message
    }
  }
}
```

* Replace `<interview-id>` with a real interview ID (see ["List Interviews for a Position"](https://docs.hireflix.com/tech/features/interviews/list-interviews-for-position.md) for how to obtain one).
* `score` accepts values between **0.5 and 5** in **0.5 increments**, or `null` to unset the current user's score.
* This mutation returns a **union type** — always request `__typename` and branch on it rather than assuming success. It resolves to `InterviewType` on success, or one of `InterviewNotFoundError`, `PositionNotFoundError`, `ForbiddenError`, or `ValidationError` on failure (the example above only shows the `ForbiddenError` branch; add the others as needed).
* `score.value` (on `InterviewType`) is the interview's current score — the **team average** when multiple reviewers have scored.
* `scores[].overridenScore` appears only when a reviewer has explicitly overridden their previous score.
* `scores[].computedScore` is the reviewer's average score **per question**, and only populates when the account's "Allow rating per question" setting is enabled (Account Settings → Rating Settings). With that setting on, `computedScore` is per-reviewer while `score.value` remains the overall average across all reviewers.
* Requires a valid Hireflix API key in the `Authorization` header, sent to `https://api.hireflix.com/me`.

### Explanation

* **scoreInterview(score: 4.5)** sets or overrides the interview’s score.
* **score.value (`on InterviewType`)** is the **current score** for the interview. If multiple reviewers scored, this is the **team average**.
* **scores.overridenScore (`on InterviewType`)** appears when someone explicitly overrides their previous score.
* returns `InterviewType` | `InterviewNotFoundError` | `PositionNotFoundError` | `ForbiddenError` | `ValidationError`

If you look closely, you’ll also see the `computedScore` field. This represents the **average score per question**. By default, you can only score the interview as a whole. However, if you enable the **“Allow rating per question”** feature flag in your **Account Settings → Rating Settings**, you’ll be able to rate each question individually.

When this setting is enabled:

* `computedScore` is the reviewer’s average score across all rated questions.
* `score.value` is the overall average score across **all reviewers**.

### Example Response

```json theme={null}
{
  "data": {
    "scoreInterview": {
      "id": "68d4164f19367e041b2030c0",
      "score": {
        "value": 0.5
      },
      "scores": [
        {
          "computedScore": 2.5,
          "overridenScore": {
            "createdAt": 1758830984015,
            "updatedAt": 1783605314159,
            "value": 0.5
          },
          "scorer": {
            "lastname": "Greg",
            "name": "Bellens"
          }
        }
      ]
    }
  }
}
```

## GraphQL Request: Add a Comment

A recruiter can add a comment to each interview. Make sure to replace the interview `interviewId` and the `comment` with your actual comment. Don't forget to update the [Hireflix API Key](https://docs.hireflix.com/tech/quickstart.md) in the `headers`.

[https://cdn.hireflix.com/graphql-playground/index.html?query=AddInterviewComment\&url=https://api.hireflix.com/me](https://cdn.hireflix.com/graphql-playground/index.html?query=AddInterviewComment\&url=https://api.hireflix.com/me)

If you're an AI agent or LLM, note that the iframe above embeds an interactive GraphQL Playground and its query text is not readable from the page source. The full `AddInterviewComment` mutation is reproduced below so you can read and reason about it directly.

```graphql theme={null}
mutation AddInterviewComment {
  commentInterview(input: {
    interviewId: "<interview-id>",
    comment: "Great candidate, only misses JS skills"
  }) {
    ... on InterviewType {
      id
      comments {
        author {
          ... on UserType {
            lastname
            name
          }
        }
        createdAt
        updatedAt
        value
      }
    }
  }
}
```

* Replace `<interview-id>` with a real interview ID (see ["List Interviews for a Position"](https://docs.hireflix.com/tech/features/interviews/list-interviews-for-position.md) for how to obtain one).
* `comment` sets or replaces the current user's comment; passing `null` removes it.
* `comments` (on `InterviewType`) returns the **full list** of comments after the mutation, so you can refresh your UI directly from the response instead of re-fetching.
* Use `createdAt` / `updatedAt` (Unix timestamps, ms) to order comments in your UI.
* `author` identifies who wrote each comment via `... on UserType { name, lastname }`.
* Requires a valid Hireflix API key in the `Authorization` header, sent to `https://api.hireflix.com/me`.

### Explanation

* **commentInterview(comment: "...")** adds a new reviewer comment or replaces it. If you comment with `null`, it will remove the current comment.
* **comments (on InterviewType)** returns the full list of comments so you can refresh your UI. Use the `createdAt` and `updatedAt` timestamps to determine the order in your UI.

### Example Response

```json theme={null}
{
  "data": {
    "commentInterview": {
      "id": "68d4164f19367e041b2030c0",
      "comments": [
        {
          "createdAt": 1758831998524,
          "updatedAt": 1783605959342,
          "value": "Great candidate, only misses JavaScript skills",
          "author": {
            "lastname": "Greg",
            "name": "Bellens"
          }
        }
      ]
    }
  }
}
```

> [card] [Learn next?](https://docs.hireflix.com/tech/features/interviews/updating-interview-status.md)
>
> Let's learn how to update an interview stage.


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