# Add candidates from anywhere

> Bring candidates in from referral forms, sourcing tools and events, with their resumes, put them forward for jobs and get them scored.

Candidates who apply on your job board arrive by themselves. This guide is for everyone else: referrals from your team, candidates from a sourcing tool or an agency, people you met at an event. You'll add the candidate, attach their resume, put them forward for a job, and read the AI's scorecard.

**You'll need** a key with `candidates:write` and `applications:write`, plus `jobs:read` to look up jobs.

## 1. Add the candidate

[Create a candidate](https://hirehappy.io/docs/api/candidates#create-candidate) with their name, and whatever else you have. Set `source` to where they came from, in your own words. The team sees it in the app, and you can report on it later.

```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",
    "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
    "source": "referral"
  }'
```

### Someone who's already there

A candidate is one person across all your jobs, and their email is unique in your organization. Adding one whose email is taken fails with `409`:

```json
{
  "detail": [
    {
      "type": "conflict",
      "loc": ["body", "email"],
      "msg": "A candidate with email 'ana.ribeiro@example.com' already exists."
    }
  ]
}
```

Then find them ([List candidates](https://hirehappy.io/docs/api/candidates#list-candidates) with `q` set to the email) and use the one that's there:

```python
def find_or_create_candidate(client, data: dict) -> dict:
    response = client.post("/candidates", json=data)
    if response.status_code == 409 and data.get("email"):
        found = client.get("/candidates", params={"q": data["email"]}).raise_for_status().json()
        for candidate in found["items"]:
            if (candidate["email"] or "").lower() == data["email"].lower():
                return candidate
    response.raise_for_status()
    return response.json()
```

## 2. Attach their resume

[Upload the resume](https://hirehappy.io/docs/api/candidates#put-candidate-resume) as a PDF, up to 10 MB, sent as `multipart/form-data` in a field named `resume`. It replaces any resume they had.


```bash
curl -X PUT https://api.hirehappy.io/v1/candidates/CANDIDATE_ID/resume \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -F "resume=@ana-ribeiro.pdf;type=application/pdf"
```

```python
with open("ana-ribeiro.pdf", "rb") as pdf:
    client.put(
        f"/candidates/{candidate['id']}/resume",
        files={"resume": ("ana-ribeiro.pdf", pdf, "application/pdf")},
    ).raise_for_status()
```

```js
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append(
  "resume",
  await openAsBlob("ana-ribeiro.pdf", { type: "application/pdf" }),
  "ana-ribeiro.pdf"
);
await fetch(`https://api.hirehappy.io/v1/candidates/${candidate.id}/resume`, {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.HIREHAPPY_API_KEY}` },
  body: form,
});
```


> [!IMPORTANT]
> Upload the resume **before** putting the candidate forward. Scoring reads the resume as it is when the application is scored, so a resume added later is only used when it's scored again.

## 3. Put them forward for a job

[Create an application](https://hirehappy.io/docs/api/applications#create-application) for the candidate and the job. It starts in the job's first stage. To start further along (someone you've already screened, say), send a `stage_id` from [the job's stages](https://hirehappy.io/docs/api/job-stages#list-job-stages).

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

A candidate has one application per job, so putting them forward twice for the same one fails with `409`. For a retry, that means the first attempt worked.

## 4. Read the scorecard

When the job has a rubric, the new application is scored by AI in the background, usually within a minute or two. Its `scorecard` shows how that's going:

```json
"scorecard": { "status": "pending", "score": null, "knockout_result": null, "scored_at": null }
```

Once `status` is `completed`, [Retrieve the scorecard](https://hirehappy.io/docs/api/scorecards#get-scorecard) for the whole of it: the score out of 100, a summary, and each criterion of the rubric with its score, the reasoning, and a quote from the resume or answers as evidence.

```python
import time

def wait_for_scorecard(client, application_id: str, timeout: float = 180) -> dict | None:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        application = client.get(f"/applications/{application_id}").raise_for_status().json()
        status = (application["scorecard"] or {}).get("status")
        if status == "completed":
            return client.get(f"/applications/{application_id}/scorecard").raise_for_status().json()
        if status in (None, "failed"):
            return None  # No rubric, or scoring failed: the team can re-score in the app.
        time.sleep(10)
    return None
```

You don't have to wait for it: the team sees the score in the app as soon as it's ready.

## 5. Tell the team why

[Add a note](https://hirehappy.io/docs/api/notes#create-note) with the context that came with the candidate: who referred them, or what the recruiter said. It shows on their profile in the app, marked as added through the API.

```bash
curl -X POST https://api.hirehappy.io/v1/candidates/CANDIDATE_ID/notes \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "Referred by Sam on the platform team; they worked together at Bolt."}'
```

## What the candidate sees

Nothing, yet. Candidates you add don't get the job board's emails or a status page (their application's `status_url` is null), so you decide how and when to get in touch.
