Free100EcommerceLeads
API
Laatst bijgewerkt 26 August 2026
Een sleutel krijgen
Sleutels maak je in je account aan en zie je één keer. Wij bewaren een hash, dus niemand kan er later een opzoeken, wij ook niet. Kwijt betekent een nieuwe. Intrekken werkt meteen.
Een sleutel ziet eruit als f100_live_…. Dat voorvoegsel ligt vast zodat secret scanners hem herkennen als hij ooit in een openbaar repository belandt. Behandel hem als een wachtwoord: alleen serverside, nooit in een browser, nooit in een mobiele app.
Een verzoek doen
Alles leeft onder https://api.free100ecommerceleads.com/v1. Stuur de sleutel mee als bearer token.
curl "https://api.free100ecommerceleads.com/v1/search?country=DE&industry_id=4&limit=100" \ -H "Authorization: Bearer f100_live_..."
Zoeken
GET /v1/search heeft er minstens één nodig van country, industry_id of size_bucket. Dat is dezelfde ondergrens als op de site: alles opvragen kan niet.
| 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 |
| exclude_extrapolated | true to hide pattern-guessed emails |
| cursor | From the previous response |
{
"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 is true wanneer het adres uit een patroon is afgeleid op basis van naam en bedrijf (zoals [email protected]) in plaats van op afleverbaarheid gecontroleerd. Verifieer deze voordat je verstuurt.
Pagineren, en waarom er geen paginanummer is
Bewaar de next_cursor en stuur hem terug om verder te gaan. Binnen één zoekopdracht krijg je nooit hetzelfde record twee keer, tot exhausted true teruggeeft.
De cursor is ondertekend en gebonden aan je account en aan precies de filters die je gebruikte. Eén die is uitgegeven voor een Duitse zoekopdracht wordt geweigerd bij een Franse, en één die aan een ander account is uitgegeven wordt geweigerd bij het jouwe. Een nieuwe zoekopdracht begin je door hem weg te laten.
Er is bewust geen manier om een record op id op te halen, en geen offsetparameter. Allebei zouden ze iemand in staat stellen de hele database parallel af te lopen, en precies daarvoor bestaat dit ontwerp.
De andere 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 |
Niet twee keer hetzelfde contact verkocht krijgen
Twee verschillende dingen zorgen dat een record je niet twee keer bereikt.
Binnen één zoekopdracht is de cursor de garantie. De wandeling gaat alleen vooruit, dus pagineren kan geen record teruggeven dat het je al gaf, hoeveel paginas je ook ophaalt. Het vraagt niets van je behalve het terugsturen van next_cursor .
Tussen exports is een grootboek de garantie. Elke rij die als CSV-rij vertrekt wordt op je account vastgelegd. Latere exports slaan hem over, en /v1/search geeft hem niet meer terug, zodat een contact dat je al hebt meegenomen niet twee maanden later opnieuw in een zoekopdracht opduikt en niet een tweede keer in je CRM belandt.
Records tellen mee voor je abonnement zodra ze geleverd zijn: op het scherm, in een API-respons of in een bulkbestand. Het blokkeergrootboek wordt gevuld door exports, niet door zoekopdrachten. Het bulkendpoint slaat records die al in het grootboek staan altijd over.
Een record komt in het grootboek zodra het als bestand vertrekt, niet zodra het in een zoekrespons verschijnt. Binnen één zoekopdracht garandeert de cursor geen herhalingen. Bij twee zoekopdrachten met overlappende filters kan een record dat je zag maar nooit exporteerde opnieuw langskomen. exhausted markeert het einde van een zoekopdracht.
Het grootboek hoort bij het account en niet bij een sleutel, dus elke sleutel en de webapp lezen en schrijven hetzelfde, en het verloopt niet: een record dat in maart is geëxporteerd blijft in december geblokkeerd. Heb je een lijst kwijt en wil je hem terug, dan accepteert de CSV-download op je dashboard include_exported=true, en dat kost je niets extra. Die records zijn geteld toen ze de eerste keer werden geleverd.
Limieten
Deze getallen staan hier zodat je ze nooit in productie hoeft te ontdekken.
| 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 |
Elke respons draagt RateLimit-Limit, RateLimit-Remaining en RateLimit-Reset. Een 429 draagt ook Retry-After in seconden. Het verbruik telt de records die je werkelijk kreeg, nooit de records die je vroeg.
Daglimieten groeien in je eerste week naar het volle tempo van het abonnement. Maandtotalen worden nooit verlaagd.
Fouten
{
"error": {
"type": "rate_limited",
"message": "60 requests a minute is the limit on this plan.",
"retry_after": 12,
"docs": "https://free100ecommerceleads.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 |
Wat je met de gegevens mag doen
Records zijn gelicentieerd voor je eigen benadering. Verkoop ze niet door, publiceer ze niet opnieuw en vouw ze niet in een product dat je verkoopt. Geleverde records dragen traceerbare markeringen die aan de sleutel hangen die ze ophaalde, dus een lijst die ergens anders opduikt is terug te voeren op het account waar hij vandaan kwam. De voorwaarden zetten dit volledig uiteen.
MCP
Richt Claude, Codex of een andere MCP-agent op https://api.free100ecommerceleads.com/v1/mcp met dezelfde sleutel. Hij spreekt JSON-RPC over HTTP en biedt drie tools: search_leads, get_facets en get_usage. Ze draaien dezelfde code als de endpoints hierboven, dus een agent krijgt hetzelfde tegoed, dezelfde limieten en dezelfde cursorregels. Er is geen apart quotum om bij te houden.
De meeste MCP-clients nemen een configuratieblok als dit, met je eigen sleutel op de plek van de placeholder:
{
"mcpServers": {
"ecommerceleads": {
"url": "https://api.free100ecommerceleads.com/v1/mcp",
"headers": { "Authorization": "Bearer f100_live_..." }
}
}
}Webhooks
Bewaar een zoekopdracht, hang er een endpoint aan, en nieuwe treffers worden erheen gepost zodra ze binnenkomen. Elke levering draagt x-f100-timestamp en x-f100-signature. Controleer de handtekening tegen het geheim dat je bij het aanmaken van het endpoint kreeg, en weiger alles met een tijdstempel ouder dan vijf minuten. Een ontvanger die onze POST niet van die van een ander kan onderscheiden, is een open endpoint.
Mislukkingen worden met oplopende tussenpozen opnieuw geprobeerd. Tien mislukkingen op rij zetten het endpoint uit en de fout verschijnt op je accountpagina, zodat een dode URL niet eeuwig opnieuw wordt geprobeerd.
Wat er bewust ontbreekt
Verrijking, oftewel iemand opzoeken op e-mailadres, bieden we niet aan. Een specifiek persoon rechtstreeks kunnen opvragen zou het hele antimisbruikontwerp van deze API ongedaan maken.
Mis je iets dat je nodig hebt? Het contactformulier bereikt een mens.