Get started
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:
- Open Settings → API keys and choose New key.
- Name it after what will use it, like "Careers site" or "HRIS sync".
- 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.
- 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.
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:
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:
curl https://api.hirehappy.io/v1/organizations/self \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"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())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());{
"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 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):
curl "https://api.hirehappy.io/v1/jobs?status=open" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"jobs = client.get("/jobs", params={"status": "open"}).raise_for_status().json()
job_id = jobs["items"][0]["id"]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):
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": "[email protected]",
"source": "referral"
}'candidate = client.post(
"/candidates",
json={
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]",
"source": "referral",
},
).raise_for_status().json()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: "[email protected]",
source: "referral",
}),
}).then((r) => r.json());And put them forward for the job (Create an application). They land in the job's first stage, and if the job has a rubric, AI scores the application in the background:
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"}'application = client.post(
"/applications",
json={"job_id": job_id, "candidate_id": candidate["id"]},
).raise_for_status().json()
print(application["stage_id"], application["scorecard"])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: scopes, expiry and keeping keys safe.
- Conventions: IDs, times, partial updates and what happens behind each call.
- Add candidates from anywhere: resumes, duplicates and scoring, the full version of step 3.
- API reference: every endpoint.