---
title: "Create scorecard"
method: POST
path: "/v3/scorecards"
tags: ["Scorecards"]
---

# Create scorecard

`POST /v3/scorecards`

## Request

- Base URL: `https://harvest.greenhouse.io`
- URL: `https://harvest.greenhouse.io/v3/scorecards`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://auth.greenhouse.io/authorize`
    - Client credentials
    - Token URL: `https://auth.greenhouse.io/token` scopes: `harvest:scorecards:create`
  - HTTP bearer

Create a scorecard for a given interview kit on a given application. `interview_kit_id`, `interviewer_id`, `interviewed_at`, `application_id`, and `submitter_id` are required; the kit must belong to the application's job. Send `status: "draft"` to stash an in-progress scorecard, or `status: "complete"` to submit immediately — submitting stamps `submitted_at` and locks the scorecard outside the organization's edit window.

## Request body

- object
  - `interview_kit_id` integer, required: Id of the interview kit this scorecard is filled out against. Must belong to the same job as the `application_id`.
  - `interviewer_id` integer, required: Id of the Greenhouse user this scorecard is assigned to (the interviewer being scored against).
  - `interviewed_at` string, date-time, required: Timestamp the interview took place, in ISO 8601. Used to compute time-to-submit and to align the scorecard with the interview slot.
  - `notes` string: Free-text "key takeaways" the interviewer is recording (pros, cons, follow-ups). Plain text; `@`-mentions are accepted and stored alongside the rendered names.
  - `candidate_rating` 'strong_no' | 'no' | 'yes' | 'strong_yes' | 'no_decision': Overall recommendation for the candidate. One of `strong_no` ("Definitely Not"), `no`, `yes`, `strong_yes`, or `no_decision`. Pass `no_decision` to submit the scorecard without picking a recommendation.
  - `private_notes` string: Free-text private notes; only users with the "see private notes" permission can read these back.
  - `status` 'draft' | 'complete': Initial lifecycle status. Send `draft` to create an in-progress scorecard, or `complete` to submit it immediately — sending `complete` also stamps `submitted_at`.
  - `public_notes` string: Free-text "note to other interviewers" shared with the rest of the hiring team.
  - `application_id` integer, required: Id of the application the scorecard belongs to. The application's job must own the supplied `interview_kit_id`.
  - `submitter_id` integer, required: Id of the user submitting the scorecard. Usually matches `interviewer_id`; set differently when an admin is filing the scorecard on the interviewer's behalf.
  - `question_answers` object[]: Answers to the interview kit's scorecard questions, written atomically with the scorecard. Each entry identifies the question by `scorecard_question_id` and supplies a `value` shaped by the question's `answer_type`. Questions omitted here are left unanswered.
    - `scorecard_question_id` integer, required: Id of the scorecard question being answered. Must belong to the scorecard's interview kit (`GET /v3/scorecard_questions?interview_kit_ids=...`). Questions with `answer_type: "instruction"` are display-only and rejected.
    - `value` union, required: The answer, shaped by the question's `answer_type`: string for `text`, boolean for `yes_no`, option id for `single_select`, array of option ids for `multi_select` (treated as a set — the current selection is replaced; only active options are selectable). Select values are option ids only; option names are not accepted (unlike custom field values). Required: send an explicit `null` to clear an answer. A value whose type does not match the question's `answer_type` is rejected. Writing a `text` value stores plain text — any rich-text formatting previously entered in the Greenhouse UI is cleared.
      - string: Answer for a `text` question. Stored as plain text.
      - boolean: Answer for a `yes_no` question.
      - integer: Id of the selected option for a `single_select` question. Must belong to the question.
      - integer[]: Ids of the selected options for a `multi_select` question. Replaces the current selection as a set; each id must belong to the question.
  - `candidate_attributes` object[]: Ratings for the job's candidate attributes, written atomically with the scorecard. Each entry identifies the attribute by `job_candidate_attribute_id`. Attributes omitted here are left unrated.
    - `job_candidate_attribute_id` integer, required: Id of the job candidate attribute being rated. Must belong to the application's job (`GET /v3/job_candidate_attributes?job_ids=...`).
    - `value` 'definitely_not' | 'no' | 'yes' | 'strong_yes' | 'mixed' | 'no_decision' | 'null', nullable: Rating for this attribute. One of `definitely_not`, `no`, `yes`, `strong_yes`, `mixed`, or `no_decision`. Send `null` to clear; a cleared rating reads back as `no_decision`. Omitting the key leaves the current rating untouched (a note-only update); each entry must include `value` or `note`.
    - `note` string, nullable: Free-text note explaining the rating. Send `null` to clear.

## Response `201`

Successful

- object
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `interview_kit_id` integer: Id of the interview kit this scorecard was filled out against. The kit determines the questions, focus attributes, and rating scale on the scorecard. The kit also identifies which interview slot on the job's interview plan produced this scorecard.
  - `interviewer_id` integer: Id of the Greenhouse user who participated in the interview and to whom this scorecard is assigned. Each interviewer on a multi-interviewer interview gets their own scorecard.
  - `interviewed_at` string, date-time, nullable: Timestamp the interview took place, in ISO 8601. Mirrors the underlying interview's scheduled time and is set when the scorecard is created (manual scorecards may set this independently).
  - `notes` string, nullable: Free-text "key takeaways" the interviewer recorded on the scorecard (pros, cons, follow-ups). Plain text with `@`-mentions rendered as user names; use `notes_with_tags` for the version where mentions are tagged for downstream parsing.
  - `notes_with_tags` string, nullable: `notes` with `@`-mentions rendered as embedded user tags (e.g. `@[User Name](user:123)`) instead of plain user names, for partners that need to resolve mentioned users.
  - `submitter_id` integer: Id of the Greenhouse user who actually submitted the scorecard. Usually the same as `interviewer_id`, but differs when an admin submits a scorecard on another interviewer's behalf.
  - `candidate_rating` string: Interviewer's overall recommendation on whether the candidate passed the interview. One of `strong_no` ("Definitely Not" in the UI), `no`, `yes`, `strong_yes`, or `no_decision`. `no_decision` is recorded when the interviewer submitted the scorecard without choosing a recommendation.
  - `private_notes` string, nullable: Free-text private notes visible only to users with the "see private notes" permission. Plain text with `@`-mentions rendered as user names; use `private_notes_with_tags` for the tagged version.
  - `private_notes_with_tags` string, nullable: `private_notes` with `@`-mentions rendered as embedded user tags instead of plain user names.
  - `status` 'draft' | 'complete': Lifecycle status of the scorecard. `complete` is submitted feedback (and `submitted_at` is set). `draft` is an autosaved working copy owned by the user who opened the form; it is not shown as feedback and does not mean feedback is owed. Only complete scorecards count toward interview completion and downstream analysis.
  - `public_notes` string, nullable: Free-text "note to other interviewers" the interviewer leaves for the rest of the hiring team. Plain text with `@`-mentions rendered as user names; use `public_notes_with_tags` for the tagged version.
  - `public_notes_with_tags` string, nullable: `public_notes` with `@`-mentions rendered as embedded user tags instead of plain user names.
  - `application_id` integer: Id of the application this scorecard belongs to. Use it to look up the candidate via the applications endpoint.
  - `submitted_at` string, date-time, nullable: Timestamp the scorecard was submitted (moved from `draft` to `complete`), in ISO 8601. `null` while `status` is `draft`. The delta between `interviewed_at` and `submitted_at` is a common "time to submit scorecard" measure.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Content

---

[API](https://skmtc.dev/greenhouse/apis/harvest-api.md) - [All operations](https://skmtc.dev/greenhouse/apis/harvest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/greenhouse/apis/harvest-api/revisions/822822e3f771?raw)