# Applications

> A candidate's candidacy for one job: its stage, status and AI score. Part of the HireHappy API reference (https://hirehappy.io/docs/api).

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

### List applications

`GET https://api.hirehappy.io/v1/applications`

Scope: `applications:read`

Newest first, or best match first with `sort=score` (failed knockouts and the unscored last). `q` searches the candidate's name, email and resume (every word has to match).

**Query parameters**

| Name | Type | Description |
| --- | --- | --- |
| `job_id` | uuid | Only applications to this job. |
| `candidate_id` | uuid | Only this candidate's applications. |
| `stage_id` | uuid | Only applications in this stage of their job. |
| `status` | array of enum | Only applications with these statuses; repeat for several, e.g. ?status=active&status=hired. one of `active`, `rejected`, `hired`, `withdrawn` |
| `q` | string | Every word must match the candidate's name, email or resume, e.g. react berlin. |
| `sort` | enum | newest first, or score: best match first, failed knockouts and the unscored last. one of `newest`, `score`, default `"newest"` |
| `limit` | integer | How many to return. min 1, max 100, default `50` |
| `offset` | integer | How many to skip. See [Pagination](https://hirehappy.io/docs/pagination). default `0` |

**Example request**

```bash
curl "https://api.hirehappy.io/v1/applications?job_id=7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c&status=active&sort=score" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
```

**Response** `200` (a page: `items`, `total`, `limit`, `offset`)

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `job_id` | uuid |  |
| `candidate_id` | uuid |  |
| `candidate` | object |  |
| `candidate.id` | uuid |  |
| `candidate.first_name` | string |  |
| `candidate.last_name` | string |  |
| `candidate.email` | string | nullable |
| `stage_id` | uuid | A stage of the job (GET /jobs/{job_id}/job-stages). |
| `status` | enum | active (in the pipeline), rejected, hired or withdrawn. one of `active`, `rejected`, `hired`, `withdrawn` |
| `rejection_reason` | string | Kept with a rejection; internal, never shown to the candidate. nullable |
| `withdrawal_reason` | string | The candidate's own words on withdrawing, if any. nullable |
| `reapplied_at` | datetime | Set when a rejected or withdrawn candidate applied again, until its status next changes. nullable |
| `status_url` | string | The candidate's private status page; null for candidates who didn't apply through the job board. nullable |
| `scorecard` | object | Null until scoring has been asked for (it is, on its own, when the job has a rubric). nullable |
| `scorecard.status` | enum | pending while being (re)scored. one of `pending`, `completed`, `failed` |
| `scorecard.score` | integer | 0-100 against the job's rubric; null until scored, or when the rubric only has knockouts. nullable |
| `scorecard.knockout_result` | enum | The worst of its knockout criteria: failed, else unclear, else passed; null without any. nullable, one of `passed`, `unclear`, `failed` |
| `scorecard.scored_at` | datetime | nullable |

```json
{
  "items": [
    {
      "id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
      "created_at": "2026-10-26T09:30:00Z",
      "updated_at": "2026-10-27T14:05:00Z",
      "job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
      "candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
      "candidate": {
        "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
        "first_name": "Ana",
        "last_name": "Ribeiro",
        "email": "ana.ribeiro@example.com"
      },
      "stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
      "status": "active",
      "rejection_reason": null,
      "withdrawal_reason": null,
      "reapplied_at": null,
      "status_url": "https://jobs.hirehappy.io/acme/status/Zk3pQ9vX2mL7",
      "scorecard": {
        "status": "completed",
        "score": 82,
        "knockout_result": "passed",
        "scored_at": "2026-10-26T09:31:12Z"
      }
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

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

### Create an application

`POST https://api.hirehappy.io/v1/applications`

Scope: `applications:write`

Put a candidate forward for a job, in its first stage unless `stage_id` says otherwise. Scored in the background when the job has a rubric. 409 when they already have an application for it.

**Request body** (application/json)

| Name | Type | Description |
| --- | --- | --- |
| `job_id` | uuid | required |
| `candidate_id` | uuid | required |
| `stage_id` | uuid | A stage of the job; the first one when left out. nullable |

**Example request**

```bash
curl -X POST "https://api.hirehappy.io/v1/applications" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
    "candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f"
  }'
```

**Response** `201`

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `job_id` | uuid |  |
| `candidate_id` | uuid |  |
| `candidate` | object |  |
| `candidate.id` | uuid |  |
| `candidate.first_name` | string |  |
| `candidate.last_name` | string |  |
| `candidate.email` | string | nullable |
| `stage_id` | uuid | A stage of the job (GET /jobs/{job_id}/job-stages). |
| `status` | enum | active (in the pipeline), rejected, hired or withdrawn. one of `active`, `rejected`, `hired`, `withdrawn` |
| `rejection_reason` | string | Kept with a rejection; internal, never shown to the candidate. nullable |
| `withdrawal_reason` | string | The candidate's own words on withdrawing, if any. nullable |
| `reapplied_at` | datetime | Set when a rejected or withdrawn candidate applied again, until its status next changes. nullable |
| `status_url` | string | The candidate's private status page; null for candidates who didn't apply through the job board. nullable |
| `scorecard` | object | Null until scoring has been asked for (it is, on its own, when the job has a rubric). nullable |
| `scorecard.status` | enum | pending while being (re)scored. one of `pending`, `completed`, `failed` |
| `scorecard.score` | integer | 0-100 against the job's rubric; null until scored, or when the rubric only has knockouts. nullable |
| `scorecard.knockout_result` | enum | The worst of its knockout criteria: failed, else unclear, else passed; null without any. nullable, one of `passed`, `unclear`, `failed` |
| `scorecard.scored_at` | datetime | nullable |

```json
{
  "id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
  "candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "candidate": {
    "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
    "first_name": "Ana",
    "last_name": "Ribeiro",
    "email": "ana.ribeiro@example.com"
  },
  "stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
  "status": "active",
  "rejection_reason": null,
  "withdrawal_reason": null,
  "reapplied_at": null,
  "status_url": "https://jobs.hirehappy.io/acme/status/Zk3pQ9vX2mL7",
  "scorecard": {
    "status": "completed",
    "score": 82,
    "knockout_result": "passed",
    "scored_at": "2026-10-26T09:31:12Z"
  }
}
```

**Errors**: `400` a value is out of place; `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed applications:write; `409` when they already have an application for it; `422` a parameter or field doesn't validate.

### Retrieve an application

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

Scope: `applications:read`



**Path parameters**

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

**Example request**

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

**Response** `200`

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `job_id` | uuid |  |
| `candidate_id` | uuid |  |
| `candidate` | object |  |
| `candidate.id` | uuid |  |
| `candidate.first_name` | string |  |
| `candidate.last_name` | string |  |
| `candidate.email` | string | nullable |
| `stage_id` | uuid | A stage of the job (GET /jobs/{job_id}/job-stages). |
| `status` | enum | active (in the pipeline), rejected, hired or withdrawn. one of `active`, `rejected`, `hired`, `withdrawn` |
| `rejection_reason` | string | Kept with a rejection; internal, never shown to the candidate. nullable |
| `withdrawal_reason` | string | The candidate's own words on withdrawing, if any. nullable |
| `reapplied_at` | datetime | Set when a rejected or withdrawn candidate applied again, until its status next changes. nullable |
| `status_url` | string | The candidate's private status page; null for candidates who didn't apply through the job board. nullable |
| `scorecard` | object | Null until scoring has been asked for (it is, on its own, when the job has a rubric). nullable |
| `scorecard.status` | enum | pending while being (re)scored. one of `pending`, `completed`, `failed` |
| `scorecard.score` | integer | 0-100 against the job's rubric; null until scored, or when the rubric only has knockouts. nullable |
| `scorecard.knockout_result` | enum | The worst of its knockout criteria: failed, else unclear, else passed; null without any. nullable, one of `passed`, `unclear`, `failed` |
| `scorecard.scored_at` | datetime | nullable |

```json
{
  "id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
  "candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "candidate": {
    "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
    "first_name": "Ana",
    "last_name": "Ribeiro",
    "email": "ana.ribeiro@example.com"
  },
  "stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
  "status": "active",
  "rejection_reason": null,
  "withdrawal_reason": null,
  "reapplied_at": null,
  "status_url": "https://jobs.hirehappy.io/acme/status/Zk3pQ9vX2mL7",
  "scorecard": {
    "status": "completed",
    "score": 82,
    "knockout_result": "passed",
    "scored_at": "2026-10-26T09:31:12Z"
  }
}
```

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

### Update an application

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

Scope: `applications:write`

Move it to another stage, or change its status: reject, hire (moves it to the last stage, and starts onboarding), or back to active. As in the app, a candidate who applied through the job board is emailed on moving on to a later public stage and on being hired; on being rejected only when `notify_candidate` asks.

**Path parameters**

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

**Request body** (application/json)

| Name | Type | Description |
| --- | --- | --- |
| `stage_id` | uuid | Move it to another stage of its job, at the bottom of it. The last stage marks it hired. nullable |
| `status` | enum | rejected, hired (moves it to the last stage and starts onboarding) or back to active. nullable, one of `active`, `rejected`, `hired`, `withdrawn` |
| `rejection_reason` | string | Kept with a rejection; internal, never shown to the candidate. nullable, max 5,000 chars |
| `notify_candidate` | boolean | With status "rejected": email the candidate their default rejection email, now. Other emails (moved on to a later public stage, hired) go to candidates who applied through the job board on their own. default `false` |

**Example request**

```bash
curl -X PATCH "https://api.hirehappy.io/v1/applications/e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c"
  }'
```

**Response** `200`

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `job_id` | uuid |  |
| `candidate_id` | uuid |  |
| `candidate` | object |  |
| `candidate.id` | uuid |  |
| `candidate.first_name` | string |  |
| `candidate.last_name` | string |  |
| `candidate.email` | string | nullable |
| `stage_id` | uuid | A stage of the job (GET /jobs/{job_id}/job-stages). |
| `status` | enum | active (in the pipeline), rejected, hired or withdrawn. one of `active`, `rejected`, `hired`, `withdrawn` |
| `rejection_reason` | string | Kept with a rejection; internal, never shown to the candidate. nullable |
| `withdrawal_reason` | string | The candidate's own words on withdrawing, if any. nullable |
| `reapplied_at` | datetime | Set when a rejected or withdrawn candidate applied again, until its status next changes. nullable |
| `status_url` | string | The candidate's private status page; null for candidates who didn't apply through the job board. nullable |
| `scorecard` | object | Null until scoring has been asked for (it is, on its own, when the job has a rubric). nullable |
| `scorecard.status` | enum | pending while being (re)scored. one of `pending`, `completed`, `failed` |
| `scorecard.score` | integer | 0-100 against the job's rubric; null until scored, or when the rubric only has knockouts. nullable |
| `scorecard.knockout_result` | enum | The worst of its knockout criteria: failed, else unclear, else passed; null without any. nullable, one of `passed`, `unclear`, `failed` |
| `scorecard.scored_at` | datetime | nullable |

```json
{
  "id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
  "candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "candidate": {
    "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
    "first_name": "Ana",
    "last_name": "Ribeiro",
    "email": "ana.ribeiro@example.com"
  },
  "stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
  "status": "active",
  "rejection_reason": null,
  "withdrawal_reason": null,
  "reapplied_at": null,
  "status_url": "https://jobs.hirehappy.io/acme/status/Zk3pQ9vX2mL7",
  "scorecard": {
    "status": "completed",
    "score": 82,
    "knockout_result": "passed",
    "scored_at": "2026-10-26T09:31:12Z"
  }
}
```

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