Docs

Search the docs

Guides, sections and API endpoints

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:

  1. Open 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.

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:

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

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"
  }'

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"}'

Open the job in HireHappy and Ana is there, in the first stage, with a scorecard on its way.

Next steps