HR Hiring — Find More Like This

Endpoints it uses

• /api/v1/profile/full10 credits/call
• /api/v1/search/people10 credits/call
• /api/v1/search/people-live10 credits/call

Ballpark: ~300 credits for 10 typical runs. Signup includes 300 free credits.

What's inside (full preview)

---
name: linkedin-hr-hiring
description: Use when a hiring manager or recruiter provides ONE LinkedIn profile of a "good match" candidate and wants to find more candidates like them. Triggers on requests like "find more candidates like X", "who else fits this profile", "build me a sourcing list from this hire", "duplicate this employee", "more profiles like this engineer". Returns a ranked list of similar candidates with title, location, and headline.
---

# LinkedIn HR Hiring (via Zooq)

You source hiring candidates by starting from ONE seed profile the user already considers a "good match". You read what actually makes that person a fit — their current title, their current employer's industry, their top skills — and then search LinkedIn's professional graph for other people who share those attributes. Useful for replacement hires, scaling a successful role, or building a sourcing list anchored on a known-good profile.

## Inputs you need from the user

- **Seed handle**: the LinkedIn handle of the "good match" candidate (the part after `linkedin.com/in/`). Example: `jane-doe-engineer`, not the full URL.
- **Count** (optional, default 20): how many similar candidates to return.
- **Filters** (optional): location, current title contains, seniority. You can push most of these straight into the search (title, `geo_country_code`, `geo_city`, `current_only`) rather than filtering client-side.
- **Enrich** (optional, default true): whether to pull each candidate's full profile (skills, education) for fit scoring. Adds one extra API call per candidate; toggle off for cheap shortlists.

## How to call

This skill uses 2 Zooq endpoints (each call consumes Zooq credits — see https://zooq.dev/dash for the user's current balance and per-call cost):

1. **Read the seed profile (the "match template")** — one call gives you everything you need to describe the ideal candidate:
```
GET https://zooq.dev/api/v1/profile/full?handle=<SEED_HANDLE>
Headers:
  X-API-Key: REPLACE_WITH_YOUR_KEY
```
   From `data`, extract the seed's "ideal" attributes:
   - **Current title** — the `title` of the `full_positions[]` entry where `is_current === true`.
   - **Current employer** — that same entry's `organization_slug` and `organization_industry`.
   - **Top skills** — the `normalized_name` of the first several `data.skills[]` entries.
   - **Location** — `data.geo.countryCode` (and `data.geo.city` if you want to keep the search local).

2. **Search for similar candidates** using those attributes as filters:
```
GET https://zooq.dev/api/v1/search/people?title=<SEED_TITLE>&skills=<SKILL1,SKILL2>&geo_country_code=<CC>&current_only=true&limit=<N>
Headers:
  X-API-Key: REPLACE_WITH_YOUR_KEY
```
   Filter guidance:
   - `title` — the seed's current title (min 3 chars), e.g. `Director of Engineering`. Match a role *family*, not the exact string — drop seniority prefixes like "Senior"/"Staff" from the title filter and score seniority separately (see below).
   - `skills` — 2-4 of the seed's top normalized skill names, comma-separated. Use `skills_match=any` (the default) to widen, `skills_match=all` to tighten.
   - `geo_country_code` (and optionally `geo_city`, min 3 chars) — from the seed's geo, unless the user wants a broader search.
   - `current_only=true` — restrict the title/skill match to people's *current* roles.
   - `limit` — 1-50 per page (default 20). For more than 50 results, paginate: pass the `pagination.next_cursor` from the previous response back as `&cursor=<VALUE>`, and stop when you've reached the requested count or `pagination.has_more` is false.

   **Dedupe the seed:** the search will usually return the seed candidate themselves — drop any result whose `handle` equals the seed handle before you count/rank.

3. **(Optional) Enrich each candidate** for fit scoring:
```
GET https://zooq.dev/api/v1/profile/full?handle=<CANDIDATE_HANDLE>
Headers:
  X-API-Key: REPLACE_WITH_YOUR_KEY
```
   Only do this when `enrich = true`. It returns each candidate's full `skills[]`, `full_positions[]`, and `education[]` so you can score them. Skip for fast/cheap shortlists.

### Resolving skill names (optional helper)

If the seed's skills come back oddly formatted, or you want to broaden a skill into its canonical catalog form, look it up:
```
GET https://zooq.dev/api/v1/g/title-skills-lookup?name=<SKILL>
Headers:
  X-API-Key: REPLACE_WITH_YOUR_KEY
```
Read `data[].normalized_name` and feed that into the `skills` filter above. In practice the `normalized_name` values already on the seed profile work directly, so this call is usually unnecessary.

## Optional: source the seed's FORMER colleagues (live search)

People who USED to work at the seed's company are often the strongest matches — same environment, already moved once. The dataset search cannot express this; the live search can:

```
GET https://zooq.dev/api/v1/companies/entity-id?slug=<SEED_COMPANY_SLUG>
GET https://zooq.dev/api/v1/search/people-live?pastCompany=<ORG_ID>&title=<SEED_TITLE>&count=20
Headers:
  X-API-Key: REPLACE_WITH_YOUR_KEY
```

Offer this as a second sourcing lane when the user's seed has a notable employer. 10 credits per call, same as everything else.

## Fit scoring algorithm

When `enrich = true`, compute a 0-100 fit score per candidate (read the candidate's current title, skills, and geo from their enriched `profile/full` record):

1. **Title match (40 points):** if candidate's current title exactly matches the seed's title → 40. Same role family (e.g. both "Engineer" of any seniority) → 25. Different family → 0.
2. **Skills overlap (30 points):** `(candidate skills ∩ seed skills) / max(seed skills, 1) × 30`. Compare on `normalized_name`. Cap at 30.
3. **Seniority match (15 points):** infer seniority from title prefix (Senior / Staff / Principal / VP / Director / Head of). Same level → 15, ±1 level → 7, more → 0.
4. **Location match (15 points):** exact city match → 15, same metro → 10, same country → 5, else 0.

If `enrich = false`, omit the score; just return the candidates in the order search returned them (best keyword relevance first).

## API-call ballparks

Count of API calls per run shape (NOT credit cost — multiply by current per-call rate from the Zooq dashboard):

- **Lean (no enrich, 10 candidates):** ~2 calls (1 seed read + 1 search page).
- **Standard (enrich, 20 candidates):** ~2 + 20 enrichments = ~22 calls.
- **Bulk (enrich, 50 candidates):** ~52 calls (1 seed + ~1 search page + 50 enrichments).

Always tell the user roughly how many calls a run will make and confirm before kicking it off.

## Output format

Return a Markdown table sorted by fit score descending (or by search relevance if no enrichment):

```
| Rank | Name | Title | Location | Fit | LinkedIn |
|---|---|---|---|---|---|
| 1 | Alice Wong | Senior ML Engineer @ Anthropic | San Francisco | 87 | linkedin.com/in/alice-wong |
| 2 | Bob Singh  | Staff Engineer @ OpenAI         | Mountain View | 81 | linkedin.com/in/bob-singh   |
```

Build the LinkedIn column from each result's `handle` (`linkedin.com/in/<handle>`) and pull Name/Title/Location from `first_name`+`last_name`, `headline`, and `geo_city`/`geo`.

After the table, write 2-3 sentences summarizing the cohort (common employers, dominant skill, geographic concentration) — recruiters use this to refine the search.

## Don't do

- **Don't return raw JSON.** Recruiters read tables, not JSON dumps.
- **Don't fabricate data the API didn't return** (e.g. salary, willingness to leave, contact info). The data is LinkedIn-public only.
- **Don't over-narrow the search.** Stacking an exact title + `skills_match=all` + city can return zero rows. Start broad (role family + 2 skills + country), then tighten only if the user wants a shorter list.
- **Don't forget to drop the seed** from the results before ranking — search returns the seed candidate themselves.
- **Don't dedupe across multiple runs in the same session** unless asked — assume the user wants a fresh search.
- **Don't store the API key in any output back to the user.** It's already wired into this skill file.

## On rate limits and refunds

- HTTP 429 → wait 30 seconds, retry once.
- HTTP 5xx → the Zooq proxy auto-refunds credits and surfaces a 502. Do not retry beyond what the user explicitly approved.
- HTTP 402 → user is out of credits. Tell them: "You're out of Zooq credits. Top up at https://zooq.dev/dash/billing — Add Credits in the sidebar."