Free100Leads

API

Ultimo aggiornamento 19 August 2026

Ottenere una chiave

Le chiavi si creano nel tuo account e si mostrano una volta sola. Conserviamo un hash, quindi nessuno può ritrovarla dopo, noi compresi. Persa, ne crei un’altra. La revoca è immediata.

Una chiave somiglia a f100_live_…. Il prefisso è fisso perché gli scanner di segreti la riconoscano se finisce in un repository pubblico. Trattala come una password: solo lato server, mai in un browser, mai in un’app mobile.

Fare una richiesta

Tutto vive sotto https://api.free100leads.com/v1. Manda la chiave come token bearer.

curl "https://api.free100leads.com/v1/search?country=DE&industry_id=4&limit=100" \
  -H "Authorization: Bearer f100_live_..."

Cercare

GET /v1/search richiede almeno uno tra country, industry_id o size_bucket. È lo stesso minimo del sito: non c’è modo di chiedere tutto.

{
  "data": [
    {
      "name": "…",
      "job_title": "…",
      "company": "…",
      "email": "…",
      "phone": "…",
      "city": "…",
      "region": null,
      "country": "DE",
      "industry": "computer software",
      "company_size": "51-200"
    }
  ],
  "next_cursor": "c_…",
  "exhausted": false,
  "usage": { "records_used": 4210, "records_included": 100000, "period_end": "…" }
}

La paginazione, e perché non c’è un numero di pagina

Conserva il next_cursor e ripassalo per continuare. Non ricevi mai lo stesso record due volte in una ricerca, finché exhausted non torna true.

Il cursore è firmato e legato al tuo account e ai filtri esatti usati. Uno emesso per una ricerca tedesca viene rifiutato in una francese, e uno emesso a un altro account viene rifiutato nel tuo. Ometterlo avvia una ricerca nuova.

Di proposito non c’è modo di prendere un record per id, né un parametro offset. Entrambi permetterebbero di percorrere l’intero database in parallelo, esattamente ciò che questo design impedisce.

Gli altri endpoint

Non farsi vendere lo stesso contatto due volte

Due cose diverse impediscono a un record di raggiungerti due volte.

Dentro una ricerca, il cursore è la garanzia. Il percorso va solo in avanti: sfogliare una ricerca non può restituire un record già consegnato, per quante pagine tu prenda. Non chiede altro che ripassare next_cursor .

Tra un export e l’altro, un registro è la garanzia. Ogni riga che esce come CSV viene annotata sul tuo account. Gli export successivi la saltano, e /v1/search smette di restituirla: un contatto già portato via non riappare in una ricerca due mesi dopo, e non finisce nel tuo CRM una seconda volta.

I record contano sul piano alla consegna: a schermo, in una risposta API o in un file in blocco. Il registro di soppressione si riempie con gli export, non con le ricerche. L’endpoint in blocco salta sempre i record già annotati.

Un record entra nel registro quando esce come file, non quando appare in una risposta di ricerca. Dentro una ricerca, il cursore garantisce l’assenza di ripetizioni. Tra due ricerche con filtri sovrapposti, un record visto ma mai esportato può tornare. exhausted segna la fine di una ricerca.

Il registro appartiene all’account, non a una chiave: tutte le chiavi e l’app web leggono e scrivono lo stesso, e non scade. Un record esportato a marzo è ancora soppresso a dicembre. Se ti serve recuperare una lista persa, il download CSV della dashboard accetta include_exported=true, e non ti addebita di nuovo. Quei record sono stati contati alla prima consegna.

Limiti

Questi numeri sono pubblicati qui perché tu non li scopra mai in produzione.

Ogni risposta porta RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Un 429 porta anche Retry-After in secondi. L’uso conta i record davvero ricevuti, mai quelli richiesti.

I limiti giornalieri salgono al pieno ritmo del piano nella tua prima settimana. I totali mensili non vengono mai ridotti.

Errori

{
  "error": {
    "type": "rate_limited",
    "message": "60 requests a minute is the limit on this plan.",
    "retry_after": 12,
    "docs": "https://free100leads.com/docs/api#rate_limited"
  }
}

Cosa puoi fare con i dati

I record sono licenziati per il tuo outreach. Non rivenderli, non ripubblicarli, non incorporarli in un prodotto che vendi. I record consegnati portano marcatori tracciabili legati alla chiave che li ha scaricati: una lista che spunta altrove si può risalire all’account d’origine. I termini lo dicono per intero.

MCP

Punta Claude, Codex o un altro agente compatibile con MCP a https://api.free100leads.com/v1/mcp con la stessa chiave. Parla JSON-RPC su HTTP e offre tre strumenti: search_leads, get_facets e get_usage. Eseguono lo stesso codice degli endpoint sopra: un agente ha la stessa quota, gli stessi limiti e le stesse regole di cursore. Non c’è una quota separata da seguire.

La maggior parte dei client MCP usa un blocco di configurazione come questo, con la tua chiave al posto del segnaposto:

{
  "mcpServers": {
    "free100leads": {
      "url": "https://api.free100leads.com/v1/mcp",
      "headers": { "Authorization": "Bearer f100_live_..." }
    }
  }
}

Webhook

Salva una ricerca, collega un endpoint, e i nuovi risultati vi vengono postati appena arrivano. Ogni consegna porta x-f100-timestamp e x-f100-signature. Verifica la firma con il segreto mostrato alla creazione dell’endpoint e rifiuta tutto ciò che ha più di cinque minuti. Un ricevitore che non distingue il nostro POST da un altro ha un endpoint aperto.

I fallimenti attendono e riprovano. Dieci fallimenti consecutivi spengono l’endpoint e l’errore appare sulla pagina del tuo account: una URL morta smette di essere ritentata per sempre.

Cosa manca di proposito

L’arricchimento, cioè cercare una persona per email, non è offerto. La consultazione diretta di un individuo disferebbe il design anti-abuso dell’intera API.

Ti manca qualcosa? Il modulo di contatto arriva a una persona.