Free100Leads

API

Aktualizacja 19 August 2026

Jak zdobyć klucz

Klucze tworzysz w swoim koncie i pokazujemy je jeden raz. Przechowujemy skrót, więc nikt nie podejrzy go później, my również. Zgubisz — tworzysz nowy. Unieważnienie działa natychmiast.

Klucz wygląda tak: f100_live_…. Ten prefiks jest stały, żeby skanery sekretów rozpoznały go, gdyby kiedyś trafił do publicznego repozytorium. Traktuj go jak hasło: tylko po stronie serwera, nigdy w przeglądarce, nigdy w aplikacji mobilnej.

Wysyłanie żądania

Wszystko żyje pod adresem https://api.free100leads.com/v1. Klucz wysyłaj jako token bearer.

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

Wyszukiwanie

GET /v1/search wymaga co najmniej jednego z: country, industry_id lub size_bucket. To ten sam próg co na stronie: nie da się poprosić o wszystko.

{
  "data": [
    {
      "name": "…",
      "job_title": "…",
      "company": "…",
      "email": "…",
      "email_extrapolated": false,
      "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": "…" }
}

email_extrapolated jest prawdziwe, gdy adres został odgadnięty ze wzorca na podstawie imienia i firmy (na przykład [email protected]), a nie sprawdzony pod kątem dostarczalności. Zweryfikuj takie adresy przed wysyłką.

Stronicowanie i dlaczego nie ma numeru strony

Zachowaj next_cursor i odeślij go, aby kontynuować. W obrębie jednego wyszukiwania nigdy nie dostaniesz tego samego rekordu dwa razy, dopóki exhausted nie wróci jako true.

Kursor jest podpisany i przypisany do Twojego konta oraz do dokładnie tych filtrów, których użyłeś. Kursor wydany dla wyszukiwania niemieckiego zostanie odrzucony przy francuskim, a wydany innemu kontu — przy Twoim. Nowe wyszukiwanie zaczynasz, po prostu go pomijając.

Celowo nie ma sposobu, by pobrać rekord po identyfikatorze, ani parametru offset. Oba pozwoliłyby przejść całą bazę równolegle, a właśnie temu ten projekt ma zapobiegać.

Pozostałe endpointy

Jak nie kupić dwa razy tego samego kontaktu

Dwie różne rzeczy pilnują, by rekord nie trafił do Ciebie dwukrotnie.

W obrębie jednego wyszukiwania gwarancją jest kursor. Przejście idzie wyłącznie do przodu, więc stronicowanie nie odda rekordu, który już Ci wydało, niezależnie od liczby stron. Nie wymaga od Ciebie nic poza odesłaniem next_cursor z powrotem.

Między eksportami gwarancją jest rejestr. Każdy wiersz, który wychodzi jako wiersz CSV, jest zapisywany na Twoim koncie. Późniejsze eksporty go pomijają, a /v1/search przestaje go zwracać, więc kontakt, którego już sobie zabrałeś, nie pojawi się w wyszukiwaniu dwa miesiące później ani nie trafi drugi raz do Twojego CRM-u.

Rekordy liczą się do Twojego planu w chwili dostarczenia: na ekranie, w odpowiedzi API albo w pliku zbiorczym. Rejestr wykluczeń zapełniają eksporty, nie wyszukiwania. Endpoint zbiorczy zawsze pomija rekordy będące już w rejestrze.

Rekord trafia do rejestru, gdy wychodzi jako plik, a nie gdy pojawia się w odpowiedzi wyszukiwania. W obrębie jednego wyszukiwania kursor gwarantuje brak powtórek. Przy dwóch wyszukiwaniach o nakładających się filtrach rekord, który widziałeś, ale nigdy nie wyeksportowałeś, może wrócić. exhausted oznacza koniec wyszukiwania.

Rejestr należy do konta, a nie do klucza, więc każdy klucz i aplikacja webowa czytają i zapisują ten sam, a on nie wygasa: rekord wyeksportowany w marcu jest nadal wykluczony w grudniu. Jeśli po zgubieniu potrzebujesz listy z powrotem, pobranie CSV z panelu przyjmuje include_exported=true, i nie obciąża Cię ponownie. Te rekordy zostały policzone przy pierwszym dostarczeniu.

Limity

Publikujemy te liczby tutaj, żebyś nigdy nie odkrył ich na produkcji.

Każda odpowiedź niesie RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset. Odpowiedź 429 niesie też Retry-After w sekundach. Zużycie liczy rekordy, które faktycznie otrzymałeś, nigdy te, o które poprosiłeś.

Limity dzienne dochodzą do pełnego tempa planu w ciągu pierwszego tygodnia. Sumy miesięczne nigdy nie są obniżane.

Błędy

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

Co wolno robić z danymi

Rekordy są licencjonowane na Twój własny kontakt handlowy. Nie odsprzedawaj ich, nie publikuj ponownie i nie wplataj w sprzedawany produkt. Wydawane rekordy niosą znaczniki powiązane z kluczem, którym je pobrano, więc lista, która wypłynie gdzie indziej, da się doprowadzić z powrotem do konta, z którego pochodzi. Opisuje to w całości regulamin .

MCP

Skieruj Claude, Codex albo dowolnego agenta obsługującego MCP na https://api.free100leads.com/v1/mcp z tym samym kluczem. Mówi JSON-RPC po HTTP i udostępnia trzy narzędzia: search_leads, get_facets i get_usage. Uruchamiają ten sam kod co endpointy powyżej, więc agent dostaje ten sam limit, te same ograniczenia tempa i te same reguły kursora. Nie ma osobnej puli do pilnowania.

Większość klientów MCP przyjmuje blok konfiguracji taki jak ten, z Twoim własnym kluczem w miejscu wypełniacza:

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

Webhooki

Zapisz wyszukiwanie, podłącz endpoint, a nowe dopasowania będą do niego wysyłane, gdy tylko się pojawią. Każda dostawa niesie x-f100-timestamp i x-f100-signature. Sprawdź podpis względem sekretu pokazanego przy tworzeniu endpointu i odrzucaj wszystko ze znacznikiem czasu starszym niż pięć minut. Odbiornik, który nie odróżni naszego POST-a od cudzego, jest otwartym endpointem.

Nieudane dostawy są ponawiane z narastającym odstępem. Dziesięć porażek z rzędu wyłącza endpoint, a błąd pojawia się na stronie konta, więc martwy URL przestaje być ponawiany w nieskończoność.

Czego celowo nie ma

Nie oferujemy wzbogacania danych, czyli wyszukiwania osoby po adresie e-mail. Bezpośrednie odpytanie o konkretną osobę zniweczyłoby całą konstrukcję API chroniącą przed nadużyciami.

Brakuje Ci czegoś? Formularz formularz kontaktowy dociera do człowieka.