How to Find and Enrich Leads From Claude Code

How to Find and Enrich Leads From Claude Code

How to Find and Enrich Leads From Claude CodeHassann

The Firecrawl Alexandria people API lets your coding agent find and enrich people through one...

The Firecrawl Alexandria people API lets your coding agent find and enrich people through one Firecrawl key. You discover tools for free with v2/search, list candidates with Apollo people/search at 0 credits, reveal one with Apollo people/match at 30 credits, or enrich a known email with People Data Labs person/enrich at 60 credits. Every call goes through POST /v2/scrape.

Try Apidog today

Each step below comes twice: a prompt for Claude Code (or Codex) and the raw curl, so you can script it without an agent.

What the Firecrawl Alexandria people API is

Alexandria is Firecrawl's library of third-party data providers, reachable with the API key you already use for scraping. Per the Alexandria docs, you discover a tool, inspect its inputs and price, then run it with scrape. Discovery is free; execution costs the credits listed on the tool.

The People category holds 12 providers. Two of them cover most prospecting work:

Provider Capability Credits per call What you send What you get
Apollo people/search 0 person_titles, q_keywords, q_organization_domains_list, per_page (max 100) Previews: first name, masked surname, title, company, has_email, Apollo id
Apollo people/match 30 id from search, or linkedin_url, email, or name plus domain One resolved person with title, history and contact details
People Data Labs person/enrich 60 email, profile, pdl_id and others; a bare name returns a 400 A full person record plus likelihood (1 to 10)

Prices are the ones shown next to the Run button on the Apollo page and the People Data Labs page on November 4, 2026. Apollo's page also says a people/match miss "returns no person and is not billed."

What a people lookup costs in dollars

A credit's value depends on your plan. Per the Firecrawl pricing page, Hobby is $19 a month for 5,000 credits and Standard is $99 a month for 100,000 credits, both billed monthly.

Call Credits Hobby ($0.0038/credit) Standard ($0.00099/credit)
Discovery search or find-tools 0 $0 $0
Apollo people/search 0 $0 $0
Apollo people/match 30 $0.114 $0.0297
PDL person/enrich 60 $0.228 $0.0594

The math: $19 / 5,000 = $0.0038 per credit, and $99 / 100,000 = $0.00099. Searching 100 previews and revealing the best 20 costs 600 credits, which fits inside the Free plan's monthly 1,000. People Data Labs also caps you at 50,000 API calls per year per organization, shared across person and company endpoints, retries included.

Flow of a people lookup on Firecrawl Alexandria: free discovery search, Apollo people/search at 0 credits, Apollo people/match at 30 credits, People Data Labs person/enrich at 60 credits, and feedback refunding 1 credit

Step 1: Connect Claude Code to Firecrawl

The fastest route is Firecrawl's agent installer. It adds the Firecrawl skills to every coding agent it detects and signs you in through the browser:

npx -y firecrawl-cli@latest init --all --browser
Enter fullscreen mode Exit fullscreen mode

Restart your agent afterward. By hand, it's npm install -g firecrawl-cli and firecrawl login. Our Firecrawl CLI guide covers both, and the Firecrawl MCP walkthrough covers the MCP server, which exposes the same loop as firecrawl_search, firecrawl_find_tools and firecrawl_scrape.

For the curl examples below, export your key once:

export FIRECRAWL_API_KEY="fc-..."   # never commit this
Enter fullscreen mode Exit fullscreen mode

Step 2: Discover the people tools for free

Ask your agent first, since discovery costs nothing:

Use Firecrawl Alexandria to find tools that search people by job title and
company, and tools that enrich a person from an email. Inspect Apollo and
People Data Labs with find-tools and show me each capability's inputs and
credit price before you run anything.
Enter fullscreen mode Exit fullscreen mode

Under the hood, that's a search with sources set to ["alexandria"] only. Leaving out "web" keeps it free, because web results are billed:

curl https://api.firecrawl.dev/v2/search \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "find people by job title and company", "sources": ["alexandria"], "limit": 5}'
Enter fullscreen mode Exit fullscreen mode

The response lists ranked tools, each with a provider, capability and description. To read inputs and prices, the agent runs find-tools:

firecrawl find-tools --options '{"providers":["apollo","people-data-labs"],"level":"tools","expand":["options","response"]}' --include-costs
Enter fullscreen mode Exit fullscreen mode

Step 3: Search Apollo for candidates at 0 credits

Apollo's page tells agents to always start here: it's free and shows who exists before you spend anything.

Run Apollo people/search through Firecrawl Alexandria for "VP of Sales" and
"Head of Revenue" at stripe.com and linear.app, 25 per page. Show name,
title, company and has_email. Don't reveal anyone yet.
Enter fullscreen mode Exit fullscreen mode

The raw call:

curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alexandria": {
      "provider": "apollo",
      "capability": "people/search",
      "options": {
        "person_titles": ["VP of Sales", "Head of Revenue"],
        "q_organization_domains_list": ["stripe.com", "linear.app"],
        "page": 1,
        "per_page": 25
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Each preview carries a masked surname and an Apollo id, the most reliable input for the next step.

Step 4: Reveal one person with people/match

Now pay only for the people worth contacting, at 30 credits per match:

For the 3 previews with has_email true, run Apollo people/match with their
id. Don't set reveal_personal_emails or reveal_phone_number.
Enter fullscreen mode Exit fullscreen mode 
curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alexandria": {"provider": "apollo", "capability": "people/match", "options": {"id": "<apollo_id>"}}}'
Enter fullscreen mode Exit fullscreen mode

Leave the two reveal flags off unless you need them. The Apollo page says a personal email "bills extra" and a phone number is "substantially more expensive than the base match."

Step 5: Enrich a known email with People Data Labs

When you already have an email, say from an inbound signup, person/enrich returns a fuller profile: work email, title, company, LinkedIn URL, experience and skills.

Enrich jane@example.com with People Data Labs person/enrich through
Firecrawl Alexandria. Set min_likelihood to 6 so a weak match comes back
as a 404 instead of a wrong record.
Enter fullscreen mode Exit fullscreen mode 
curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alexandria": {"provider": "people-data-labs", "capability": "person/enrich", "options": {"email": "jane@example.com", "min_likelihood": 6}}}'
Enter fullscreen mode Exit fullscreen mode

min_likelihood runs from 1 to 10 with a default of 2. The provider page puts the tradeoff plainly: a 404 "is free here and a wrong record is not." Raise it before you loop over a list.

Handle THIRD_PARTY_DATA_TERMS_REQUIRED

Your first paid call to a provider may fail with THIRD_PARTY_DATA_TERMS_REQUIRED. Per the docs, the error carries a requiresAction.url, and an org admin has to open it and accept that provider's terms before any call goes through.

Don't let the agent click through it. The docs say agents need explicit user authorization before accepting terms, which govern how you may use personal data. Add one line to your CLAUDE.md: "If a call returns THIRD_PARTY_DATA_TERMS_REQUIRED, stop and show me requiresAction.url."

Read the alexandria[].data payload

Results come back in an alexandria array, one entry per tool call, with the provider's payload under data. Raw HTTP wraps the whole SDK result in a top-level data, so in a curl response the Apollo match sits at data.alexandria[0].data.person:

curl -s https://api.firecrawl.dev/v2/scrape ... | jq '.data.alexandria[0].data.person | {name, title, email, linkedin_url}'
Enter fullscreen mode Exit fullscreen mode

Two checks keep bad rows out of your CRM:

  1. Check each result for errors before you read data. The docs say this explicitly; a single call can fail while the HTTP request succeeds.
  2. Treat placeholder emails as missing. Apollo notes that an unrevealed email can come back as the literal email_not_unlocked@domain.com, even when email_status says verified.

For People Data Labs, the person sits under data inside the result, next to the envelope's status and likelihood.

Send feedback and get a credit back

Alexandria pays you for feedback. Each submission refunds 1 credit for any rating, capped per UTC day at 10 credits per website and 100 per team. You have 20 minutes from your team's latest Alexandria call; after that you get FEEDBACK_WINDOW_EXPIRED.

From the CLI, run firecrawl alexandria feedback (see --help for the options). Over MCP, the agent calls firecrawl_feedback with endpoint: "alexandria". A prompt line works well: "If a result looks wrong or empty, send Alexandria feedback describing it."

Let Claude Code guard these calls with Apidog CLI

Once a script depends on people/search returning an id that people/match accepts, a renamed field breaks it quietly. Your agent can turn the calls from this guide into a regression scenario in Apidog CLI and run it on a schedule. You write one prompt.

Set up the CLI and its agent skill once:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code or Codex when prompted
Enter fullscreen mode Exit fullscreen mode

Then give Claude Code this [REDACTED PROMPT]
Write an OpenAPI 3 file for three Firecrawl calls from this guide:
POST /v2/search with sources ["alexandria"], POST /v2/scrape for apollo
people/search (per_page 1), and POST /v2/scrape for apollo people/match.
All send Authorization: Bearer {{FIRECRAWL_API_KEY}}. Import it into Apidog
project and create a "Firecrawl" environment for
https://api.firecrawl.dev. Build a test scenario that runs the three in
order, saves data.alexandria[0].data.people[0].id as personId and passes it
to people/match, and asserts status 200, no result error, and a person
object on the match. Run it and summarize failures.


The agent reads each payload schema, validates it, then runs commands like these:
Enter fullscreen mode Exit fullscreen mode


bash
apidog import --project --format openapi --file ./firecrawl-people.json
apidog environment create Firecrawl --project --base-url https://api.firecrawl.dev
apidog test-scenario create --project --name "Alexandria people" --folder-id --priority
apidog cli-schema get test-scenario-update
apidog cli-schema validate test-scenario-update --file ./people-scenario.json
apidog test-scenario update --project --file ./people-scenario.json
apidog run -t --project -e \
--env-var "FIRECRAWL_API_KEY=$FIRECRAWL_API_KEY" -r cli,junit




![Diagram of an Apidog test scenario chaining Firecrawl v2/search, Apollo people/search and Apollo people/match, run by a coding agent with apidog run and producing a test report](https://assets.apidog.com/blog-next/2026/11/firecrawl-alexandria-people-api-apidog-scenario.png)

Each full run costs 30 credits for the match, so schedule it daily rather than on every commit. The [apidog run reference](http://apidog.com/blog/apidog-run-command-reference?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) lists the report and iteration flags, and [Apidog CLI in Claude Code](http://apidog.com/blog/apidog-cli-in-claude-code?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) shows the setup in more depth. Apidog's Free plan covers up to 4 users.

  


## FAQ

**Is the Firecrawl Alexandria people API free?** Discovery is free, and Apollo `people/search` showed 0 credits on November 4, 2026. Revealing a person costs credits: 30 for Apollo `people/match` and 60 for People Data Labs `person/enrich`. The Free plan includes 1,000 credits a month with no card.

**Do I need separate Apollo or People Data Labs accounts?** No. Alexandria runs both through your Firecrawl API key and bills in Firecrawl credits. An org admin does need to accept each provider's terms once, which is what `THIRD_PARTY_DATA_TERMS_REQUIRED` asks for.

**Why does my people/match response show [email_not_unlocked@domain.com](mailto:email_not_unlocked@domain.com)?** That's Apollo's placeholder for an email that wasn't revealed. Treat it as unavailable, even if `email_status` says verified.

**Can Codex or Cursor run this instead of Claude Code?** Yes. `npx -y firecrawl-cli@latest init --all` sets up every detected agent, and the MCP tools work in any MCP client. The `curl` calls work with no agent at all.

**How do I avoid paying for wrong matches?** Search before you match, match by Apollo `id` rather than by name, and set `min_likelihood` to 6 or higher on People Data Labs. Apollo doesn't bill a miss, and a PDL 404 is free.
Enter fullscreen mode Exit fullscreen mode