Docs

Search the docs

Guides, sections and API endpoints

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.

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

JSON
{
  "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:

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

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.

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

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