Guides
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). 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.
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 jobslet 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;
}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.
<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.