# Build a careers page

> List your open jobs on your own site, in your own design, with every apply button going to HireHappy.

Your HireHappy job board already lists your open jobs, branded, at `https://jobs.hirehappy.io/{your slug}`. When you want the jobs on your own site instead, in its design and its navigation, the API gives you the list, and each job's `job_board_url` takes candidates to apply.

Candidates still apply on HireHappy's job board. That way they get the application form you set up for the job, AI scoring, and a status page that tells them where they stand.

**You'll need** a key with `jobs:read`, and nothing else.

## 1. Fetch the open jobs on your server

List the jobs with `status=open` ([List jobs](https://hirehappy.io/docs/api/jobs#list-jobs)). Only open jobs take applications, and only they have a `job_board_url`.

Do this on your server or at build time, never in the browser: the key would be in the page for anyone to take, and the API refuses browser calls anyway.


```python
import os
import time
import httpx

client = httpx.Client(
    base_url="https://api.hirehappy.io/v1",
    headers={"Authorization": f"Bearer {os.environ['HIREHAPPY_API_KEY']}"},
)

_cache: tuple[float, list[dict]] | None = None

def open_jobs() -> list[dict]:
    """Every open job, refreshed at most every five minutes."""
    global _cache
    if _cache and time.monotonic() - _cache[0] < 300:
        return _cache[1]
    jobs, offset = [], 0
    while True:
        page = client.get("/jobs", params={"status": "open", "limit": 100, "offset": offset})
        page.raise_for_status()
        body = page.json()
        jobs += body["items"]
        offset += body["limit"]
        if offset >= body["total"]:
            break
    _cache = (time.monotonic(), jobs)
    return jobs
```

```js
let cache = null;

// Every open job, refreshed at most every five minutes.
export async function openJobs() {
  if (cache && Date.now() - cache.at < 5 * 60 * 1000) return cache.jobs;
  const jobs = [];
  for (let offset = 0; ;) {
    const query = new URLSearchParams({
      status: "open",
      limit: "100",
      offset: String(offset),
    });
    const response = await fetch(`https://api.hirehappy.io/v1/jobs?${query}`, {
      headers: { Authorization: `Bearer ${process.env.HIREHAPPY_API_KEY}` },
    });
    if (!response.ok) throw new Error(`HireHappy API: ${response.status}`);
    const page = await response.json();
    jobs.push(...page.items);
    offset += page.limit;
    if (offset >= page.total) break;
  }
  cache = { at: Date.now(), jobs };
  return jobs;
}
```


> [!TIP]
> Cache the list, as above, or rebuild your static site on a schedule. Jobs change a few times a day at most, and caching keeps your page fast when the API is slow or down.

## 2. Show them

Each job has what a listing needs:

| Field                                           | Use it for                             |
| ----------------------------------------------- | -------------------------------------- |
| `title`                                         | The job's name                         |
| `location`, `workplace_type`, `employment_type` | "Berlin, Germany · Hybrid · Full-time" |
| `description`                                   | The full description, as HTML          |
| `job_board_url`                                 | The **Apply** button                   |
| `created_at`                                    | "Posted 3 days ago", or sorting        |

The `description` is HTML limited to a few safe tags (paragraphs, headings, lists, links, emphasis), so you can render it as it comes. Style those tags to match your site.

```html
<article class="job">
  <h2>Backend Engineer</h2>
  <p class="meta">Berlin, Germany · Hybrid · Full-time</p>
  <div class="description"><!-- job.description --></div>
  <a class="apply" href="https://jobs.hirehappy.io/acme/7c2e4f1a-…">Apply</a>
</article>
```

`workplace_type` is `onsite`, `hybrid` or `remote`, or null when it wasn't set; the other two are free text, or null.

## 3. Group and filter

The API returns jobs newest first. Group and filter them on your side, by `location` or `workplace_type`, say. With the whole list cached, that's instant.

## When a job closes

Closing a job in HireHappy takes it off the job board, and off your list on your next refresh, as it's no longer `open`. Someone with your page open from before can still follow its apply link, but the job board no longer takes applications for it.
