Get started
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 aremultipart/form-data. - Responses are JSON, in UTF-8. A delete returns
204 No Contentand 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:00Zor2026-11-02T00:00:00+01:00. Times without one are refused with422(typetimezone_aware), rather than guessed at.
Your organization's timezone (an IANA name like Europe/Berlin) is on Retrieve your 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).
Partial updates
PATCH changes only the fields you send. Fields you leave out keep their values, and null clears an optional one:
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 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. qsearches text. On applications it matches the candidate's name, email and resume, and every word has to match:q=react berlinfinds 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.
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.
- A candidate's
resume_urlis 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 Requestsand503 Service Unavailable, wait and retry, honouring theRetry-Afterheader when there is one, and backing off exponentially when not. - Retrying is safe for
GET,PATCH,PUTandDELETE: doing them twice has the same effect as once. POSTcreates 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 with409rather than making a duplicate. Treat that409on a retry as "it worked the first time".