Docs

Search the docs

Guides, sections and API endpoints

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 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:

FieldUse it for
titleThe job's name
location, workplace_type, employment_type"Berlin, Germany · Hybrid · Full-time"
descriptionThe full description, as HTML
job_board_urlThe 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.