`.
### List jobs
`GET https://api.hirehappy.io/v1/jobs`
Scope: `jobs:read`
Newest first. `q` matches the title.
**Query parameters**
| Name | Type | Description |
| --- | --- | --- |
| `status` | array of enum | Only jobs with these statuses; repeat for several, e.g. ?status=open&status=draft. one of `draft`, `open`, `closed` |
| `q` | string | Matches part of the title. |
| `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/jobs?status=open" \
-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 |
| `title` | string | |
| `description` | string | HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre. nullable |
| `location` | string | nullable |
| `employment_type` | string | nullable |
| `workplace_type` | enum | nullable, one of `onsite`, `hybrid`, `remote` |
| `status` | enum | draft (not posted), open (on the job board, taking applications) or closed. one of `draft`, `open`, `closed` |
| `hiring_manager_id` | uuid | A member of the hiring team (a user id). nullable |
| `job_board_url` | string | The job's page on the job board, where candidates apply; null unless open. nullable |
```json
{
"items": [
{
"id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"title": "Backend Engineer",
"description": "Build and run the APIs behind our product, in Python and Postgres.
",
"location": "Berlin, Germany",
"employment_type": "Full-time",
"workplace_type": "hybrid",
"status": "open",
"hiring_manager_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"job_board_url": "https://jobs.hirehappy.io/acme/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c"
}
],
"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 jobs:read; `422` a parameter or field doesn't validate.
### Create a job
`POST https://api.hirehappy.io/v1/jobs`
Scope: `jobs:write`
Create a job with the default pipeline stages and application form, to set up further in the app.
**Request body** (application/json)
| Name | Type | Description |
| --- | --- | --- |
| `title` | string | required, min 1 chars, max 200 chars |
| `description` | string | HTML, as JobResponse.description; anything else is stripped. nullable |
| `location` | string | nullable, max 200 chars |
| `employment_type` | string | nullable, max 50 chars |
| `workplace_type` | enum | nullable, one of `onsite`, `hybrid`, `remote` |
| `status` | enum | open posts it to the job board at once. one of `draft`, `open`, `closed`, default `"draft"` |
| `hiring_manager_id` | uuid | A user id of a member of the organization. nullable |
**Example request**
```bash
curl -X POST "https://api.hirehappy.io/v1/jobs" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Backend Engineer",
"description": "Build and run the APIs behind our product, in Python and Postgres.
",
"location": "Berlin, Germany",
"employment_type": "Full-time",
"workplace_type": "hybrid",
"status": "draft"
}'
```
**Response** `201`
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `created_at` | datetime | |
| `updated_at` | datetime | nullable |
| `title` | string | |
| `description` | string | HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre. nullable |
| `location` | string | nullable |
| `employment_type` | string | nullable |
| `workplace_type` | enum | nullable, one of `onsite`, `hybrid`, `remote` |
| `status` | enum | draft (not posted), open (on the job board, taking applications) or closed. one of `draft`, `open`, `closed` |
| `hiring_manager_id` | uuid | A member of the hiring team (a user id). nullable |
| `job_board_url` | string | The job's page on the job board, where candidates apply; null unless open. nullable |
```json
{
"id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"title": "Backend Engineer",
"description": "Build and run the APIs behind our product, in Python and Postgres.
",
"location": "Berlin, Germany",
"employment_type": "Full-time",
"workplace_type": "hybrid",
"status": "open",
"hiring_manager_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"job_board_url": "https://jobs.hirehappy.io/acme/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c"
}
```
**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 jobs:write; `422` a parameter or field doesn't validate.
### Retrieve a job
`GET https://api.hirehappy.io/v1/jobs/{job_id}`
Scope: `jobs:read`
**Path parameters**
| Name | Type | Description |
| --- | --- | --- |
| `job_id` | uuid | required |
**Example request**
```bash
curl "https://api.hirehappy.io/v1/jobs/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"
```
**Response** `200`
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `created_at` | datetime | |
| `updated_at` | datetime | nullable |
| `title` | string | |
| `description` | string | HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre. nullable |
| `location` | string | nullable |
| `employment_type` | string | nullable |
| `workplace_type` | enum | nullable, one of `onsite`, `hybrid`, `remote` |
| `status` | enum | draft (not posted), open (on the job board, taking applications) or closed. one of `draft`, `open`, `closed` |
| `hiring_manager_id` | uuid | A member of the hiring team (a user id). nullable |
| `job_board_url` | string | The job's page on the job board, where candidates apply; null unless open. nullable |
```json
{
"id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"title": "Backend Engineer",
"description": "Build and run the APIs behind our product, in Python and Postgres.
",
"location": "Berlin, Germany",
"employment_type": "Full-time",
"workplace_type": "hybrid",
"status": "open",
"hiring_manager_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"job_board_url": "https://jobs.hirehappy.io/acme/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c"
}
```
**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed jobs:read; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
### Update a job
`PATCH https://api.hirehappy.io/v1/jobs/{job_id}`
Scope: `jobs:write`
Change a job's details, or open (post) or close it.
**Path parameters**
| Name | Type | Description |
| --- | --- | --- |
| `job_id` | uuid | required |
**Request body** (application/json)
| Name | Type | Description |
| --- | --- | --- |
| `title` | string | nullable, min 1 chars, max 200 chars |
| `description` | string | nullable |
| `location` | string | nullable, max 200 chars |
| `employment_type` | string | nullable, max 50 chars |
| `workplace_type` | enum | nullable, one of `onsite`, `hybrid`, `remote` |
| `status` | enum | open posts it to the job board, closed takes it down. nullable, one of `draft`, `open`, `closed` |
| `hiring_manager_id` | uuid | nullable |
**Example request**
```bash
curl -X PATCH "https://api.hirehappy.io/v1/jobs/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "open"
}'
```
**Response** `200`
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `created_at` | datetime | |
| `updated_at` | datetime | nullable |
| `title` | string | |
| `description` | string | HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre. nullable |
| `location` | string | nullable |
| `employment_type` | string | nullable |
| `workplace_type` | enum | nullable, one of `onsite`, `hybrid`, `remote` |
| `status` | enum | draft (not posted), open (on the job board, taking applications) or closed. one of `draft`, `open`, `closed` |
| `hiring_manager_id` | uuid | A member of the hiring team (a user id). nullable |
| `job_board_url` | string | The job's page on the job board, where candidates apply; null unless open. nullable |
```json
{
"id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"title": "Backend Engineer",
"description": "Build and run the APIs behind our product, in Python and Postgres.
",
"location": "Berlin, Germany",
"employment_type": "Full-time",
"workplace_type": "hybrid",
"status": "open",
"hiring_manager_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"job_board_url": "https://jobs.hirehappy.io/acme/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c"
}
```
**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 jobs:write; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
---
# Job stages
> A job's hiring pipeline, from the first stage to hired. Part of the HireHappy API reference (https://hirehappy.io/docs/api).
Base URL: `https://api.hirehappy.io/v1`. Authenticate with `Authorization: Bearer `.
### List a job's stages
`GET https://api.hirehappy.io/v1/jobs/{job_id}/job-stages`
Scope: `jobs:read`
The job's pipeline, in order.
**Path parameters**
| Name | Type | Description |
| --- | --- | --- |
| `job_id` | uuid | required |
**Example request**
```bash
curl "https://api.hirehappy.io/v1/jobs/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c/job-stages" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"
```
**Response** `200` (an array)
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `job_id` | uuid | |
| `name` | string | |
| `position` | integer | 0 first. New applications start in the first stage; the last one is hired. |
| `kind` | enum | What the team does with an application there: nothing beyond moving it on (none), interview, call, assessment (work to hand in) or offer. one of `none`, `interview`, `call`, `assessment`, `offer` |
| `description` | string | A line or two on what happens in it, for the candidate. nullable |
| `is_public` | boolean | Shown to candidates on their status page as a step of their progress. |
```json
[
{
"id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
"job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"name": "Interview",
"position": 2,
"kind": "interview",
"description": "A 45-minute video call with the hiring manager.",
"is_public": true
}
]
```
**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed jobs:read; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
---
# Candidates
> The people you're considering, one per person across all your jobs, with their resumes. Part of the HireHappy API reference (https://hirehappy.io/docs/api).
Base URL: `https://api.hirehappy.io/v1`. Authenticate with `Authorization: Bearer `.
### List candidates
`GET https://api.hirehappy.io/v1/candidates`
Scope: `candidates:read`
Newest first. `q` matches part of the name or email.
**Query parameters**
| Name | Type | Description |
| --- | --- | --- |
| `q` | string | Matches part of the name or email. |
| `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/candidates?q=ribeiro" \
-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 |
| `first_name` | string | |
| `last_name` | string | |
| `email` | string | Unique within the organization. nullable |
| `phone` | string | nullable |
| `location` | string | nullable |
| `linkedin_url` | string | nullable |
| `source` | string | Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...). nullable |
| `resume_url` | string | Their resume (PDF); null when there's none. nullable |
```json
{
"items": [
{
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "ana.ribeiro@example.com",
"phone": "+49 30 901820",
"location": "Lisbon, Portugal",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral",
"resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}
],
"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 candidates:read; `422` a parameter or field doesn't validate.
### Create a candidate
`POST https://api.hirehappy.io/v1/candidates`
Scope: `candidates:write`
Add a candidate, to put forward for a job with POST /applications. 409 when another candidate has the email.
**Request body** (application/json)
| Name | Type | Description |
| --- | --- | --- |
| `first_name` | string | required, min 1 chars, max 100 chars |
| `last_name` | string | required, min 1 chars, max 100 chars |
| `email` | email | 409 when another candidate has it. nullable |
| `phone` | string | nullable, max 50 chars |
| `location` | string | nullable, max 200 chars |
| `linkedin_url` | string | nullable, max 500 chars |
| `source` | string | Where they came from, in your own words: referral, linkedin, agency, ... nullable, max 100 chars |
**Example request**
```bash
curl -X POST "https://api.hirehappy.io/v1/candidates" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "ana.ribeiro@example.com",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral"
}'
```
**Response** `201`
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `created_at` | datetime | |
| `updated_at` | datetime | nullable |
| `first_name` | string | |
| `last_name` | string | |
| `email` | string | Unique within the organization. nullable |
| `phone` | string | nullable |
| `location` | string | nullable |
| `linkedin_url` | string | nullable |
| `source` | string | Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...). nullable |
| `resume_url` | string | Their resume (PDF); null when there's none. nullable |
```json
{
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "ana.ribeiro@example.com",
"phone": "+49 30 901820",
"location": "Lisbon, Portugal",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral",
"resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}
```
**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 candidates:write; `409` when another candidate has the email; `422` a parameter or field doesn't validate.
### Retrieve a candidate
`GET https://api.hirehappy.io/v1/candidates/{candidate_id}`
Scope: `candidates:read`
**Path parameters**
| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |
**Example request**
```bash
curl "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"
```
**Response** `200`
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `created_at` | datetime | |
| `updated_at` | datetime | nullable |
| `first_name` | string | |
| `last_name` | string | |
| `email` | string | Unique within the organization. nullable |
| `phone` | string | nullable |
| `location` | string | nullable |
| `linkedin_url` | string | nullable |
| `source` | string | Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...). nullable |
| `resume_url` | string | Their resume (PDF); null when there's none. nullable |
```json
{
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "ana.ribeiro@example.com",
"phone": "+49 30 901820",
"location": "Lisbon, Portugal",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral",
"resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}
```
**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:read; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
### Update a candidate
`PATCH https://api.hirehappy.io/v1/candidates/{candidate_id}`
Scope: `candidates:write`
**Path parameters**
| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |
**Request body** (application/json)
| Name | Type | Description |
| --- | --- | --- |
| `first_name` | string | nullable, min 1 chars, max 100 chars |
| `last_name` | string | nullable, min 1 chars, max 100 chars |
| `email` | email | nullable |
| `phone` | string | nullable, max 50 chars |
| `location` | string | nullable, max 200 chars |
| `linkedin_url` | string | nullable, max 500 chars |
| `source` | string | nullable, max 100 chars |
**Example request**
```bash
curl -X PATCH "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+49 30 901820",
"location": "Lisbon, Portugal"
}'
```
**Response** `200`
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `created_at` | datetime | |
| `updated_at` | datetime | nullable |
| `first_name` | string | |
| `last_name` | string | |
| `email` | string | Unique within the organization. nullable |
| `phone` | string | nullable |
| `location` | string | nullable |
| `linkedin_url` | string | nullable |
| `source` | string | Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...). nullable |
| `resume_url` | string | Their resume (PDF); null when there's none. nullable |
```json
{
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "ana.ribeiro@example.com",
"phone": "+49 30 901820",
"location": "Lisbon, Portugal",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral",
"resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}
```
**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 candidates:write; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
### Delete a candidate
`DELETE https://api.hirehappy.io/v1/candidates/{candidate_id}`
Scope: `candidates:write`
Delete a candidate for good, with their applications and notes (a request to erase their data, say).
**Path parameters**
| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |
**Example request**
```bash
curl -X DELETE "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"
```
**Response** `204` with no body.
**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:write; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
### Upload a candidate's resume
`PUT https://api.hirehappy.io/v1/candidates/{candidate_id}/resume`
Scope: `candidates:write`
Set the candidate's resume, a PDF sent as multipart/form-data (`resume`), replacing any they had. It's searchable at once; scorecards use it from the next scoring on.
**Path parameters**
| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |
**Request body** (multipart/form-data)
| Name | Type | Description |
| --- | --- | --- |
| `resume` | string | required |
**Example request**
```bash
curl -X PUT "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f/resume" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-F "resume=@resume.pdf;type=application/pdf"
```
**Response** `200`
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `created_at` | datetime | |
| `updated_at` | datetime | nullable |
| `first_name` | string | |
| `last_name` | string | |
| `email` | string | Unique within the organization. nullable |
| `phone` | string | nullable |
| `location` | string | nullable |
| `linkedin_url` | string | nullable |
| `source` | string | Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...). nullable |
| `resume_url` | string | Their resume (PDF); null when there's none. nullable |
```json
{
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "ana.ribeiro@example.com",
"phone": "+49 30 901820",
"location": "Lisbon, Portugal",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral",
"resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}
```
**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 candidates:write; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
---
# Notes
> The hiring team's notes on candidates. Part of the HireHappy API reference (https://hirehappy.io/docs/api).
Base URL: `https://api.hirehappy.io/v1`. Authenticate with `Authorization: Bearer `.
### List a candidate's notes
`GET https://api.hirehappy.io/v1/candidates/{candidate_id}/notes`
Scope: `candidates:read`
The hiring team's notes on the candidate, newest first.
**Path parameters**
| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |
**Example request**
```bash
curl "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f/notes" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"
```
**Response** `200` (an array)
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `created_at` | datetime | |
| `candidate_id` | uuid | |
| `author_id` | uuid | The team member who wrote it; null for a note added through the API (api_key_id) or by someone who's since left. nullable |
| `api_key_id` | uuid | The API key it was added with; null once that key is revoked. nullable |
| `body` | string | |
```json
[
{
"id": "f2a4c6e8-1b3d-4f5a-9c7e-0d2f4a6c8e1b",
"created_at": "2026-10-26T09:30:00Z",
"candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"author_id": null,
"api_key_id": "5e1d9a47-2c3b-4f80-8d6e-7a9b0c1d2e3f",
"body": "Strong system design answers. Worth a second interview."
}
]
```
**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:read; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
### Add a note
`POST https://api.hirehappy.io/v1/candidates/{candidate_id}/notes`
Scope: `candidates:write`
Add a note for the hiring team; the app shows it as added through the API.
**Path parameters**
| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |
**Request body** (application/json)
| Name | Type | Description |
| --- | --- | --- |
| `body` | string | required, min 1 chars, max 20,000 chars |
**Example request**
```bash
curl -X POST "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f/notes" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"body": "Referred by Sam on the platform team; they worked together at Bolt."
}'
```
**Response** `201`
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `created_at` | datetime | |
| `candidate_id` | uuid | |
| `author_id` | uuid | The team member who wrote it; null for a note added through the API (api_key_id) or by someone who's since left. nullable |
| `api_key_id` | uuid | The API key it was added with; null once that key is revoked. nullable |
| `body` | string | |
```json
{
"id": "f2a4c6e8-1b3d-4f5a-9c7e-0d2f4a6c8e1b",
"created_at": "2026-10-26T09:30:00Z",
"candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"author_id": null,
"api_key_id": "5e1d9a47-2c3b-4f80-8d6e-7a9b0c1d2e3f",
"body": "Strong system design answers. Worth a second interview."
}
```
**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 candidates:write; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
---
# 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 `.
### 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.
---
# 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 `.
### 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.
---
# Interviews
> Interviews, calls and assessments of applications. Part of the HireHappy API reference (https://hirehappy.io/docs/api).
Base URL: `https://api.hirehappy.io/v1`. Authenticate with `Authorization: Bearer `.
### List interviews
`GET https://api.hirehappy.io/v1/interviews`
Scope: `applications:read`
The organization's interviews, calls and assessments, soonest first (an assessment by when it's due). For a calendar, e.g. the week's interviews: `kind=interview&starts_after=2026-11-02T00:00:00Z&starts_before=2026-11-09T00:00:00Z`. Times are ISO 8601 with a timezone; bounding the start leaves assessments out, as they have none.
**Query parameters**
| Name | Type | Description |
| --- | --- | --- |
| `kind` | array of enum | Only these kinds; repeat for several, e.g. ?kind=interview&kind=call. one of `interview`, `call`, `assessment` |
| `job_id` | uuid | Only interviews for this job. |
| `candidate_id` | uuid | Only this candidate's interviews. |
| `application_id` | uuid | Only this application's interviews. |
| `starts_after` | datetime | Only those starting at or after this time, with a timezone, e.g. 2026-11-02T00:00:00Z. Leaves out assessments. |
| `starts_before` | datetime | Only those starting before this time, with a timezone. Leaves out assessments. |
| `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/interviews?kind=interview&starts_after=2026-11-02T00%3A00%3A00Z&starts_before=2026-11-09T00%3A00%3A00Z" \
-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 |
| `application_id` | uuid | |
| `job_id` | uuid | |
| `candidate` | object | |
| `candidate.id` | uuid | |
| `candidate.first_name` | string | |
| `candidate.last_name` | string | |
| `candidate.email` | string | nullable |
| `stage_id` | uuid | The stage it's for; null once that stage is deleted. nullable |
| `kind` | enum | one of `interview`, `call`, `assessment` |
| `starts_at` | datetime | Interviews: when it's scheduled. Calls: when it was made. Null for assessments. nullable |
| `ends_at` | datetime | Interviews: when it ends (an hour after it starts when no length was set). Calls: when given a length. Null for assessments. nullable |
| `duration_minutes` | integer | nullable |
| `location` | string | Interviews: where, as free text: an address, a meeting link, "Phone". nullable |
| `interviewers` | array of object | Who's interviewing, or reviewing the work. |
| `interviewers.id` | uuid | |
| `interviewers.first_name` | string | |
| `interviewers.last_name` | string | |
| `interviewers.email` | string | |
| `details` | string | Interviews: what the invite tells the candidate. Calls: how it went. nullable |
| `due_at` | datetime | Assessments: when the work is due; null for no due date. nullable |
| `submitted_at` | datetime | Assessments: when the work was handed in. nullable |
```json
{
"items": [
{
"id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"application_id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
"job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"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",
"kind": "interview",
"starts_at": "2026-11-03T10:00:00Z",
"ends_at": "2026-11-03T10:45:00Z",
"duration_minutes": 45,
"location": "https://meet.google.com/abc-defg-hij",
"interviewers": [
{
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"first_name": "Maya",
"last_name": "Okafor",
"email": "maya@acme.com"
}
],
"details": "We'll talk through a system you've built. Bring questions!",
"due_at": null,
"submitted_at": null
}
],
"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.
### List an application's interviews
`GET https://api.hirehappy.io/v1/applications/{application_id}/interviews`
Scope: `applications:read`
Every round of the application, the stage it's in now and earlier ones, latest first.
**Path parameters**
| Name | Type | Description |
| --- | --- | --- |
| `application_id` | uuid | required |
**Example request**
```bash
curl "https://api.hirehappy.io/v1/applications/e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e/interviews" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"
```
**Response** `200` (an array)
| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid | |
| `created_at` | datetime | |
| `updated_at` | datetime | nullable |
| `application_id` | uuid | |
| `job_id` | uuid | |
| `candidate` | object | |
| `candidate.id` | uuid | |
| `candidate.first_name` | string | |
| `candidate.last_name` | string | |
| `candidate.email` | string | nullable |
| `stage_id` | uuid | The stage it's for; null once that stage is deleted. nullable |
| `kind` | enum | one of `interview`, `call`, `assessment` |
| `starts_at` | datetime | Interviews: when it's scheduled. Calls: when it was made. Null for assessments. nullable |
| `ends_at` | datetime | Interviews: when it ends (an hour after it starts when no length was set). Calls: when given a length. Null for assessments. nullable |
| `duration_minutes` | integer | nullable |
| `location` | string | Interviews: where, as free text: an address, a meeting link, "Phone". nullable |
| `interviewers` | array of object | Who's interviewing, or reviewing the work. |
| `interviewers.id` | uuid | |
| `interviewers.first_name` | string | |
| `interviewers.last_name` | string | |
| `interviewers.email` | string | |
| `details` | string | Interviews: what the invite tells the candidate. Calls: how it went. nullable |
| `due_at` | datetime | Assessments: when the work is due; null for no due date. nullable |
| `submitted_at` | datetime | Assessments: when the work was handed in. nullable |
```json
[
{
"id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"application_id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
"job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"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",
"kind": "interview",
"starts_at": "2026-11-03T10:00:00Z",
"ends_at": "2026-11-03T10:45:00Z",
"duration_minutes": 45,
"location": "https://meet.google.com/abc-defg-hij",
"interviewers": [
{
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"first_name": "Maya",
"last_name": "Okafor",
"email": "maya@acme.com"
}
],
"details": "We'll talk through a system you've built. Bring questions!",
"due_at": null,
"submitted_at": null
}
]
```
**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.