Como Encontrar e Enriquecer Leads com o Claude Code

A API de pessoas do Firecrawl Alexandria permite que seu agente de codificação encontre e enriqueça pessoas através de uma única chave do Firecrawl. Você descobre ferramentas gratuitamente com v2/search, lista candidatos com o Apollo people/search a 0 créditos, revela um com o Apollo people/match a 30 créditos, ou enriquece um e-mail conhecido com o People Data Labs person/enrich a 60 créditos. Toda chamada passa por POST /v2/scrape.

Cada passo abaixo aparece duas vezes: um prompt para o Claude Code (ou Codex) e o curl bruto, para que você possa scriptá-lo sem um agente.

O que é a API de pessoas do Firecrawl Alexandria

Alexandria é a biblioteca do Firecrawl de provedores de dados de terceiros, acessível com a chave de API que você já usa para scraping. De acordo com a documentação do Alexandria, você descobre uma ferramenta, inspeciona suas entradas e preço, e então a executa com scrape. A descoberta é gratuita; a execução custa os créditos listados na ferramenta.

A categoria Pessoas contém 12 provedores. Dois deles cobrem a maior parte do trabalho de prospecção:

Os preços são os mostrados ao lado do botão Run na página do Apollo e na página do People Data Labs em 4 de novembro de 2026. A página do Apollo também diz que um erro de people/match "retorna nenhuma pessoa e não é cobrado."

Quanto custa uma consulta de pessoas em dólares

O valor de um crédito depende do seu plano. De acordo com a página de preços do Firecrawl, o Hobby é $19 por mês para 5.000 créditos e o Standard é $99 por mês para 100.000 créditos, ambos cobrados mensalmente.

A matemática: $19 / 5.000 = $0,0038 por crédito, e $99 / 100.000 = $0,00099. Pesquisar 100 prévias e revelar as 20 melhores custa 600 créditos, o que cabe dentro dos 1.000 mensais do plano Free. O People Data Labs também limita você a 50.000 chamadas de API por ano por organização, compartilhadas entre endpoints de pessoa e empresa, incluindo tentativas repetidas.

Passo 1: Conecte o Claude Code ao Firecrawl

A rota mais rápida é o instalador de agente do Firecrawl. Ele adiciona as skills do Firecrawl a cada agente de codificação que detecta e faz login para você através do navegador:

npx -y firecrawl-cli@latest init --all --browser

Reinicie seu agente depois. Manualmente, é npm install -g firecrawl-cli e firecrawl login. Nosso guia do Firecrawl CLI cobre ambos, e o passo a passo do Firecrawl MCP cobre o servidor MCP, que expõe o mesmo ciclo como firecrawl_search, firecrawl_find_tools e firecrawl_scrape.

Para os exemplos de curl abaixo, exporte sua chave uma vez:

export FIRECRAWL_API_KEY="fc-..."   # never commit this

Passo 2: Descubra as ferramentas de pessoas gratuitamente

Pergunte ao seu agente primeiro, já que a descoberta não custa nada:

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.

Por baixo dos panos, isso é uma pesquisa com sources definido apenas como ["alexandria"]. Omitir "web" mantém a pesquisa gratuita, porque resultados da web são cobrados:

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}'

A resposta lista tools classificadas, cada uma com um provedor, capacidade e descrição. Para ler entradas e preços, o agente executa find-tools:

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

Passo 3: Pesquise no Apollo por candidatos a 0 créditos

A página do Apollo diz aos agentes para sempre começar aqui: é gratuito e mostra quem existe antes de você gastar qualquer coisa.

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.

A chamada bruta:

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
      }
    }
  }'

Cada prévia carrega um sobrenome mascarado e um id do Apollo, a entrada mais confiável para o próximo passo.

Passo 4: Revele uma pessoa com people/match

Agora pague apenas pelas pessoas que valem a pena contatar, a 30 créditos por 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.

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

Deixe as duas flags de revelação desativadas, a menos que você precise delas. A página do Apollo diz que um e-mail pessoal "cobra a mais" e um número de telefone é "substancialmente mais caro do que o match base."

Passo 5: Enriqueça um e-mail conhecido com o People Data Labs

Quando você já tem um e-mail, digamos de um cadastro de entrada, person/enrich retorna um perfil mais completo: e-mail de trabalho, cargo, empresa, URL do LinkedIn, experiência e habilidades.

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.

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}}}'

min_likelihood vai de 1 a 10 com um padrão de 2. A página do provedor coloca o trade-off de forma clara: um 404 "é gratuito aqui e um registro errado não é." Aumente-o antes de iterar sobre uma lista.

Lide com THIRD_PARTY_DATA_TERMS_REQUIRED

Sua primeira chamada paga a um provedor pode falhar com THIRD_PARTY_DATA_TERMS_REQUIRED. De acordo com a documentação, o erro carrega um requiresAction.url, e um administrador da organização precisa abri-lo e aceitar os termos daquele provedor antes que qualquer chamada passe.

Não deixe o agente clicar nele. A documentação diz que os agentes precisam de autorização explícita do usuário antes de aceitar termos, que regem como você pode usar dados pessoais. Adicione uma linha ao seu CLAUDE.md: "Se uma chamada retornar THIRD_PARTY_DATA_TERMS_REQUIRED, pare e me mostre requiresAction.url."

Leia o payload alexandria[].data

Os resultados voltam em um array alexandria, uma entrada por chamada de ferramenta, com o payload do provedor em data. O HTTP bruto envolve todo o resultado do SDK em um data de nível superior, então em uma resposta curl o match do Apollo fica em data.alexandria[0].data.person:

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

Duas verificações mantêm linhas ruins fora do seu CRM:

1. Verifique cada resultado em busca de erros antes de ler data. A documentação diz isso explicitamente; uma única chamada pode falhar enquanto a requisição HTTP é bem-sucedida.
2. Trate e-mails de placeholder como ausentes. O Apollo observa que um e-mail não revelado pode voltar como o literal email_not_unlocked@domain.com, mesmo quando email_status diz verificado.

Para o People Data Labs, a pessoa fica sob data dentro do resultado, ao lado de status e likelihood do envelope.

Envie feedback e receba um crédito de volta

Alexandria te paga por feedback. Cada envio reembolsa 1 crédito por qualquer avaliação, limitado por dia UTC a 10 créditos por site e 100 por equipe. Você tem 20 minutos a partir da última chamada Alexandria da sua equipe; depois disso você recebe FEEDBACK_WINDOW_EXPIRED.

Da CLI, execute firecrawl alexandria feedback (veja --help para as opções). Via MCP, o agente chama firecrawl_feedback com endpoint: "alexandria". Uma linha de prompt funciona bem: "Se um resultado parecer errado ou vazio, envie feedback ao Alexandria descrevendo-o."

Deixe o Claude Code proteger essas chamadas com o Apidog CLI

Quando um script depende de people/search retornar um id que people/match aceita, um campo renomeado o quebra silenciosamente. Seu agente pode transformar as chamadas deste guia em um cenário de regressão no Apidog CLI e executá-lo em uma agenda. Você escreve um prompt.

Configure a CLI e sua skill de agente uma vez:

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

Então dê ao Claude Code este 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 <projectId> 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.

O agente lê cada esquema de payload, valida-o e então executa comandos como estes:

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

Cada execução completa custa 30 créditos pelo match, então agende-a diariamente em vez de a cada commit. A referência do apidog run lista as flags de relatório e iteração, e Apidog CLI no Claude Code mostra a configuração com mais profundidade. O plano Free do Apidog cobre até 4 usuários.

Perguntas frequentes

A API de pessoas do Firecrawl Alexandria é gratuita? A descoberta é gratuita, e o Apollo people/search mostrou 0 créditos em 4 de novembro de 2026. Revelar uma pessoa custa créditos: 30 para o Apollo people/match e 60 para o People Data Labs person/enrich. O plano Free inclui 1.000 créditos por mês sem cartão.

Preciso de contas separadas do Apollo ou do People Data Labs? Não. O Alexandria executa ambos através da sua chave de API do Firecrawl e cobra em créditos do Firecrawl. Um administrador da organização precisa aceitar os termos de cada provedor uma vez, que é o que THIRD_PARTY_DATA_TERMS_REQUIRED pede.

Por que minha resposta de people/match mostra email_not_unlocked@domain.com? Esse é o placeholder do Apollo para um e-mail que não foi revelado. Trate-o como indisponível, mesmo que email_status diga verificado.

O Codex ou o Cursor podem executar isso em vez do Claude Code? Sim. npx -y firecrawl-cli@latest init --all configura cada agente detectado, e as ferramentas MCP funcionam em qualquer cliente MCP. As chamadas curl funcionam sem nenhum agente.

Como evito pagar por matches errados? Pesquise antes de fazer o match, faça o match pelo id do Apollo em vez de por nome, e defina min_likelihood para 6 ou mais no People Data Labs. O Apollo não cobra por um erro, e um 404 do PDL é gratuito.