# Jobs

> Your jobs: posting them on the job board, closing them, and their details. 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 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": "<p>Build and run the APIs behind our product, in Python and Postgres.</p>",
      "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": "<p>Build and run the APIs behind our product, in Python and Postgres.</p>",
    "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": "<p>Build and run the APIs behind our product, in Python and Postgres.</p>",
  "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": "<p>Build and run the APIs behind our product, in Python and Postgres.</p>",
  "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": "<p>Build and run the APIs behind our product, in Python and Postgres.</p>",
  "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.
