Pesquise contactos, diretamente a partir do seu agente.

Visão geral

A API da B2BLeads é um único endpoint de descoberta compatível com MCP. URL base:

https://api.b2bleadsapi.com

Todas as respostas são em JSON. Não é necessário nenhum SDK — pedidos HTTPS simples funcionam a partir de qualquer linguagem ou da chamada de ferramentas nativa de um agente de IA.

Autenticação

Transmita a sua chave de API como token de portador (bearer token). Crie chaves a partir do painel, em Chaves de API.

Authorization: Bearer b2bl-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Os pedidos sem uma chave válida devolvem 401 Unauthorized. Cada chave tem um limite de taxa por minuto e está limitada pela quota de pesquisa mensal do seu plano.

GET /v1/search-leads

Encontra empresas que correspondam ao seu próprio vocabulário de pesquisa — opções claras e criadas para o efeito, em vez de campos de pedido de baixo nível. É necessário pelo menos um de q, industry ou city.

Parâmetros da consulta

Exemplo de pedido

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"

Exemplo de resposta

{
  "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..."
}

Envie de volta nextPageToken como page_token para obter a página seguinte. É null quando já não há mais resultados.

Nota para agentes de IA: em planos com Email Finder, o campo email de um contacto guardado pode ser devolvido como a cadeia literal CFD* em vez de um endereço. Isto significa que todas as tentativas de extração (um pedido HTTP simples, seguido de um recurso a navegador headless) foram bloqueadas pela proteção anti-bot da Cloudflare do site de destino — não se trata de um resultado vazio nem de um erro, e repetir no mesmo site não terá sucesso. Trate CFD* como "sem e-mail disponível" e não como um endereço real, e não o comunique ao utilizador final como sendo o seu e-mail de contacto.

Experimente ao vivo

GET /v1/search-leads/industries

Endpoint público, sem autenticação — devolve a lista atual de valores industry suportados, para que os clientes e agentes nunca precisem de os codificar de forma fixa.

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

Experimente ao vivo

Erros

Os erros são JSON simples com um único campo error.

Limites de taxa e quota

Cada chave de API tem um limite de taxa por minuto e uma quota de pesquisa mensal, ambos definidos pelo seu plano. Consulte a utilização atual a qualquer momento na página Faturação do painel, ou através do endpoint GET /v1/billing se estiver autenticado com um token de sessão.

Utilizá-lo como ferramenta MCP

Disponibilizamos um servidor MCP oficial que encapsula esta API em cinco ferramentas — search_leads, list_industries, list_saved_lists, get_saved_list e find_email — para Claude Desktop, Claude Code, Cursor, ChatGPT, Gemini/Antigravity, Grok Build, GitHub Copilot e qualquer outro cliente compatível com MCP. Não é necessária nenhuma integração REST manual.

Adicione-o à configuração do seu cliente MCP com uma chave de API a partir do Chaves de API:

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

Prefere configurá-lo você mesmo através de REST simples? Os parâmetros acima correspondem diretamente ao esquema de entrada da ferramenta — o agente escolhe um setor e uma cidade em linguagem natural, e a B2BLeads trata de traduzir isso numa consulta de descoberta em tempo real nos bastidores.

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

Uma ferramenta separada trata de pesquisas exaustivas a uma cidade inteira — mas com um aviso explícito de custo elevado para que os agentes não a chamem por predefinição:

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

Mais ferramentas só de leitura completam a superfície 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á disponível em qualquer plano pago (a partir do Starter) — o mesmo nível que já enriquece automaticamente os resultados de search_leads com e-mails. Sem um plano ativo, a chave recebe simplesmente um erro de "atualização necessária" em vez de um resultado.