Candidate sourcing by title and skill

Recipe prompt

Implement this recipe in my project: https://www.forager.ai/docs/recipes/source-candidates.md

Build a candidate sourcing search. Resolve skill and location names to IDs with the Forager person skills and locations autocomplete endpoints, let the user choose the matches, then run a person role search with role_title, role_is_current, person_skills and person_locations. Show name, headline, location and LinkedIn profile URL, with paging through the page field. Handle empty results, a 403, and a 429 with backoff, and cache autocomplete results. Keep the API key server-side in FORAGER_API_KEY with FORAGER_ACCOUNT_ID. Add tests that stub the HTTP calls.

Candidate sourcing: title, skill and location filters return a list of candidates

What you’ll build

A sourcing search for a recruiting tool. A recruiter types a title, a skill and a place. Your server turns the skill and place into IDs, runs the search, and returns a page of candidates to review.

Steps

Resolve skills and locations

Search filters take IDs. Call Person skills lookup and Locations lookup with q. Each returns results with an id and text. Show the text values so the recruiter can choose.

curl -G "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/autocomplete/person_skills/" \
  -H "X-API-KEY: $FORAGER_API_KEY" --data-urlencode "q=python"

curl -G "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/autocomplete/locations/" \
  -H "X-API-KEY: $FORAGER_API_KEY" --data-urlencode "q=Berlin"

import os, requests

BASE = f"https://api-v2.forager.ai/api/{os.environ['FORAGER_ACCOUNT_ID']}/datastorage"
HEADERS = {"X-API-KEY": os.environ["FORAGER_API_KEY"]}

def suggest(kind, q):
    r = requests.get(f"{BASE}/autocomplete/{kind}/", headers=HEADERS, params={"q": q}, timeout=30)
    r.raise_for_status()
    return [(int(i["id"]), i["text"]) for i in r.json()["results"]]

skills = suggest("person_skills", "python")
places = suggest("locations", "Berlin")

const BASE = `https://api-v2.forager.ai/api/${process.env.FORAGER_ACCOUNT_ID}/datastorage`;
const headers = {
  "X-API-KEY": process.env.FORAGER_API_KEY,
  "Content-Type": "application/json",
};

async function suggest(kind, q) {
  const r = await fetch(`${BASE}/autocomplete/${kind}/?q=${encodeURIComponent(q)}`, { headers });
  if (!r.ok) throw new Error(`Forager ${r.status}`);
  return (await r.json()).results.map((i) => [Number(i.id), i.text]);
}

const skills = await suggest("person_skills", "python");
const places = await suggest("locations", "Berlin");

Search by role, skill and location

Send a POST to Person role search with the chosen IDs. role_title supports a boolean text query, such as "backend engineer" OR "software engineer". To count matches before you fetch them, send the same body to Person role search totals.

curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/person_role_search/" \
  -H "X-API-KEY: $FORAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_title": "Backend Engineer", "role_is_current": true, "person_skills": [101], "person_locations": [202], "page": 1}'

r = requests.post(
    f"{BASE}/person_role_search/",
    headers=HEADERS,
    json={
        "role_title": "Backend Engineer",
        "role_is_current": True,
        "person_skills": [skills[0][0]],
        "person_locations": [places[0][0]],
        "page": 1,
    },
    timeout=30,
)
r.raise_for_status()
candidates = [hit["person"] for hit in r.json()["search_results"]]

const r = await fetch(`${BASE}/person_role_search/`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    role_title: "Backend Engineer",
    role_is_current: true,
    person_skills: [skills[0][0]],
    person_locations: [places[0][0]],
    page: 1,
  }),
});
if (!r.ok) throw new Error(`Forager ${r.status}`);
const candidates = (await r.json()).search_results.map((hit) => hit.person);

Show the candidates

Each person has id, full_name, headline, skills and location. Its linkedin_info carries public_profile_url and public_identifier. Show these and keep the id for the next step. Use person_headline or person_description to narrow the search by text, and role_years_on_position_start and role_years_on_position_end to filter by time in role.

Get contact details for shortlisted people

Only for the people a recruiter shortlists, follow the candidate contact recipe.

Handle the edge cases

Not found. An empty search_results means no match. Offer to drop the location or a skill. If autocomplete returns no results for a name, try a shorter term.
403. The key is missing or invalid. Fix the credentials; do not retry.
429. Autocomplete allows 10 requests per second per account, so cache IDs and debounce typeahead. See errors and rate limits.
Paging. Use page to request more results.
Credits. A role search costs 1 credit per request, and so does a role search totals call. Autocomplete is free. See credit pricing.

Search people by role

Every role search filter.

Find filter values

Which autocomplete feeds which filter.

Person skills lookup

Autocomplete reference.

Recipes

Sales and dialer platforms

Recruiting platforms

Data and product teams

AI agents

Sample apps

More examples

Candidate sourcing by title and skill

What you’ll build

Steps

Handle the edge cases

Search people by role

Find filter values

Person skills lookup

​What you’ll build

​Steps

​Handle the edge cases

​Related

Search people by role

Find filter values

Person skills lookup

What you’ll build

Steps

Handle the edge cases

Related