Cómo encontrar y enriquecer leads con Claude Code

La API de personas de Firecrawl Alexandria permite a tu agente de programación encontrar y enriquecer personas mediante una sola clave de Firecrawl. Descubres herramientas gratis con v2/search, listas candidatos con Apollo people/search a 0 créditos, revelas uno con Apollo people/match a 30 créditos, o enriqueces un correo electrónico conocido con People Data Labs person/enrich a 60 créditos. Cada llamada pasa por POST /v2/scrape.

Cada paso a continuación aparece dos veces: un prompt para Claude Code (o Codex) y el curl sin procesar, para que puedas automatizarlo sin un agente.

Qué es la API de personas de Firecrawl Alexandria

Alexandria es la biblioteca de proveedores de datos de terceros de Firecrawl, accesible con la clave de API que ya usas para el scraping. Según la documentación de Alexandria, descubres una herramienta, inspeccionas sus entradas y su precio, y luego la ejecutas con scrape. El descubrimiento es gratis; la ejecución cuesta los créditos indicados en la herramienta.

La categoría People contiene 12 proveedores. Dos de ellos cubren la mayor parte del trabajo de prospección:

Proveedor	Capacidad	Créditos por llamada	Qué envías	Qué obtienes
Apollo	`people/search`	0	`person_titles`, `q_keywords`, `q_organization_domains_list`, `per_page` (máx. 100)	Vistas previas: nombre, apellido enmascarado, cargo, empresa, `has_email`, `id` de Apollo
Apollo	`people/match`	30	`id` de la búsqueda, o `linkedin_url`, `email`, o `name` más `domain`	Una persona resuelta con cargo, historial y datos de contacto
People Data Labs	`person/enrich`	60	`email`, `profile`, `pdl_id` y otros; un nombre sin más datos devuelve un 400	Un registro completo de la persona más `likelihood` (1 a 10)

Los precios son los que se muestran junto al botón Run en la página de Apollo y la página de People Data Labs el 4 de noviembre de 2026. La página de Apollo también dice que un fallo de people/match “no devuelve ninguna persona y no se factura”.

Cuánto cuesta una búsqueda de personas en dólares

El valor de un crédito depende de tu plan. Según la página de precios de Firecrawl, Hobby cuesta $19 al mes por 5,000 créditos y Standard cuesta $99 al mes por 100,000 créditos, ambos con facturación mensual.

Llamada	Créditos	Hobby ($0.0038/crédito)	Standard ($0.00099/crédito)
Búsqueda de descubrimiento o 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

Las cuentas: $19 / 5,000 = $0.0038 por crédito, y $99 / 100,000 = $0.00099. Buscar 100 vistas previas y revelar las 20 mejores cuesta 600 créditos, lo que cabe dentro de los 1,000 mensuales del plan Free. People Data Labs también te limita a 50,000 llamadas API al año por organización, compartidas entre los endpoints de persona y empresa, incluyendo reintentos.

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

Paso 1: Conecta Claude Code a Firecrawl

La ruta más rápida es el instalador de agentes de Firecrawl. Añade las habilidades de Firecrawl a cada agente de programación que detecta y te inicia sesión a través del navegador:

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

Reinicia tu agente después. De forma manual, es npm install -g firecrawl-cli y firecrawl login. Nuestra guía de Firecrawl CLI cubre ambos, y el recorrido de Firecrawl MCP cubre el servidor MCP, que expone el mismo bucle como firecrawl_search, firecrawl_find_tools y firecrawl_scrape.

Para los ejemplos de curl a continuación, exporta tu clave una vez:

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

Paso 2: Descubre las herramientas de personas gratis

Pregunta primero a tu agente, ya que el descubrimiento no cuesta 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.

En realidad, eso es una búsqueda con sources establecido solo en ["alexandria"]. Omitir "web" la mantiene gratis, porque los resultados web se facturan:

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

La respuesta lista tools clasificadas, cada una con un proveedor, una capacidad y una descripción. Para leer entradas y precios, el agente ejecuta find-tools:

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

Paso 3: Busca candidatos en Apollo a 0 créditos

La página de Apollo indica a los agentes que siempre empiecen aquí: es gratis y muestra quién existe antes de que gastes nada.

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.

La llamada sin procesar:

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 vista previa lleva un apellido enmascarado y un id de Apollo, la entrada más fiable para el siguiente paso.

Paso 4: Revela una persona con people/match

Ahora paga solo por las personas que vale la pena contactar, a 30 créditos por coincidencia:

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

Deja las dos flags de revelado desactivadas a menos que las necesites. La página de Apollo dice que un correo personal “cuesta extra” y que un número de teléfono es “sustancialmente más caro que la coincidencia base”.

Paso 5: Enriquece un correo conocido con People Data Labs

Cuando ya tienes un correo electrónico, por ejemplo de un registro entrante, person/enrich devuelve un perfil más completo: correo de trabajo, cargo, empresa, URL de LinkedIn, experiencia y 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 va de 1 a 10 con un valor predeterminado de 2. La página del proveedor plantea el equilibrio con claridad: un 404 “es gratis aquí y un registro incorrecto no lo es”. Súbelo antes de recorrer una lista.

Maneja THIRD_PARTY_DATA_TERMS_REQUIRED

Tu primera llamada de pago a un proveedor puede fallar con THIRD_PARTY_DATA_TERMS_REQUIRED. Según la documentación, el error incluye una requiresAction.url, y un administrador de la organización tiene que abrirla y aceptar los términos de ese proveedor antes de que se realice cualquier llamada.

No dejes que el agente haga clic en ella. La documentación dice que los agentes necesitan autorización explícita del usuario antes de aceptar términos, que rigen cómo puedes usar datos personales. Añade una línea a tu CLAUDE.md: “Si una llamada devuelve THIRD_PARTY_DATA_TERMS_REQUIRED, detente y muéstrame requiresAction.url.”

Lee el payload de alexandria[].data

Los resultados vuelven en un array alexandria, una entrada por llamada de herramienta, con el payload del proveedor bajo data. HTTP sin procesar envuelve todo el resultado del SDK en un data de nivel superior, así que en una respuesta de curl la coincidencia de Apollo está en data.alexandria[0].data.person:

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

Dos comprobaciones evitan que filas incorrectas entren en tu CRM:

Comprueba si hay errores en cada resultado antes de leer data. La documentación lo dice explícitamente; una sola llamada puede fallar mientras la solicitud HTTP tiene éxito.
Trata los correos de marcador de posición como ausentes. Apollo señala que un correo no revelado puede volver como el literal email_not_unlocked@domain.com, incluso cuando email_status dice verificado.

Para People Data Labs, la persona está bajo data dentro del resultado, junto al status y likelihood del envelope.

Envía feedback y recupera un crédito

Alexandria te paga por feedback. Cada envío reembolsa 1 crédito por cualquier valoración, con un límite por día UTC de 10 créditos por sitio web y 100 por equipo. Tienes 20 minutos desde la última llamada a Alexandria de tu equipo; después de eso recibes FEEDBACK_WINDOW_EXPIRED.

Desde la CLI, ejecuta firecrawl alexandria feedback (consulta --help para las opciones). Por MCP, el agente llama a firecrawl_feedback con endpoint: "alexandria". Una línea de prompt funciona bien: “Si un resultado parece incorrecto o vacío, envía feedback a Alexandria describiéndolo.”

Deja que Claude Code proteja estas llamadas con Apidog CLI

Una vez que un script depende de que people/search devuelva un id que people/match acepte, un campo renombrado lo rompe silenciosamente. Tu agente puede convertir las llamadas de esta guía en un escenario de regresión en Apidog CLI y ejecutarlo según una programación. Tú escribes un prompt.

Configura la CLI y su skill de agente una 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

Luego dale a 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.

El agente lee el esquema de cada payload, lo valida y luego ejecuta comandos como estos:

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

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

Cada ejecución completa cuesta 30 créditos por la coincidencia, así que prográmala a diario en lugar de en cada commit. La referencia de apidog run lista las flags de informe e iteración, y Apidog CLI en Claude Code muestra la configuración con más profundidad. El plan Free de Apidog cubre hasta 4 usuarios.

Preguntas frecuentes

¿La API de personas de Firecrawl Alexandria es gratis? El descubrimiento es gratis, y Apollo people/search mostraba 0 créditos el 4 de noviembre de 2026. Revelar una persona cuesta créditos: 30 para Apollo people/match y 60 para People Data Labs person/enrich. El plan Free incluye 1,000 créditos al mes sin tarjeta.

¿Necesito cuentas separadas de Apollo o People Data Labs? No. Alexandria ejecuta ambos a través de tu clave de API de Firecrawl y factura en créditos de Firecrawl. Un administrador de la organización sí necesita aceptar los términos de cada proveedor una vez, que es lo que pide THIRD_PARTY_DATA_TERMS_REQUIRED.

¿Por qué mi respuesta de people/match muestra email_not_unlocked@domain.com? Ese es el marcador de posición de Apollo para un correo que no se reveló. Trátalo como no disponible, incluso si email_status dice verificado.

¿Pueden Codex o Cursor ejecutar esto en lugar de Claude Code? Sí. npx -y firecrawl-cli@latest init --all configura cada agente detectado, y las herramientas MCP funcionan en cualquier cliente MCP. Las llamadas de curl funcionan sin ningún agente.

¿Cómo evito pagar por coincidencias incorrectas? Busca antes de hacer match, haz match por id de Apollo en lugar de por nombre, y establece min_likelihood en 6 o más en People Data Labs. Apollo no factura un fallo, y un 404 de PDL es gratis.