Free100Leads
API
最終更新 19 August 2026
キーの取得
キーはアカウントで作成され、一度だけ表示されます。保存するのはハッシュだけなので、後から確認することは誰にもできません。私たちにもです。失くしたら作り直し。無効化は即時です。
キーの形式は f100_live_…です。この接頭辞は固定で、公開リポジトリに漏れた場合にシークレットスキャナーが認識できます。パスワードと同じ扱いを: サーバー側のみ、ブラウザに置かない、モバイルアプリに埋め込まない。
リクエストの送り方
すべては https://api.free100leads.com/v1の下にあります。キーは bearer トークンとして送ります。
curl "https://api.free100leads.com/v1/search?country=DE&industry_id=4&limit=100" \ -H "Authorization: Bearer f100_live_..."
検索
GET /v1/search には次のうち少なくとも1つが必要です: 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 を保存し、次のリクエストで渡せば続きが取れます。1つの検索の中で同じレコードを二度受け取ることはありません。 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 |
同じ連絡先を二度買わされないために
レコードが二度届くのを、二つの別々の仕組みが防ぎます。
1つの検索の中では、カーソルが保証です。 歩みは前にしか進まないため、何ページめくっても、既に渡したレコードが再び返ることはありません。必要なのは next_cursor を返すことだけです。
エクスポートをまたぐ場合は、台帳が保証です。 CSV として出た行はすべてアカウントに記録されます。以後のエクスポートはそれを飛ばし、 /v1/search も返さなくなります。持ち出した連絡先が2か月後の検索に再登場することも、CRM に二度入ることもありません。
レコードは提供時にプランへ計上されます: 画面上、API 応答、一括ファイルのいずれでも。抑止台帳を埋めるのはエクスポートで、検索ではありません。一括エンドポイントは台帳にあるレコードを常に飛ばします。
レコードが台帳に書かれるのはファイルとして出たときで、検索応答に現れたときではありません。1つの検索内はカーソルが重複なしを保証します。フィルタが重なる2つの検索の間では、見たけれどエクスポートしていないレコードが再び現れることがあります。 exhausted が検索の終わりを示します。
台帳はキーではなくアカウントに属します。すべてのキーとウェブアプリが同じ台帳を読み書きし、期限もありません。3月にエクスポートしたレコードは12月も抑止されたままです。失くしたリストを取り戻したいときは、ダッシュボードの 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 が秒単位で付きます。使用量は実際に受け取ったレコードで数え、要求した数では数えません。
日次上限は最初の1週間でプランの本来の速度まで上がります。月間総量が減ることはありません。
エラー
{
"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 で、3つのツールを提供します: search_leads, get_facets と get_usage。上のエンドポイントと同じコードが動くため、エージェントの割当も、レート制限も、カーソルの規則も同じです。別枠のクォータはありません。
多くのMCPクライアントはこのような設定ブロックを使います。プレースホルダーの部分を自分のキーに置き換えてください:
{
"mcpServers": {
"free100leads": {
"url": "https://api.free100leads.com/v1/mcp",
"headers": { "Authorization": "Bearer f100_live_..." }
}
}
}Webhook
検索を保存してエンドポイントを付けると、新しい一致が届き次第そこへ POST されます。すべての配信には x-f100-timestamp と x-f100-signatureが付きます。エンドポイント作成時に表示されたシークレットで署名を検証し、タイムスタンプが5分より古いものは拒否してください。私たちの POST と他人の POST を見分けられない受け口は、開いたエンドポイントです。
失敗は間隔を空けて再試行されます。10回連続で失敗するとエンドポイントは停止し、エラーがアカウントページに表示されます。死んだ URL が永遠に叩かれ続けることはありません。
意図的にないもの
エンリッチメント、つまりメールアドレスから人を調べる機能は提供しません。特定個人の直接照会は、API 全体の不正対策設計を無効にしてしまいます。
必要なものが見つからない場合は お問い合わせフォーム が人につながります。