Encuentra contactos, directamente desde tu agente.

Resumen

La API de B2BLeads es un único endpoint de descubrimiento compatible con MCP. URL base:

https://api.b2bleadsapi.com

Todas las respuestas son JSON. No se necesita ningún SDK — las solicitudes HTTPS simples funcionan desde cualquier lenguaje o desde el llamado a herramientas nativo de un agente de IA.

Autenticación

Envía tu clave de API como un token bearer. Crea claves desde el panel, en Claves API.

Authorization: Bearer b2bl-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Las solicitudes sin una clave válida devuelven 401 Unauthorized. Cada clave tiene un límite de solicitudes por minuto y una cuota mensual de búsquedas según tu plan.

GET /v1/search-leads

Encuentra empresas que coincidan con tu propio vocabulario de búsqueda — opciones claras y diseñadas para el caso de uso, en lugar de campos de bajo nivel. Se requiere al menos uno de q, industry o city.

Parámetros de consulta

Solicitud de ejemplo

curl "https://api.b2bleadsapi.com/v1/search-leads?industry=construction&city=Munich&radius_km=25&min_rating=4&has_website=true&open_now=true&rank_by=distance" \
  -H "Authorization: Bearer b2bl-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "results": [
    {
      "id": "ChIJ...",
      "name": "Bauunion GmbH",
      "address": "Landsberger Str. 12, 80339 München",
      "phone": "+49 89 1234567",
      "website": "https://bauunion.de",
      "rating": 4.7,
      "ratingCount": 128,
      "status": "OPERATIONAL",
      "priceLevel": null,
      "openNow": true
    }
  ],
  "nextPageToken": "AY1v..."
}

Devuelve nextPageToken como page_token para obtener la página siguiente. Es null cuando ya no hay más resultados.

Nota para agentes de IA: en los planes con Email Finder, el campo email de un contacto guardado puede devolver el texto literal CFD* en lugar de una dirección. Esto significa que todos los intentos de extracción (una solicitud HTTP simple y, después, un navegador sin interfaz como alternativa) fueron bloqueados por la protección contra bots de Cloudflare del sitio de destino — no es un resultado vacío ni un error, y volver a intentarlo con el mismo sitio no tendrá éxito. Trata CFD* como "correo no disponible" y no como una dirección real, y no lo muestres al usuario final como su correo de contacto.

Pruébalo en vivo

GET /v1/search-leads/industries

Endpoint público, sin autenticación — devuelve la lista actual de valores de industry admitidos, para que los clientes y agentes nunca necesiten codificarlos de forma fija.

curl "https://api.b2bleadsapi.com/v1/search-leads/industries"

{
  "industries": [
    { "value": "construction", "label": "Construction" },
    { "value": "restaurants", "label": "Restaurants" },
    { "value": "retail", "label": "Retail" },
    { "value": "manufacturing", "label": "Manufacturing" },
    { "value": "logistics", "label": "Logistics & Freight" },
    { "value": "it_services", "label": "IT Services" },
    { "value": "healthcare", "label": "Healthcare" },
    { "value": "real_estate", "label": "Real Estate" },
    { "value": "hospitality", "label": "Hospitality" },
    { "value": "professional_services", "label": "Professional Services" }
  ]
}

Pruébalo en vivo

Errores

Los errores son JSON simple con un único campo error.

Límites de uso y cuota

Cada clave de API tiene un límite de solicitudes por minuto y una cuota mensual de búsquedas, ambos definidos por tu plan. Consulta el uso actual en cualquier momento desde la página de Facturación del panel, o mediante el endpoint GET /v1/billing si estás autenticado con un token de sesión.

Usarlo como herramienta MCP

Publicamos un servidor MCP oficial que expone esta API como cinco herramientas — search_leads, list_industries, list_saved_lists, get_saved_list y find_email — para Claude Desktop, Claude Code, Cursor, ChatGPT, Gemini/Antigravity, Grok Build, GitHub Copilot y cualquier otro cliente compatible con MCP. No hace falta integración manual por REST.

Añádelo a la configuración de tu cliente MCP con una clave de API desde Claves API:

{
  "mcpServers": {
    "b2bleads": {
      "command": "npx",
      "args": ["-y", "b2bleads-mcp"],
      "env": {
        "B2BLEADS_API_KEY": "your-api-key-here"
      }
    }
  }
}

¿Prefieres integrarlo tú mismo por REST? Los parámetros anteriores se corresponden directamente con el esquema de entrada de la herramienta — el agente elige un sector y una ciudad en lenguaje natural, y B2BLeads se encarga de traducirlo en una consulta de descubrimiento en tiempo real.

{
  "name": "search_leads",
  "description": "Find companies by industry, city and radius",
  "parameters": {
    "q": "string, optional free-text query",
    "industry": "enum, see /v1/search-leads/industries",
    "city": "string",
    "radius_km": "number, max 50",
    "min_rating": "number 0-5",
    "has_website": "boolean",
    "verified_only": "boolean",
    "open_now": "boolean",
    "price_level": "enum, comma-separated: budget, moderate, expensive, luxury",
    "rank_by": "enum: relevance, distance (requires city)",
    "limit": "number 1-20",
    "page_token": "string, from a previous response's nextPageToken"
  }
}

Una herramienta independiente gestiona búsquedas exhaustivas en toda una ciudad, con una advertencia explícita de coste elevado para que los agentes no la invoquen por defecto:

{
  "name": "search_leads_advanced",
  "description": "⚠️ Elevated cost: 9x the quota of a single search_leads call. Tiles a city into a 3x3 grid of sub-searches to return up to ~180 deduplicated businesses in one city, beyond search_leads' normal ~20-60 result ceiling. Only use when more results are explicitly needed for one city — never as a default. Does not support pagination.",
  "parameters": {
    "q": "string, optional free-text query",
    "industry": "enum, see /v1/search-leads/industries",
    "city": "string, required — ONLY the city name, e.g. \"Lyon\" (not the full search query)",
    "min_rating": "number 0-5",
    "has_website": "boolean",
    "verified_only": "boolean",
    "open_now": "boolean",
    "price_level": "enum, comma-separated: budget, moderate, expensive, luxury"
  }
}

Otras herramientas de solo lectura completan la superficie MCP:

{
  "name": "list_industries",
  "description": "List the industry values accepted by search_leads",
  "parameters": {}
}

{
  "name": "list_saved_lists",
  "description": "List this account's saved lead lists",
  "parameters": {}
}

{
  "name": "get_saved_list",
  "description": "Get the leads saved in a specific list",
  "parameters": {
    "list_id": "string, required — from list_saved_lists"
  }
}

{
  "name": "find_email",
  "description": "Look up a best-effort contact email for a single business website",
  "parameters": {
    "website": "string, required, e.g. https://example.com"
  }
}

find_email está disponible en cualquier plan de pago (desde Starter) — el mismo nivel que ya enriquece automáticamente los resultados de search_leads con correos electrónicos. Sin un plan activo, la clave recibe simplemente un error de "se requiere actualizar el plan" en lugar de un resultado.