Trova contatti, direttamente dal tuo agente.

Panoramica

L'API di B2BLeads è un unico endpoint di discovery compatibile con MCP. URL di base:

https://api.b2bleadsapi.com

Ogni risposta è in formato JSON. Non è richiesto alcun SDK — semplici richieste HTTPS funzionano da qualsiasi linguaggio o dal tool-calling nativo di un agente AI.

Autenticazione

Passa la tua chiave API come bearer token. Crea le chiavi dalla dashboard, alla voce Chiavi API.

Authorization: Bearer b2bl-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Le richieste senza una chiave valida restituiscono 401 Unauthorized. Ogni chiave ha un limite di frequenza al minuto ed è soggetta alla quota di ricerca mensile del tuo piano.

GET /v1/search-leads

Trova aziende in base al tuo vocabolario di ricerca — opzioni pulite e mirate anziché campi di richiesta di basso livello. È richiesto almeno uno tra q, industry o city.

Parametri della query

Esempio di richiesta

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"

Esempio di risposta

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

Restituisci nextPageToken come page_token per recuperare la pagina successiva. Diventa null quando non ci sono più risultati.

Nota per gli agenti AI: sui piani con Email Finder, il campo email di un contatto salvato può restituire la stringa letterale CFD* invece di un indirizzo. Questo significa che ogni tentativo di scraping (una richiesta HTTP semplice, poi un fallback con browser headless) è stato bloccato dalla protezione anti-bot Cloudflare del sito di destinazione — non è un risultato vuoto né un errore, e ritentare sullo stesso sito non avrà successo. Considera CFD* come "email non disponibile" anziché come un indirizzo reale, e non riportarlo all'utente finale come sua email di contatto.

Provalo dal vivo

GET /v1/search-leads/industries

Endpoint pubblico e non autenticato — restituisce l'elenco attuale dei valori industry supportati, così client e agenti non devono mai codificarli manualmente.

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

Provalo dal vivo

Errori

Gli errori sono in JSON semplice con un unico campo error.

Limiti di frequenza e quota

Ogni chiave API ha un limite di frequenza al minuto e una quota di ricerca mensile, entrambi definiti dal tuo piano. Controlla l'utilizzo attuale in qualsiasi momento dalla pagina Fatturazione della dashboard, oppure tramite l'endpoint GET /v1/billing se sei autenticato con un token di sessione.

Usarlo come strumento MCP

Pubblichiamo un server MCP ufficiale che incapsula questa API in cinque strumenti — search_leads, list_industries, list_saved_lists, get_saved_list e find_email — per Claude Desktop, Claude Code, Cursor, ChatGPT, Gemini/Antigravity, Grok Build, GitHub Copilot e qualsiasi altro client compatibile con MCP. Nessuna integrazione REST manuale necessaria.

Aggiungilo alla configurazione del tuo client MCP con una chiave API dalla pagina Chiavi API:

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

Preferisci collegarlo tu stesso via REST puro? I parametri sopra corrispondono direttamente allo schema di input dello strumento — l'agente sceglie un settore e una città in linguaggio naturale, e B2BLeads si occupa di tradurlo in una query di discovery live dietro le quinte.

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

Uno strumento separato gestisce ricerche esaustive sull'intera città — con un avviso esplicito di costo elevato affinché gli agenti non lo richiamino per impostazione predefinita:

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

Altri strumenti di sola lettura completano 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 è disponibile su qualsiasi piano a pagamento (da Starter in su) — lo stesso livello che già arricchisce automaticamente i risultati di search_leads con le email. Senza un piano attivo, la chiave riceve semplicemente un errore "upgrade required" invece di un risultato.