Free100Leads

API

Zuletzt aktualisiert 19 August 2026

Einen Schlüssel bekommen

Schlüssel entstehen in deinem Konto und werden einmal angezeigt. Wir speichern einen Hash, also kann ihn später niemand nachschlagen, wir auch nicht. Verloren heißt neu anlegen. Widerruf wirkt sofort.

Ein Schlüssel sieht so aus: f100_live_…. Das Präfix ist fest, damit Secret-Scanner ihn erkennen, falls er je in ein öffentliches Repository gerät. Behandle ihn wie ein Passwort: nur serverseitig, nie im Browser, nie in einer Mobile-App.

Eine Anfrage stellen

Alles lebt unter https://api.free100leads.com/v1. Schick den Schlüssel als Bearer-Token.

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

Suchen

GET /v1/search braucht mindestens eines von country, industry_id oder size_bucket. Dieselbe Untergrenze wie auf der Website: alles auf einmal lässt sich nicht anfragen.

Parameter	Meaning
country	ISO-3166 alpha-2, e.g. DE
region	US state name, lowercase. Only meaningful with country=US
industry_id	From /v1/facets
size_bucket	1 (1-10) through 8 (10001+)
contact	email or phone, to require that channel
title	Job title contains this text
limit	Up to 500 a page
cursor	From the previous response

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

Blättern, und warum es keine Seitenzahl gibt

Behalte den next_cursor und gib ihn zurück, um weiterzumachen. Innerhalb einer Suche bekommst du nie denselben Datensatz zweimal, bis exhausted true zurückkommt.

Der Cursor ist signiert und an dein Konto und die exakten Filter gebunden. Einer für eine deutsche Suche wird bei einer französischen abgelehnt, einer für ein fremdes Konto bei deinem. Eine neue Suche beginnst du, indem du ihn weglässt.

Es gibt absichtlich keinen Abruf per id und keinen offset-Parameter. Beides ließe jemanden die ganze Datenbank parallel abgehen, genau das verhindert dieses Design.

Die übrigen Endpoints

Endpoint	What it gives you
GET /v1/facets	Every country, industry and size you can filter on, with counts
GET /v1/usage	Records used and left this period, and today
GET /v1/me	Which key this is, which plan, and its limits

Denselben Kontakt nicht zweimal verkauft bekommen

Zwei verschiedene Dinge verhindern, dass ein Datensatz dich zweimal erreicht.

Innerhalb einer Suche ist der Cursor die Garantie. Der Gang führt nur vorwärts, also kann das Blättern keinen schon gelieferten Datensatz noch mal liefern, egal wie viele Seiten du nimmst. Es verlangt nichts außer der Rückgabe von next_cursor .

Über Exporte hinweg ist ein Register die Garantie. Jede Zeile, die als CSV hinausgeht, wird deinem Konto zugeschrieben. Spätere Exporte überspringen sie, und /v1/search liefert sie nicht mehr: Ein bereits mitgenommener Kontakt taucht zwei Monate später nicht wieder in einer Suche auf und landet nicht zum zweiten Mal in deinem CRM.

Datensätze zählen bei der Lieferung gegen deinen Plan: am Bildschirm, in einer API-Antwort oder in einer Massendatei. Das Unterdrückungsregister füllen Exporte, keine Suchen. Der Massen-Endpoint überspringt registrierte Datensätze immer.

Ein Datensatz kommt ins Register, wenn er als Datei hinausgeht, nicht wenn er in einer Suchantwort erscheint. Innerhalb einer Suche garantiert der Cursor keine Wiederholungen. Über zwei Suchen mit überlappenden Filtern kann ein gesehener, aber nie exportierter Datensatz wiederkommen. exhausted markiert das Ende einer Suche.

Das Register gehört dem Konto, nicht einem Schlüssel: Alle Schlüssel und die Web-App lesen und schreiben dasselbe, und es läuft nicht ab. Ein im März exportierter Datensatz ist im Dezember noch unterdrückt. Brauchst du eine verlorene Liste zurück, nimmt der CSV-Download deines Dashboards include_exported=true an, und das kostet nichts extra. Diese Datensätze wurden bei der ersten Lieferung gezählt.

Grenzen

Diese Zahlen stehen hier, damit du sie nie erst in der Produktion entdeckst.

Limit	Growth	Scale
Records a month	100,000	1,500,000
Records a day	10,000	50,000
Records an hour	5,000	25,000
Requests a minute	25	60
Requests in flight	2	4
Keys	3	10

Jede Antwort trägt RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset. Ein 429 trägt zusätzlich Retry-After in Sekunden. Gezählt werden die tatsächlich erhaltenen Datensätze, nie die angefragten.

Tagesgrenzen steigen in deiner ersten Woche bis zum vollen Tempo des Plans. Monatssummen werden nie gekürzt.

Fehler

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

Type	Status	What to do
invalid_request	400	Fix the parameters. Retrying unchanged will not help
unauthorized	401	The key is wrong, revoked or missing
quota_exhausted	402	Out of records. Deliberately not a 429, because backing off will not fix a billing state. Wait for the reset or upgrade
forbidden	403	The plan or the key does not carry this
not_found	404	No such endpoint or resource. Check the path
rate_limited	429	Slow down. Honour Retry-After
server_error	500	Ours. Retry with backoff, and tell us if it persists

Was du mit den Daten tun darfst

Datensätze sind für deine eigene Ansprache lizenziert. Nicht weiterverkaufen, nicht neu veröffentlichen, nicht in ein Produkt einbauen, das du verkaufst. Gelieferte Datensätze tragen nachverfolgbare Marker, die an den abrufenden Schlüssel gebunden sind: Eine Liste, die woanders auftaucht, lässt sich zum Ursprungskonto zurückverfolgen. Die AGB sagen das vollständig.

MCP

Richte Claude, Codex oder einen anderen MCP-fähigen Agenten auf https://api.free100leads.com/v1/mcp mit demselben Schlüssel. Er spricht JSON-RPC über HTTP und bietet drei Werkzeuge: search_leads, get_facets und get_usage. Sie führen denselben Code aus wie die Endpoints oben: Ein Agent bekommt dieselbe Zuteilung, dieselben Grenzen und dieselben Cursor-Regeln. Es gibt kein separates Kontingent zu verwalten.

Die meisten MCP-Clients verwenden einen Konfigurationsblock wie diesen, mit deinem eigenen Schlüssel anstelle des Platzhalters:

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

Webhooks

Speichere eine Suche, häng einen Endpoint an, und neue Treffer werden dorthin gepostet, sobald sie eintreffen. Jede Zustellung trägt x-f100-timestamp und x-f100-signature. Prüfe die Signatur gegen das beim Anlegen gezeigte Secret und weise alles ab, dessen Zeitstempel älter als fünf Minuten ist. Ein Empfänger, der unser POST nicht von fremden unterscheiden kann, hat einen offenen Endpoint.

Fehlschläge warten und versuchen es erneut. Zehn Fehlschläge in Folge schalten den Endpoint ab, und der Fehler erscheint auf deiner Kontoseite: Eine tote URL wird nicht ewig weiterprobiert.

Was absichtlich fehlt

Anreicherung, also eine Person per Email nachzuschlagen, gibt es nicht. Der direkte Abruf einer bestimmten Person würde das Anti-Missbrauchs-Design der ganzen API aushebeln.

Fehlt dir etwas? Das Kontaktformular erreicht einen Menschen.