Free100Leads

API

最近更新 19 August 2026

获取密钥

密钥在你的账户里创建，只显示一次。我们只保存哈希，之后没有人能查到它，包括我们。丢了就再建一个。吊销立即生效。

密钥形如 f100_live_…。前缀固定，这样如果它出现在公开仓库里，密钥扫描器能认出来。把它当密码对待：只放服务器端，不进浏览器，不进移动应用。

发起请求

一切都在 https://api.free100leads.com/v1之下。密钥作为 bearer token 发送。

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

搜索

GET /v1/search 至少需要以下之一: country, industry_id 或 size_bucket。与网站相同的底线: 没有办法一次要走全部。

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

分页，以及为什么没有页码

保存 next_cursor 并在下次请求带回即可继续。同一次搜索里你不会拿到重复记录，直到 exhausted 返回 true。

游标经过签名，绑定你的账户和当时的筛选条件。为德国搜索签发的游标在法国搜索里会被拒绝，别人账户的游标在你这里也会被拒绝。省略它就是开始新搜索。

刻意没有按 id 取记录的方式，也没有 offset 参数。两者都会让人并行遍历整个数据库，而这正是本设计要阻止的。

其他端点

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

同一个联系人不会卖你两次

有两套机制阻止一条记录到你手里两次。

同一次搜索内，游标是保证。 游走只向前，无论翻多少页，都不会返回已给过你的记录。你只需要把 next_cursor 传回来。

跨导出之间，台账是保证。 每一行以 CSV 形式离开时都记入你的账户。之后的导出会跳过它， /v1/search 也不再返回它。已经拿走的联系人不会在两个月后的搜索里再次出现，也不会第二次进你的 CRM。

记录在交付时计入方案额度: 屏幕上、API 响应里或批量文件中。抑制台账由导出填写，搜索不写入。批量端点总是跳过已在台账中的记录。

记录在以文件形式离开时写入台账，出现在搜索响应里时不写。一次搜索内游标保证不重复。两次筛选条件重叠的搜索之间，看过但没导出的记录可能再次出现。 exhausted 标记一次搜索的结束。

台账属于账户而不是密钥，所有密钥和网页端读写同一份，而且永不过期: 三月导出的记录十二月依然被抑制。如果丢了名单需要找回，仪表板的 CSV 下载接受 include_exported=true，且不会再次计费。那些记录在第一次交付时已计数。

限制

这些数字公布在这里，就是为了让你不必在生产环境里才发现它们。

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

每个响应都带有 RateLimit-Limit, RateLimit-Remaining 和 RateLimit-Reset。429 还会带上 Retry-After （单位为秒）。用量按你实际收到的记录计数，不按你请求的数量。

每日上限在你的第一周内逐步升到方案的完整速率。每月总量从不缩减。

错误

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

数据的允许用途

记录仅授权用于你自己的外联。不得转售、再发布，或打包进你出售的产品。交付的记录带有与取数密钥绑定的可追溯标记，出现在别处的名单可以追回到来源账户。完整规定见条款。

MCP

把 Claude、Codex 或其他支持 MCP 的代理指向 https://api.free100leads.com/v1/mcp ，使用同一把密钥。它通过 HTTP 讲 JSON-RPC，提供三个工具: search_leads, get_facets 和 get_usage。它们运行与上述端点相同的代码，代理获得相同的额度、相同的速率限制和相同的游标规则。没有需要另外盯着的配额。

大多数 MCP 客户端使用类似这样的配置块，把占位符换成你自己的密钥:

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

Webhooks

保存一个搜索，挂上一个端点，新的匹配一到就会推送过去。每次投递都带有 x-f100-timestamp 和 x-f100-signature。用创建端点时显示的密钥校验签名，拒绝时间戳超过五分钟的投递。分不清我们的 POST 和别人的接收端，就是一个开放端点。

失败会退避重试。连续十次失败会关闭端点，错误显示在你的账户页上，死掉的 URL 不会被永远重试。

刻意缺失的功能

不提供富化，即按邮箱查人。直接查询特定个人会破坏整个 API 的反滥用设计。

缺少你需要的东西？联系表单能联系到真人。