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