Leads Discover

Endpoints it uses

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

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

What's inside (full preview)

---
name: linkedin-leads-discover
description: Use when the user wants to find more people similar to a seed LinkedIn profile — typical asks include "find more people like X", "expand this list of leads", "find similar profiles to this CEO". Skill discovers similar profiles by reading the seed's role and company, then searching for people who match, via Zooq.
---

# LinkedIn Leads Discover (via Zooq)

You discover LinkedIn profiles similar to a starting seed. Useful for sales prospecting, recruitment ICP expansion, or building a target list from a small set of known good profiles.

The approach is **profile-then-search**: read what the seed actually is (their current job title, their current company, their industry), then use Zooq's people-search to find others who match that shape. This is more controllable than a black-box "similar" feed — you decide which of the seed's attributes define "similar", and you can widen or tighten the net.

## Inputs you need from the user

- **Seed handle**: one LinkedIn handle to start from — the part after `linkedin.com/in/` (e.g. `satyanadella`).
- **Depth** (optional, default 1): how many recursion levels to explore. At each level you take the profiles found so far, read each one's role/company, and search again — so the target list branches out:
  - depth 1: search off the seed only (~10-50 profiles)
  - depth 2: also search off each depth-1 profile (~100s)
  - depth 3: also search off each depth-2 profile (~1000s; rarely needed — always confirm with the user before depth ≥ 3)
- **Max results** (optional, default 50): cap on total profiles to return. Deduplicate by handle.

## Endpoints this skill uses

All calls are GET, auth header `X-API-Key: REPLACE_WITH_YOUR_KEY`. Every call consumes Zooq credits; the user's balance and per-call cost are at https://zooq.dev/dash.

### 1. Resolve the seed handle → stable id (and read the record)

```
GET https://zooq.dev/api/v1/profile/username-to-urn?handle=<HANDLE>
Headers:
  X-API-Key: REPLACE_WITH_YOUR_KEY
```

Read `data.id` (a stable `prsn_...` id). Note: the response is actually the FULL profile record, not just an id — so if all you needed was basic fields you already have them. For "similar" discovery you want the seed's **current role and company**, which live in `full_positions`; the next call guarantees those are present.

### 2. Read the seed's role, company, and industry

```
GET https://zooq.dev/api/v1/profile/full?handle=<HANDLE>
Headers:
  X-API-Key: REPLACE_WITH_YOUR_KEY
```

From `data`, pull the "similarity signature":
- `data.headline` — a good free-text summary of what they do.
- `data.full_positions[]` where `is_current === true` — each has:
  - `title` (e.g. "Chairman and CEO")
  - `organization_slug` (e.g. "microsoft") — the company's public slug
  - `organization_industry` (e.g. "Computer Software")

Pick the primary current position (usually the first with `is_current: true`). Its `title` and `organization_slug` drive the search below. The `organization_industry` tells you the space the seed operates in — use it to sanity-check that your matches stay on-topic.

### 3. Search for similar people

```
GET https://zooq.dev/api/v1/search/people?title=<TITLE>&organization_slugs=<SLUG>&current_only=true&limit=10
Headers:
  X-API-Key: REPLACE_WITH_YOUR_KEY
```

`data[]` is the list of matching professional records; `pagination.next_cursor` (present when `pagination.has_more` is true) pages further — pass it back as `&cursor=<next_cursor>`.

Two search shapes, depending on what "similar" should mean for the user's ask:
- **Same company, same kind of role** (peers/colleagues): `title=<seed title>&organization_slugs=<seed org slug>&current_only=true`.
- **Same role across the wider market** (competitors, other companies): `title=<seed title>&current_only=true`, optionally narrowed by `geo_country_code=<us>` or `geo_city=<...>`. Drop `organization_slugs` so you span companies.

Useful extra filters on `/search/people` (all optional): `skills` (comma-separated normalized names, e.g. `python,leadership`), `headline` (free-text, min 3 chars), `geo_country_code`, `geo_city`, `is_creator`, `is_premium`, `limit` (1-50). `title` matches loosely, so keep it short — use `chief executive officer` rather than a decorated headline string.

Each result record includes `handle`, `first_name`, `last_name`, `headline`, and `geo` / `geo_city` / `geo_country_code` — enough to present without a follow-up call.

### 3b. Optional expansion axis — company alumni (live search)

When the seed's current or past employer is distinctive, expand through it directly. Resolve the org id once (`GET /api/v1/companies/entity-id?slug=<SLUG>`), then:

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

`pastCompany` (alumni) has no equivalent on the dataset search and often surfaces the best lookalikes — people who shared the seed's environment and have since spread across the market.

## Behavior

1. Resolve the seed handle and read `profile/full` → capture the seed's current `title`, `organization_slug`, and `organization_industry`.
2. Run `/search/people` off that signature (same-company or across-market per the user's intent). Collect results; page with `cursor` until you have enough or `has_more` is false.
3. If depth > 1: for each newly discovered profile not yet processed, call `/profile/full` on its handle to read ITS current title + company, then run a fresh `/search/people`. This is how discovery branches — each person becomes a new seed. Continue to the specified depth.
4. Always **deduplicate** by handle — the same person surfaces under many searches.
5. Stop early once you hit max_results.
6. Return: a clean list of `{ handle, fullName, headline, location }` per discovered profile.

## Call-count ballparks (NOT credit costs — depth grows fast)

- depth 1: seed resolve + seed profile/full + a few search pages → ~3-8 API calls.
- depth 2: add 2 calls (profile/full + a search) per depth-1 profile you branch on → dozens of calls. Cap how many depth-1 profiles you branch on (e.g. top 10) to keep it bounded.
- depth 3: hundreds+ of calls — **always confirm with the user before running**, since at any per-call cost this is a meaningful spend.

## Don't do

- Don't run depth ≥ 3 without explicit user confirmation showing the credit cost estimate.
- Don't re-process the same handle twice (waste of credits) — keep a "seen" set.
- Don't pass a whole headline into `title` — it over-narrows and returns nothing. Extract the core role.
- Don't dump the raw recursion tree on the user — present a clean deduplicated list.
- Don't store API keys in code or output. The key is configured for you in this skill file.

## On errors and limits

- **HTTP 402** — the user is out of credits. Stop and direct them to top up at https://zooq.dev/dash.
- **HTTP 429** — rate limited. Slow down, wait 30 seconds, retry once. The Zooq proxy enforces per-key rate limits.
- **HTTP 400/422** — a bad parameter (e.g. `title` under 3 chars, or an unknown filter). Re-read the filter list above; every string filter needs at least 3 characters.
- Empty `data[]` on a search is legitimate — the signature was too narrow. Widen it (drop `organization_slugs`, shorten `title`, or remove a geo filter) and retry.