# HireHappy > HireHappy is an applicant tracking system. Its developer API (REST, JSON, API keys) gives your own systems an organization's jobs, candidates, applications, AI scorecards and interviews; its MCP server connects AI apps like Claude and ChatGPT as a member of the hiring team. - API base URL: https://api.hirehappy.io/v1 - Authentication: `Authorization: Bearer hh_sk_...`, a key made in the app under Settings → API keys - OpenAPI schema: https://hirehappy.io/docs/openapi.json - Everything below in one file: https://hirehappy.io/llms-full.txt ## Get started - [Quickstart](https://hirehappy.io/docs/quickstart.md): Make an API key, make your first call, and put a candidate forward for a job, in about five minutes. - [Authentication](https://hirehappy.io/docs/authentication.md): API keys, what each scope allows, expiry and revoking, and keeping keys safe. - [Conventions](https://hirehappy.io/docs/conventions.md): How every endpoint behaves - IDs, times, partial updates, filtering, files, the emails calls can send, and retrying. - [Pagination](https://hirehappy.io/docs/pagination.md): Page through jobs, candidates, applications and interviews with limit and offset. - [Errors](https://hirehappy.io/docs/errors.md): The one shape every error has, the types to branch on, and how to handle each. - [Versioning](https://hirehappy.io/docs/versioning.md): What can change within /v1 and what never will, and how you'll hear about changes. ## Guides - [Build a careers page](https://hirehappy.io/docs/careers-site.md): List your open jobs on your own site, in your own design, with every apply button going to HireHappy. - [Add candidates from anywhere](https://hirehappy.io/docs/add-candidates.md): Bring candidates in from referral forms, sourcing tools and events, with their resumes, put them forward for jobs and get them scored. - [Sync hires to your HR system](https://hirehappy.io/docs/sync-hires.md): Create new hires in your HRIS or payroll as soon as they're hired in HireHappy, and hire from your own systems. - [Show an interview calendar](https://hirehappy.io/docs/interview-calendar.md): Put the week's interviews on a dashboard, a meeting-room screen or a team channel, with who's interviewing whom and where. ## AI - [Connect AI apps (MCP)](https://hirehappy.io/docs/mcp.md): Add HireHappy to Claude, ChatGPT, Cursor or any MCP client, so it can work with your jobs and candidates as a member of your hiring team. - [Docs for AI coding tools](https://hirehappy.io/docs/ai-tools.md): Give Claude Code, Cursor, Copilot and other AI tools these docs as plain Markdown, and the OpenAPI schema for generating clients. ## Resources - [Changelog](https://hirehappy.io/docs/changelog.md): Every change to the HireHappy API and MCP server, newest first. ## API reference - [Organizations](https://hirehappy.io/docs/api/organizations.md): The organization the API key belongs to. Retrieve your organization. - [API keys](https://hirehappy.io/docs/api/api-keys.md): The API key itself: what it may do. Retrieve the api key. - [Jobs](https://hirehappy.io/docs/api/jobs.md): Your jobs: posting them on the job board, closing them, and their details. List jobs, create a job, retrieve a job, update a job. - [Job stages](https://hirehappy.io/docs/api/job-stages.md): A job's hiring pipeline, from the first stage to hired. List a job's stages. - [Candidates](https://hirehappy.io/docs/api/candidates.md): The people you're considering, one per person across all your jobs, with their resumes. List candidates, create a candidate, retrieve a candidate, update a candidate, delete a candidate, upload a candidate's resume. - [Notes](https://hirehappy.io/docs/api/notes.md): The hiring team's notes on candidates. List a candidate's notes, add a note. - [Applications](https://hirehappy.io/docs/api/applications.md): A candidate's candidacy for one job: its stage, status and AI score. List applications, create an application, retrieve an application, update an application. - [Scorecards](https://hirehappy.io/docs/api/scorecards.md): Applications scored by AI against their job's rubric, with the evidence. Retrieve an application's scorecard. - [Interviews](https://hirehappy.io/docs/api/interviews.md): Interviews, calls and assessments of applications. List interviews, list an application's interviews. --- # Quickstart > Make an API key, make your first call, and put a candidate forward for a job, in about five minutes. The HireHappy API is a REST API over your organization's hiring: jobs, candidates, applications, AI scorecards and interviews. It takes and returns JSON, and authenticates with an API key. ## 1. Make an API key Keys are made in the app by an **owner or admin** of your organization: 1. Open [Settings → API keys](https://app.hirehappy.io/settings#api-keys) and choose **New key**. 2. Name it after what will use it, like "Careers site" or "HRIS sync". 3. Pick what it may do with jobs, candidates and applications: nothing, read, or read and write. Give it only what it needs; you can make another key later. 4. Pick when it expires, or never. The key (`hh_sk_…`) is shown **once**. Copy it somewhere safe, like your password manager or your server's secrets. > [!WARNING] > A key acts for your whole organization. Keep it on your servers: never in a web page, a mobile app or a public repository. The API refuses calls from browsers for this reason. ## 2. Make your first call Put the key in an environment variable, so it stays out of your code: ```bash export HIREHAPPY_API_KEY="hh_sk_..." ``` Then ask which organization the key is for. Any key may do this, so it's a good first check: ```bash curl https://api.hirehappy.io/v1/organizations/self \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" ``` ```python import os import httpx client = httpx.Client( base_url="https://api.hirehappy.io/v1", headers={"Authorization": f"Bearer {os.environ['HIREHAPPY_API_KEY']}"}, ) response = client.get("/organizations/self") response.raise_for_status() print(response.json()) ``` ```js const response = await fetch("https://api.hirehappy.io/v1/organizations/self", { headers: { Authorization: `Bearer ${process.env.HIREHAPPY_API_KEY}` }, }); if (!response.ok) throw new Error(`HireHappy API: ${response.status}`); console.log(await response.json()); ``` ```json { "id": "0b6f3c2e-8a41-4d7e-9c55-3e2f1a7b9d10", "name": "Acme", "slug": "acme", "website": "https://acme.com", "timezone": "Europe/Berlin" } ``` A `401` means the key is wrong, expired or revoked; check you copied all of it. See [Errors](https://hirehappy.io/docs/errors) for the rest. ## 3. Put a candidate forward Now something real: add a candidate and put them forward for one of your open jobs. This needs a key with **read and write** on candidates and applications, and **read** on jobs. First find the job, from your open ones ([List jobs](https://hirehappy.io/docs/api/jobs#list-jobs)): ```bash curl "https://api.hirehappy.io/v1/jobs?status=open" \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" ``` ```python jobs = client.get("/jobs", params={"status": "open"}).raise_for_status().json() job_id = jobs["items"][0]["id"] ``` ```js const jobs = await fetch("https://api.hirehappy.io/v1/jobs?status=open", { headers: { Authorization: `Bearer ${process.env.HIREHAPPY_API_KEY}` }, }).then((r) => r.json()); const jobId = jobs.items[0].id; ``` Add the candidate ([Create a candidate](https://hirehappy.io/docs/api/candidates#create-candidate)): ```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", "source": "referral" }' ``` ```python candidate = client.post( "/candidates", json={ "first_name": "Ana", "last_name": "Ribeiro", "email": "ana.ribeiro@example.com", "source": "referral", }, ).raise_for_status().json() ``` ```js const candidate = await fetch("https://api.hirehappy.io/v1/candidates", { method: "POST", headers: { Authorization: `Bearer ${process.env.HIREHAPPY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ first_name: "Ana", last_name: "Ribeiro", email: "ana.ribeiro@example.com", source: "referral", }), }).then((r) => r.json()); ``` And put them forward for the job ([Create an application](https://hirehappy.io/docs/api/applications#create-application)). They land in the job's first stage, and if the job has a rubric, AI scores the application in the background: ```bash curl -X POST https://api.hirehappy.io/v1/applications \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"job_id": "JOB_ID", "candidate_id": "CANDIDATE_ID"}' ``` ```python application = client.post( "/applications", json={"job_id": job_id, "candidate_id": candidate["id"]}, ).raise_for_status().json() print(application["stage_id"], application["scorecard"]) ``` ```js const application = await fetch("https://api.hirehappy.io/v1/applications", { method: "POST", headers: { Authorization: `Bearer ${process.env.HIREHAPPY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ job_id: jobId, candidate_id: candidate.id }), }).then((r) => r.json()); ``` Open the job in HireHappy and Ana is there, in the first stage, with a scorecard on its way. ## Next steps - [Authentication](https://hirehappy.io/docs/authentication): scopes, expiry and keeping keys safe. - [Conventions](https://hirehappy.io/docs/conventions): IDs, times, partial updates and what happens behind each call. - [Add candidates from anywhere](https://hirehappy.io/docs/add-candidates): resumes, duplicates and scoring, the full version of step 3. - [API reference](https://hirehappy.io/docs/api): every endpoint. --- # Authentication > API keys, what each scope allows, expiry and revoking, and keeping keys safe. Every request carries an API key in the `Authorization` header, as a bearer token: ```http GET /v1/jobs HTTP/1.1 Host: api.hirehappy.io Authorization: Bearer hh_sk_... ``` Requests without one get `401` with type `api_key_required`; with a wrong, expired or revoked one, `401` with `invalid_api_key`. Both carry a `WWW-Authenticate: Bearer` header, as [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750) has it. ## API keys An **owner or admin** makes keys in the app, under [Settings → API keys](https://app.hirehappy.io/settings#api-keys). - **A key belongs to the organization**, not to whoever made it. It acts for the organization, so it keeps working when its maker leaves. Notes it adds show in the app as added through the API. - **The key is shown once**, when it's made. HireHappy keeps only a hash of it, so a lost key can't be recovered: make a new one. - **Keys start with `hh_sk_`**, which secret scanners (and people) can recognise. Keep that prefix in mind for your own scanning rules. - **Name keys after what uses them** ("Careers site", "Workday sync"), so you know which to revoke. The app shows each key's last characters and when it was last used. ## Scopes When you make a key, you choose what it may do with each kind of thing. Each choice is a scope: | Scope | Allows | | -------------------- | ------------------------------------------------------------------------------------ | | `jobs:read` | Listing and reading jobs and their pipeline stages | | `jobs:write` | Creating jobs, changing them, opening and closing them | | `candidates:read` | Listing and reading candidates and the team's notes on them | | `candidates:write` | Creating, changing and deleting candidates, uploading resumes, adding notes | | `applications:read` | Listing and reading applications, their AI scorecards and interviews | | `applications:write` | Putting candidates forward, moving applications between stages, rejecting and hiring | Write always comes with read. Each endpoint in the [API reference](https://hirehappy.io/docs/api) shows the scope it needs. Two endpoints need none, so any valid key may call them: [Retrieve your organization](https://hirehappy.io/docs/api/organizations#get-organization) and [Retrieve the API key](https://hirehappy.io/docs/api/api-keys#get-api-key), which tells you what the key may do: ```json { "id": "5e1d9a47-2c3b-4f80-8d6e-7a9b0c1d2e3f", "name": "Careers site", "scopes": ["jobs:read"], "expires_at": null } ``` A key without the scope an endpoint needs gets `403` with type `insufficient_scope`. A key's scopes can't be changed once it's made; make a new key with the ones you need, and revoke the old one. > [!TIP] > Give each integration its own key with the fewest scopes it needs. A careers site needs only `jobs:read`; a reporting job, only the read scopes. ## Expiry and revoking Keys expire after 30 days, 90 days or a year, or never; you choose when you make the key. From the moment a key expires or is revoked, requests with it get `401`. To revoke a key, delete it under Settings → API keys. It stops working at once. ### Rotating a key To replace a key without downtime: 1. Make a new key with the same scopes. 2. Deploy it to your systems alongside the old one, then switch over. 3. Check the old key's "last used" time in the app has stopped moving. 4. Revoke the old key. ## Keeping keys safe - **Server-side only.** The API sends no CORS headers, so browsers refuse to call it: a key in a web page or a mobile app is a key anyone can take. Call the API from your server, a background job or a build step. - **In your secrets, not your code.** Read the key from an environment variable or your secrets manager, and keep it out of logs and error reports. - **If a key leaks**, revoke it straight away and make a new one. Revoking is instant. --- # Conventions > How every endpoint behaves - IDs, times, partial updates, filtering, files, the emails calls can send, and retrying. ## Requests - **Base URL**: `https://api.hirehappy.io/v1`. HTTPS only. - **Bodies are JSON** (`Content-Type: application/json`), except resume uploads, which are `multipart/form-data`. - **Responses are JSON**, in UTF-8. A delete returns `204 No Content` and no body. - **Resources are plural nouns** (`/jobs`, `/candidates`), and the ones that belong to another sit under it (`/jobs/{job_id}/job-stages`, `/candidates/{candidate_id}/notes`). ## IDs Every object has an `id`, a UUID like `7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c`. Store them as strings. They're the same IDs the app uses, so you can match them to what you see there. ## Times - **Out**: ISO 8601, always in UTC with a `Z`, sometimes with fractions of a second: `2026-10-26T09:30:00.692264Z`. Any ISO 8601 parser reads them. - **In**: ISO 8601 with a timezone, like `2026-11-02T00:00:00Z` or `2026-11-02T00:00:00+01:00`. Times without one are refused with `422` (type `timezone_aware`), rather than guessed at. Your organization's timezone (an IANA name like `Europe/Berlin`) is on [Retrieve your organization](https://hirehappy.io/docs/api/organizations#get-organization), for showing times the way your team sees them. ## Nulls and missing fields - **Responses always have every field.** A field with no value is `null`, never left out, so you can rely on the shape. - **New fields may appear** in any response. Ignore the ones you don't know (see [Versioning](https://hirehappy.io/docs/versioning)). ## Partial updates `PATCH` changes only the fields you send. Fields you leave out keep their values, and `null` clears an optional one: ```bash curl -X PATCH https://api.hirehappy.io/v1/candidates/CANDIDATE_ID \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"phone": "+49 30 901820", "linkedin_url": null}' ``` This sets the phone number, clears the LinkedIn URL and leaves everything else as it was. ## Choices Fields with a fixed set of values (a job's `status`, an application's `status`, an interview's `kind`) are lowercase strings. The [API reference](https://hirehappy.io/docs/api) lists each one's values. More values may be added within `/v1`, so handle ones you don't know, for example by treating them like the closest one you do. ## Filtering and search - **Lists filter by query parameters**, like `GET /applications?job_id=…&status=active`. - **Repeat a parameter to match any of several values**: `?status=active&status=hired`. - **`q` searches text.** On applications it matches the candidate's name, email and resume, and every word has to match: `q=react berlin` finds React developers in Berlin. On candidates it matches part of the name or email; on jobs, the title. Lists come a page at a time; see [Pagination](https://hirehappy.io/docs/pagination). ## Rich text A job's `description` is HTML, limited to `p`, `h2`–`h4`, `strong`, `em`, `u`, `s`, `a`, `ul`, `ol`, `li`, `blockquote`, `code` and `pre`. Anything else you send is stripped, and what comes back is safe to render as is. ## Files - **Resumes are uploaded as PDFs**, up to 10 MB, with [Upload a candidate's resume](https://hirehappy.io/docs/api/candidates#put-candidate-resume). - **A candidate's `resume_url`** is a long, unguessable link that works for anyone who has it. Treat it like the resume itself: don't publish it or log it. ## What calls do beyond the data The API works the way the app does, side effects included: - **Moving an application along emails the candidate** when they applied through your job board and the new stage is shown on their status page. Candidates you added yourself have no status page, so moves don't email them. - **Rejecting emails the candidate only when you ask**, with `notify_candidate`. - **Hiring starts onboarding**, whether you move the application to its job's last stage or set its status to `hired`. Like in the app, that welcomes the new hire by email to their onboarding page. - **New applications are scored by AI** in the background when their job has a rubric. ## Rate limits and retries There's no fixed rate limit today, but keep to a few requests at a time and pace big jobs, like a first full sync. Limits will come, so handle them now: - On `429 Too Many Requests` and `503 Service Unavailable`, wait and retry, honouring the `Retry-After` header when there is one, and backing off exponentially when not. - **Retrying is safe** for `GET`, `PATCH`, `PUT` and `DELETE`: doing them twice has the same effect as once. - **`POST` creates something each time**, so retry it with care. Creating a candidate with an email that's already taken, or an application that already exists, fails with `409` rather than making a duplicate. Treat that `409` on a retry as "it worked the first time". --- # Pagination > Page through jobs, candidates, applications and interviews with limit and offset. Lists that can grow without bound (jobs, candidates, applications, interviews) come a page at a time. Small lists that belong to one thing, like a job's stages or a candidate's notes, come whole, as a plain array. ## Paging Paged lists take two query parameters: | Parameter | Default | | | --------- | ------- | --------------------------------- | | `limit` | `50` | How many to return, from 1 to 100 | | `offset` | `0` | How many to skip | And return the page with the total count: ```json { "items": [ { "id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c", "title": "Backend Engineer" } ], "total": 132, "limit": 50, "offset": 0 } ``` There's more to fetch while `offset + limit < total`. A `limit` over 100 is refused with `422`, rather than quietly cut short. ## Fetching everything ```python def paginate(client, path, **params): offset = 0 while True: page = client.get(path, params={**params, "limit": 100, "offset": offset}) page.raise_for_status() body = page.json() yield from body["items"] offset += body["limit"] if offset >= body["total"]: return for application in paginate(client, "/applications", status="hired"): print(application["candidate"]["email"]) ``` ```js async function* paginate(path, params = {}) { for (let offset = 0; ;) { const query = new URLSearchParams({ ...params, limit: "100", offset: String(offset), }); const response = await fetch(`https://api.hirehappy.io/v1${path}?${query}`, { headers: { Authorization: `Bearer ${process.env.HIREHAPPY_API_KEY}` }, }); if (!response.ok) throw new Error(`HireHappy API: ${response.status}`); const page = await response.json(); yield* page.items; offset += page.limit; if (offset >= page.total) return; } } for await (const application of paginate("/applications", { status: "hired", })) { console.log(application.candidate.email); } ``` ## Order Each list has a fixed order, given in the [API reference](https://hirehappy.io/docs/api): newest first for jobs, candidates and applications (or best match first, for applications with `sort=score`), and soonest first for interviews. Pages are counted from the top of the list each time. If items are added while you page through, one may show up twice, so key what you collect by `id`. For a list that changes often, filter it down (by job, status or time) rather than paging through all of it. --- # Errors > The one shape every error has, the types to branch on, and how to handle each. The API answers with standard HTTP status codes: `2xx` for success, `4xx` for something in the request, and `5xx` for something on our side. ## The error shape Every error has the same body: a list of what went wrong, usually one. ```json { "detail": [ { "type": "conflict", "loc": ["body", "email"], "msg": "A candidate with email 'ana.ribeiro@example.com' already exists." } ] } ``` | Field | | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | A stable, machine-readable code. **Branch on this.** | | `loc` | Where the problem is: `["body", "email"]` for a field of the body, `["query", "limit"]` for a query parameter, `["path", "job_id"]` for part of the URL, or just `["body"]` when it's the request as a whole. | | `msg` | What went wrong, in a sentence for people. It may be reworded, so don't match on it. | Validation errors (`422`) also have `input`, what was sent, and sometimes `ctx`, with details like the limit that was exceeded. ## Status codes and types | Status | Type | Means | | ------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `400` | `validation_error` | A value can't be used, though it's well formed, like a resume that isn't a PDF. | | `401` | `api_key_required` | No API key was sent. | | `401` | `invalid_api_key` | The key is wrong, expired or revoked. | | `403` | `insufficient_scope` | The key isn't allowed this; see [scopes](https://hirehappy.io/docs/authentication#scopes). | | `404` | `resource_not_found` | It doesn't exist, or belongs to another organization. | | `409` | `conflict` | It clashes with what's there, like a second candidate with the same email. | | `422` | `missing`, `uuid_parsing`, `string_too_long`, `less_than_equal`, `timezone_aware`, `value_error`, … | A parameter or field doesn't validate. One entry per problem. | | `429` | | Too many requests. Wait and retry. | | `500` | | Something broke on our side. Retry later, and tell us if it lasts. | | `503` | | Briefly unavailable. Wait and retry. | A `422` lists every problem with the request at once: ```json { "detail": [ { "type": "missing", "loc": ["body", "last_name"], "msg": "Field required", "input": { "first_name": "Ana" } }, { "type": "less_than_equal", "loc": ["query", "limit"], "msg": "Input should be less than or equal to 100", "input": "500", "ctx": { "le": 100 } } ] } ``` ## Handling errors Retry `429`, `500` and `503` with a backoff; fix the request for the rest. A `409` is often information rather than failure: the candidate or application you were making is already there. ```python import time import httpx class HireHappyError(Exception): def __init__(self, response: httpx.Response): self.status = response.status_code self.errors = response.json().get("detail", []) if response.content else [] self.type = self.errors[0]["type"] if self.errors else None super().__init__(f"{self.status} {self.type}: {self.errors}") def request(client: httpx.Client, method: str, path: str, **kwargs): for attempt in range(5): response = client.request(method, path, **kwargs) if response.status_code in (429, 500, 502, 503, 504): time.sleep(float(response.headers.get("Retry-After", 2**attempt))) continue if response.is_error: raise HireHappyError(response) return response.json() if response.content else None raise HireHappyError(response) ``` ```js class HireHappyError extends Error { constructor(status, errors) { super(`${status} ${errors[0]?.type}: ${errors[0]?.msg}`); this.status = status; this.errors = errors; this.type = errors[0]?.type; } } async function request(method, path, body) { for (let attempt = 0; attempt < 5; attempt++) { const response = await fetch(`https://api.hirehappy.io/v1${path}`, { method, headers: { Authorization: `Bearer ${process.env.HIREHAPPY_API_KEY}`, ...(body && { "Content-Type": "application/json" }), }, body: body && JSON.stringify(body), }); if ([429, 500, 502, 503, 504].includes(response.status)) { const wait = Number(response.headers.get("Retry-After") ?? 2 ** attempt); await new Promise((resolve) => setTimeout(resolve, wait * 1000)); continue; } if (!response.ok) { const { detail = [] } = await response.json().catch(() => ({})); throw new HireHappyError(response.status, detail); } return response.status === 204 ? null : response.json(); } throw new HireHappyError(503, []); } ``` --- # Versioning > What can change within /v1 and what never will, and how you'll hear about changes. The API's version is in its URL: `https://api.hirehappy.io/v1`. Within `/v1`, nothing you rely on breaks. ## What never changes within /v1 - Fields are never renamed or removed, and never change type. - Endpoints are never removed, and never start needing more than they do. - Error `type` codes keep their meaning. ## What may change These are additions, and integrations should take them in their stride: - **New endpoints**, and new optional parameters on existing ones. - **New fields in responses.** Ignore fields you don't know, rather than failing on them; in particular, don't validate responses against a closed schema. - **New values in choice fields**, like a new interview `kind` or stage `kind`. Handle values you don't know. - **New error types**, under the existing status codes. - **Wording**: `msg` in errors, and descriptions in these docs. Anything that would break an integration waits for `/v2`. When there is one, `/v1` will keep working long enough for you to move, and we'll write to you about it. ## Hearing about changes Every change to the API is in the [changelog](https://hirehappy.io/docs/changelog), newest first. The [OpenAPI schema](https://hirehappy.io/docs/openapi.json) always describes the API as it is, so diffing it is a quick way to see what changed. --- # 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

Backend Engineer

Berlin, Germany · Hybrid · Full-time

Apply
``` `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. --- # Add candidates from anywhere > Bring candidates in from referral forms, sourcing tools and events, with their resumes, put them forward for jobs and get them scored. Candidates who apply on your job board arrive by themselves. This guide is for everyone else: referrals from your team, candidates from a sourcing tool or an agency, people you met at an event. You'll add the candidate, attach their resume, put them forward for a job, and read the AI's scorecard. **You'll need** a key with `candidates:write` and `applications:write`, plus `jobs:read` to look up jobs. ## 1. Add the candidate [Create a candidate](https://hirehappy.io/docs/api/candidates#create-candidate) with their name, and whatever else you have. Set `source` to where they came from, in your own words. The team sees it in the app, and you can report on it later. ```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" }' ``` ### Someone who's already there A candidate is one person across all your jobs, and their email is unique in your organization. Adding one whose email is taken fails with `409`: ```json { "detail": [ { "type": "conflict", "loc": ["body", "email"], "msg": "A candidate with email 'ana.ribeiro@example.com' already exists." } ] } ``` Then find them ([List candidates](https://hirehappy.io/docs/api/candidates#list-candidates) with `q` set to the email) and use the one that's there: ```python def find_or_create_candidate(client, data: dict) -> dict: response = client.post("/candidates", json=data) if response.status_code == 409 and data.get("email"): found = client.get("/candidates", params={"q": data["email"]}).raise_for_status().json() for candidate in found["items"]: if (candidate["email"] or "").lower() == data["email"].lower(): return candidate response.raise_for_status() return response.json() ``` ## 2. Attach their resume [Upload the resume](https://hirehappy.io/docs/api/candidates#put-candidate-resume) as a PDF, up to 10 MB, sent as `multipart/form-data` in a field named `resume`. It replaces any resume they had. ```bash curl -X PUT https://api.hirehappy.io/v1/candidates/CANDIDATE_ID/resume \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" \ -F "resume=@ana-ribeiro.pdf;type=application/pdf" ``` ```python with open("ana-ribeiro.pdf", "rb") as pdf: client.put( f"/candidates/{candidate['id']}/resume", files={"resume": ("ana-ribeiro.pdf", pdf, "application/pdf")}, ).raise_for_status() ``` ```js import { openAsBlob } from "node:fs"; const form = new FormData(); form.append( "resume", await openAsBlob("ana-ribeiro.pdf", { type: "application/pdf" }), "ana-ribeiro.pdf" ); await fetch(`https://api.hirehappy.io/v1/candidates/${candidate.id}/resume`, { method: "PUT", headers: { Authorization: `Bearer ${process.env.HIREHAPPY_API_KEY}` }, body: form, }); ``` > [!IMPORTANT] > Upload the resume **before** putting the candidate forward. Scoring reads the resume as it is when the application is scored, so a resume added later is only used when it's scored again. ## 3. Put them forward for a job [Create an application](https://hirehappy.io/docs/api/applications#create-application) for the candidate and the job. It starts in the job's first stage. To start further along (someone you've already screened, say), send a `stage_id` from [the job's stages](https://hirehappy.io/docs/api/job-stages#list-job-stages). ```bash curl -X POST https://api.hirehappy.io/v1/applications \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"job_id": "JOB_ID", "candidate_id": "CANDIDATE_ID"}' ``` A candidate has one application per job, so putting them forward twice for the same one fails with `409`. For a retry, that means the first attempt worked. ## 4. Read the scorecard When the job has a rubric, the new application is scored by AI in the background, usually within a minute or two. Its `scorecard` shows how that's going: ```json "scorecard": { "status": "pending", "score": null, "knockout_result": null, "scored_at": null } ``` Once `status` is `completed`, [Retrieve the scorecard](https://hirehappy.io/docs/api/scorecards#get-scorecard) for the whole of it: the score out of 100, a summary, and each criterion of the rubric with its score, the reasoning, and a quote from the resume or answers as evidence. ```python import time def wait_for_scorecard(client, application_id: str, timeout: float = 180) -> dict | None: deadline = time.monotonic() + timeout while time.monotonic() < deadline: application = client.get(f"/applications/{application_id}").raise_for_status().json() status = (application["scorecard"] or {}).get("status") if status == "completed": return client.get(f"/applications/{application_id}/scorecard").raise_for_status().json() if status in (None, "failed"): return None # No rubric, or scoring failed: the team can re-score in the app. time.sleep(10) return None ``` You don't have to wait for it: the team sees the score in the app as soon as it's ready. ## 5. Tell the team why [Add a note](https://hirehappy.io/docs/api/notes#create-note) with the context that came with the candidate: who referred them, or what the recruiter said. It shows on their profile in the app, marked as added through the API. ```bash curl -X POST https://api.hirehappy.io/v1/candidates/CANDIDATE_ID/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."}' ``` ## What the candidate sees Nothing, yet. Candidates you add don't get the job board's emails or a status page (their application's `status_url` is null), so you decide how and when to get in touch. --- # Sync hires to your HR system > Create new hires in your HRIS or payroll as soon as they're hired in HireHappy, and hire from your own systems. When a candidate is hired in HireHappy, your HR system (Personio, BambooHR, Workday, your own) needs them as an employee. This guide keeps the two in step with a small job you run on a schedule. **You'll need** a key with `applications:read`, `candidates:read` and `jobs:read`. ## How it works An application is hired when the team moves it to its job's last stage, or marks it hired. A sync job: 1. Lists hired applications. 2. Skips the ones it has already synced. 3. For each new one, reads the candidate and the job, and creates the employee in your HR system. 4. Remembers it, so it isn't synced twice. There are no webhooks yet, so run it on a schedule: every 15 minutes to an hour suits most teams. ## The sync job Hired applications are few, even in big organizations, so list them all each time ([List applications](https://hirehappy.io/docs/api/applications#list-applications) with `status=hired`) rather than tracking where you left off. The list is ordered by when each application was made, not when it was hired, so a hire from an old application could be anywhere in it. ```python import os import httpx client = httpx.Client( base_url="https://api.hirehappy.io/v1", headers={"Authorization": f"Bearer {os.environ['HIREHAPPY_API_KEY']}"}, ) def hired_applications(): offset = 0 while True: body = client.get( "/applications", params={"status": "hired", "limit": 100, "offset": offset}, ).raise_for_status().json() yield from body["items"] offset += body["limit"] if offset >= body["total"]: return def sync(synced: set[str]) -> None: """`synced`: the application ids already in the HR system, kept by you.""" for application in hired_applications(): if application["id"] in synced: continue candidate = client.get(f"/candidates/{application['candidate_id']}").raise_for_status().json() job = client.get(f"/jobs/{application['job_id']}").raise_for_status().json() create_employee( # Your HR system's API. first_name=candidate["first_name"], last_name=candidate["last_name"], email=candidate["email"], phone=candidate["phone"], job_title=job["title"], location=job["location"], hired_at=application["updated_at"], # Its last change: the hire, when synced soon after. external_id=application["id"], ) synced.add(application["id"]) ``` Keep `synced` somewhere that lasts, like a table in your database. Better still, store the application `id` on the employee in your HR system (most have an external ID field), so the HR system itself knows who's synced. > [!NOTE] > An application stops being `hired` if the team moves it back into the pipeline, say after a hire made by mistake. Your job won't see it in the list any more. Decide whether that should undo anything on your side; usually a person should look at it. ## Hiring from your own systems The other direction works too: when an offer is signed in your HR system, mark the application hired in HireHappy ([Update an application](https://hirehappy.io/docs/api/applications#update-application), which needs `applications:write`): ```bash curl -X PATCH https://api.hirehappy.io/v1/applications/APPLICATION_ID \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"status": "hired"}' ``` This moves the application to its job's last stage and starts onboarding, as hiring in the app does: the new hire is welcomed by email to their onboarding page. ## Other things to sync The same pattern works for other moments: - **Rejections**, for reporting: `status=rejected`, with the internal `rejection_reason`. - **Withdrawals**: `status=withdrawn`, with the candidate's own `withdrawal_reason`. - **A stage**, like everyone in Offer: `stage_id`, from [the job's stages](https://hirehappy.io/docs/api/job-stages#list-job-stages). --- # Show an interview calendar > Put the week's interviews on a dashboard, a meeting-room screen or a team channel, with who's interviewing whom and where. Every interview, call and assessment in HireHappy is on [List interviews](https://hirehappy.io/docs/api/interviews#list-interviews): across all your jobs, soonest first. This guide builds a week's calendar from it: for a dashboard, a screen by the meeting rooms, or a Monday post in your team's chat. **You'll need** a key with `applications:read`. ## Interviews, calls and assessments Each has a `kind`: | Kind | What it is | When | | ------------ | -------------------------------------- | ----------------------------- | | `interview` | An interview booked with the candidate | `starts_at` to `ends_at` | | `call` | A call the team made to them | `starts_at`, when it was made | | `assessment` | Work the candidate was set to hand in | `due_at`, then `submitted_at` | An application has one per stage: rescheduling an interview changes it, and cancelling one deletes it. ## The week's interviews Ask for interviews starting within the week. Times go in with a timezone and come out in UTC: ```bash curl "https://api.hirehappy.io/v1/interviews?kind=interview&starts_after=2026-11-02T00:00:00Z&starts_before=2026-11-09T00:00:00Z" \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" ``` Each one names the candidate and the interviewers, so there's nothing else to look up: ```json { "id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80", "application_id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e", "job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c", "candidate": { "id": "c9d8e7f6-…", "first_name": "Ana", "last_name": "Ribeiro", "email": "ana.ribeiro@example.com" }, "kind": "interview", "starts_at": "2026-11-03T10:00:00Z", "ends_at": "2026-11-03T10:45:00Z", "location": "https://meet.google.com/abc-defg-hij", "interviewers": [ { "id": "9a8b7c6d-…", "first_name": "Maya", "last_name": "Okafor", "email": "maya@acme.com" } ] } ``` `location` is free text: a meeting link, an address, or "Phone". ## Days in your timezone The API speaks UTC; your team doesn't. Take the organization's timezone from [Retrieve your organization](https://hirehappy.io/docs/api/organizations#get-organization) and group the week by local day: ```python import os from collections import defaultdict from datetime import datetime, timedelta from zoneinfo import ZoneInfo import httpx client = httpx.Client( base_url="https://api.hirehappy.io/v1", headers={"Authorization": f"Bearer {os.environ['HIREHAPPY_API_KEY']}"}, ) tz = ZoneInfo(client.get("/organizations/self").raise_for_status().json()["timezone"]) today = datetime.now(tz).replace(hour=0, minute=0, second=0, microsecond=0) monday = today - timedelta(days=today.weekday()) interviews = client.get("/interviews", params={ "kind": "interview", "starts_after": monday.isoformat(), "starts_before": (monday + timedelta(days=7)).isoformat(), "limit": 100, }).raise_for_status().json()["items"] days = defaultdict(list) for interview in interviews: starts = datetime.fromisoformat(interview["starts_at"]).astimezone(tz) days[starts.date()].append((starts, interview)) for day, entries in sorted(days.items()): print(day.strftime("%A %-d %B")) for starts, interview in entries: candidate = interview["candidate"] with_ = ", ".join(i["first_name"] for i in interview["interviewers"]) print(f" {starts:%H:%M} {candidate['first_name']} {candidate['last_name']} with {with_} ({interview['location']})") ``` ```text Tuesday 3 November 11:00 Ana Ribeiro with Maya (https://meet.google.com/abc-defg-hij) ``` A week with more than 100 interviews needs more than one page; see [Pagination](https://hirehappy.io/docs/pagination). ## Assessments that are due Assessments have no start time, so leave out the time filters and check `due_at` and `submitted_at` yourself: ```bash curl "https://api.hirehappy.io/v1/interviews?kind=assessment&limit=100" \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" ``` Those with `submitted_at` set are in, waiting for review by their `interviewers`. Those without are outstanding, and overdue once `due_at` has passed. ## One candidate's rounds For everything one application has been through, ask the application itself ([List an application's interviews](https://hirehappy.io/docs/api/interviews#list-application-interviews)): every round, latest first. --- # Connect AI apps (MCP) > Add HireHappy to Claude, ChatGPT, Cursor or any MCP client, so it can work with your jobs and candidates as a member of your hiring team. HireHappy runs an [MCP](https://modelcontextprotocol.io) server, the open standard AI apps use to connect to other software. Connect it, and your AI app can answer questions about your jobs, applicants and scores, and keep the pipeline moving, in plain words: - "Who are the strongest Backend Engineer applicants with open source work?" - "Compare the three best on system design, with evidence." - "Export the whole pipeline as a spreadsheet." - "Move Jonah to Interview and tell the team why." It's for people working in their AI app. For your own systems and scripts, use the [API](https://hirehappy.io/docs/quickstart) instead. ## The server URL ```text https://api.hirehappy.io/mcp ``` Any app that supports remote MCP servers over HTTP, with OAuth sign-in, can connect. There's nothing to install and no key to copy. ## Connecting When you add the server, your app sends you to HireHappy to sign in. There you pick **one organization** for the app, and whether it **can make changes** or only read. Approve, and you're back in your app, connected. ### Claude In Claude (web or desktop), go to **Settings → Connectors → Add custom connector**, name it HireHappy, and paste the server URL. On Team and Enterprise plans, an owner adds it for the organization first. ### Claude Code ```bash claude mcp add --transport http hirehappy https://api.hirehappy.io/mcp ``` Then run `/mcp` in Claude Code, pick hirehappy, and sign in. ### ChatGPT In ChatGPT's settings, under **Apps & Connectors**, add a custom connector with the server URL. Custom connectors need developer mode on some plans; ChatGPT's help explains the steps for yours. ### Cursor Add it to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project): ```json { "mcpServers": { "hirehappy": { "url": "https://api.hirehappy.io/mcp" } } } ``` ### VS Code Add it to `.vscode/mcp.json`, then start it from the file or the MCP view: ```json { "servers": { "hirehappy": { "type": "http", "url": "https://api.hirehappy.io/mcp" } } } ``` ### Other apps Point them at the server URL. The server is its own OAuth 2.1 authorization server, with discovery (RFC 9728 and RFC 8414), dynamic client registration (RFC 7591) and PKCE, so apps that follow the MCP spec set themselves up. ## What it can see and do The app **acts as you**, in the one organization you picked: it sees exactly what you can in HireHappy, and nothing more. If you leave the organization, it loses access too. | Permission | Lets the app | | ---------------- | --------------------------------------------------------------------------------------------------- | | Read | Find, read, compare and export jobs, applications, candidates and scorecards | | Can make changes | Also move applications, bookmark them, give feedback, add notes, and change rubrics and focus areas | Apps that ask before running tools (Claude does, by default) show each change before it's made. Changes show in HireHappy as made by you. To disconnect an app, open **Settings → AI apps** in HireHappy. It loses access at once. ## Tools | Tool | | What it does | | -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_jobs` | Read | The organization's jobs, newest first | | `get_job` | Read | A job with its pipeline (stages, with how many applications are in each) and the rubric applications are scored against | | `query_applications` | Read | Find, screen and rank applications on the server, by score, any rubric criterion, GitHub, resume text, education, stage or status, returning only the fields asked for | | `list_applications` | Read | Applications, filtered, with their stage and headline score | | `get_application` | Read | One application in depth: where it stands, its scorecard with evidence, the candidate's answers and resume | | `get_applications` | Read | Up to 25 applications in depth at once, for comparing a shortlist | | `export_applications` | Read | Every application matching the filters, written to a CSV or JSON file, for bulk work | | `search_candidates` | Read | The organization's candidates, one per person across jobs | | `get_candidate` | Read | A candidate with their applications and the team's notes | | `move_application` | Change | Move an application to another stage; the last stage hires | | `set_application_bookmark` | Change | Bookmark an application for the team, or take the bookmark off | | `give_feedback` | Change | Your ratings and recommendation on an interview, call or assessment | | `add_note` | Change | A note on a candidate for the team, as you | | `update_job_rubric` | Change | Reword, reweight, add or remove the criteria AI scores a job's applications against | | `set_stage_focus_areas` | Change | Set what the team rates in a stage's interviews, calls or assessments | The server keeps results lean, filtering and ranking itself rather than handing your AI app everything to read, so answers come faster and stay within the app's limits on big jobs. ## Troubleshooting - **The app can't connect.** Check the URL ends in `/mcp`, and that the app supports remote (HTTP) MCP servers with OAuth. Some only run local servers. - **It says it isn't allowed to make a change.** You connected it read-only. Disconnect it under Settings → AI apps and connect again, allowing changes. - **It's looking at the wrong organization.** An app connects to one organization. Disconnect it and connect again, picking the other one. --- # Docs for AI coding tools > Give Claude Code, Cursor, Copilot and other AI tools these docs as plain Markdown, and the OpenAPI schema for generating clients. If you build your integration with an AI coding tool, give it these docs. Every page is published as plain Markdown, which AI tools read better and more cheaply than web pages. ## The files | URL | What it is | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | [/llms.txt](https://hirehappy.io/llms.txt) | An index of the docs, with a line on each page, following [llmstxt.org](https://llmstxt.org) | | [/llms-full.txt](https://hirehappy.io/llms-full.txt) | All the guides and the whole API reference, in one file | | `/docs/{page}.md` | Any page as Markdown: [/docs/quickstart.md](https://hirehappy.io/docs/quickstart.md), [/docs/api/applications.md](https://hirehappy.io/docs/api/applications.md) | | [/docs/openapi.json](https://hirehappy.io/docs/openapi.json) | The API's OpenAPI 3.1 schema | Every page also has **Copy page** and **View as Markdown** buttons under its title, for pasting into a chat. ## In your prompt Point your tool at the index, and it fetches the pages it needs: ```text Build a script that syncs hired candidates from HireHappy to our HR system. The HireHappy API docs are at https://hirehappy.io/llms.txt; read the pages you need. ``` Or, for a tool that can't fetch, paste in `llms-full.txt` or the pages the task needs. ## Generating a client The OpenAPI schema describes every endpoint, parameter and field, with descriptions. Generate typed clients from it: ```bash npx openapi-typescript https://hirehappy.io/docs/openapi.json -o hirehappy.d.ts ``` ```bash uvx openapi-python-client generate --url https://hirehappy.io/docs/openapi.json ``` It imports into Postman, Insomnia and Bruno too. Each operation also carries the scope it needs, as `x-required-scope`. ## Your own AI app Want your AI assistant itself to work with HireHappy, rather than write code for it? That's the [MCP server](https://hirehappy.io/docs/mcp). --- # Changelog > Every change to the HireHappy API and MCP server, newest first. Changes within `/v1` only ever add; see [Versioning](https://hirehappy.io/docs/versioning) for what that promises. ## October 28, 2026 ### The developer API The first version of the HireHappy API, at `https://api.hirehappy.io/v1`: - **API keys** made by owners and admins under Settings → API keys, with [scopes](https://hirehappy.io/docs/authentication#scopes) for jobs, candidates and applications, and optional expiry. - **Jobs**: list, create, read and update them, open and close them, and read their pipeline stages. - **Candidates**: list, search, create, update and delete them, upload their resumes, and read and add the hiring team's notes. - **Applications**: list them by job, candidate, stage, status or resume text, best match first or newest; put candidates forward; move them between stages; reject and hire. - **AI scorecards**: each application's score against its job's rubric, criterion by criterion, with the evidence. - **Interviews**: interviews, calls and assessments across the organization, by kind and time. ### These docs Guides, an API reference built from the OpenAPI schema, and the docs as Markdown for AI tools: [llms.txt](https://hirehappy.io/llms.txt), [llms-full.txt](https://hirehappy.io/llms-full.txt), and each page at its URL plus `.md`. --- # Organizations > The organization the API key belongs to. Part of the HireHappy API reference (https://hirehappy.io/docs/api). Base URL: `https://api.hirehappy.io/v1`. Authenticate with `Authorization: Bearer `. ### Retrieve your organization `GET https://api.hirehappy.io/v1/organizations/self` Any API key. The organization the API key belongs to. Any key may read it: a quick way to check a key works. **Example request** ```bash curl "https://api.hirehappy.io/v1/organizations/self" \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" ``` **Response** `200` | Name | Type | Description | | --- | --- | --- | | `id` | uuid | | | `name` | string | | | `slug` | string | Where its job board is: {jobs site}/{slug}. | | `website` | string | nullable | | `timezone` | string | IANA name, e.g. Europe/Berlin. | ```json { "id": "0b6f3c2e-8a41-4d7e-9c55-3e2f1a7b9d10", "name": "Acme", "slug": "acme", "website": "https://acme.com", "timezone": "Europe/Berlin" } ``` **Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing). --- # API keys > The API key itself: what it may do. Part of the HireHappy API reference (https://hirehappy.io/docs/api). Base URL: `https://api.hirehappy.io/v1`. Authenticate with `Authorization: Bearer `. ### Retrieve the API key `GET https://api.hirehappy.io/v1/api-keys/self` Any API key. The API key the request is made with: its name, what it may do and when it expires. **Example request** ```bash curl "https://api.hirehappy.io/v1/api-keys/self" \ -H "Authorization: Bearer $HIREHAPPY_API_KEY" ``` **Response** `200` | Name | Type | Description | | --- | --- | --- | | `id` | uuid | | | `name` | string | | | `scopes` | array of enum | What the key may do. one of `jobs:read`, `jobs:write`, `candidates:read`, `candidates:write`, `applications:read`, `applications:write` | | `expires_at` | datetime | Null never expires. nullable | ```json { "id": "5e1d9a47-2c3b-4f80-8d6e-7a9b0c1d2e3f", "name": "Careers site", "scopes": [ "jobs:read", "applications:read", "applications:write" ], "expires_at": null } ``` **Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing). --- # 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 `. ### 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.