Guides
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 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.
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]",
"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:
{
"detail": [
{
"type": "conflict",
"loc": ["body", "email"],
"msg": "A candidate with email '[email protected]' already exists."
}
]
}Then find them (List candidates with q set to the email) and use the one that's there:
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 as a PDF, up to 10 MB, sent as multipart/form-data in a field named resume. It replaces any resume they had.
curl -X PUT https://api.hirehappy.io/v1/candidates/CANDIDATE_ID/resume \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-F "[email protected];type=application/pdf"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()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,
});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 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.
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:
"scorecard": { "status": "pending", "score": null, "knockout_result": null, "scored_at": null }Once status is completed, Retrieve the 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.
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 NoneYou 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 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.
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.