# Scorecards

> Applications scored by AI against their job's rubric, with the evidence. Part of the HireHappy API reference (https://hirehappy.io/docs/api).

Base URL: `https://api.hirehappy.io/v1`. Authenticate with `Authorization: Bearer <API key>`.

### Retrieve an application's scorecard

`GET https://api.hirehappy.io/v1/applications/{application_id}/scorecard`

Scope: `applications:read`

The application scored by AI against its job's rubric, criterion by criterion. 404 until it's been scored.

**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `application_id` | uuid | required |

**Example request**

```bash
curl "https://api.hirehappy.io/v1/applications/e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e/scorecard" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
```

**Response** `200`

| Name | Type | Description |
| --- | --- | --- |
| `application_id` | uuid |  |
| `status` | enum | pending while being (re)scored. one of `pending`, `completed`, `failed` |
| `score` | integer | 0-100 against the job's rubric; null when the rubric only has knockouts. nullable |
| `knockout_result` | enum | nullable, one of `passed`, `unclear`, `failed` |
| `summary` | string | A couple of sentences on the overall fit. nullable |
| `scored_at` | datetime | nullable |
| `items` | array of object |  |
| `items.name` | string |  |
| `items.kind` | enum | scored (1-5) or knockout (passed, unclear or failed). one of `scored`, `knockout` |
| `items.weight` | integer |  |
| `items.score` | integer | 1-5 for a scored criterion: the team's override when there is one, else the AI's. nullable |
| `items.result` | enum | For a knockout criterion: the team's override when there is one, else the AI's. nullable, one of `passed`, `unclear`, `failed` |
| `items.justification` | string | nullable |
| `items.quote` | string | Verbatim evidence. nullable |
| `items.source` | enum | Where the quote is from. nullable, one of `resume`, `application`, `github` |

```json
{
  "application_id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
  "status": "completed",
  "score": 82,
  "knockout_result": "passed",
  "summary": "Five years running Python services in production and a clear record of owning APIs end to end.",
  "scored_at": "2026-10-26T09:31:12Z",
  "items": [
    {
      "name": "Python in production",
      "kind": "scored",
      "weight": 3,
      "score": 4,
      "result": null,
      "justification": "Ran FastAPI services at scale at her last two jobs.",
      "quote": "Led the migration of our billing API to FastAPI, serving 2M requests a day.",
      "source": "resume"
    }
  ]
}
```

**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed applications:read; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
