Docs

Search the docs

Guides, sections and API endpoints

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

Shell
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.

  • 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.

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_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".