# 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](https://app.hirehappy.io/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.

> [!WARNING]
> 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:

```bash
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:


```bash
curl https://api.hirehappy.io/v1/organizations/self \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
```

```python
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())
```

```js
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());
```


```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](https://hirehappy.io/docs/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](https://hirehappy.io/docs/api/jobs#list-jobs)):


```bash
curl "https://api.hirehappy.io/v1/jobs?status=open" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
```

```python
jobs = client.get("/jobs", params={"status": "open"}).raise_for_status().json()
job_id = jobs["items"][0]["id"]
```

```js
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](https://hirehappy.io/docs/api/candidates#create-candidate)):


```bash
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": "ana.ribeiro@example.com",
    "source": "referral"
  }'
```

```python
candidate = client.post(
    "/candidates",
    json={
        "first_name": "Ana",
        "last_name": "Ribeiro",
        "email": "ana.ribeiro@example.com",
        "source": "referral",
    },
).raise_for_status().json()
```

```js
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: "ana.ribeiro@example.com",
    source: "referral",
  }),
}).then((r) => r.json());
```


And put them forward for the job ([Create an application](https://hirehappy.io/docs/api/applications#create-application)). They land in the job's first stage, and if the job has a rubric, AI scores the application in the background:


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

```python
application = client.post(
    "/applications",
    json={"job_id": job_id, "candidate_id": candidate["id"]},
).raise_for_status().json()
print(application["stage_id"], application["scorecard"])
```

```js
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](https://hirehappy.io/docs/authentication): scopes, expiry and keeping keys safe.
- [Conventions](https://hirehappy.io/docs/conventions): IDs, times, partial updates and what happens behind each call.
- [Add candidates from anywhere](https://hirehappy.io/docs/add-candidates): resumes, duplicates and scoring, the full version of step 3.
- [API reference](https://hirehappy.io/docs/api): every endpoint.
