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 에는 다음 중 최소 하나가 필요합니다: country, industry_id 또는 size_bucket. 웹사이트와 같은 최소 조건이며, 전부를 한 번에 요청할 방법은 없습니다.

{
  "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 파라미터도 일부러 없습니다. 둘 다 데이터베이스 전체를 병렬로 훑게 해 주는데, 그것이 바로 이 설계가 막는 것입니다.

나머지 엔드포인트

같은 연락처를 두 번 사지 않도록

레코드가 두 번 도착하는 것을 서로 다른 두 장치가 막습니다.

한 검색 안에서는 커서가 보증입니다. 순회는 앞으로만 가므로, 몇 페이지를 넘기든 이미 준 레코드를 다시 주지 않습니다. 필요한 것은 next_cursor 를 돌려보내는 것뿐입니다.

내보내기 사이에서는 장부가 보증입니다. CSV로 나간 모든 행은 계정에 기록됩니다. 이후 내보내기는 그 행을 건너뛰고, /v1/search 도 더는 반환하지 않습니다. 이미 가져간 연락처가 두 달 뒤 검색에 다시 나오거나 CRM에 두 번 들어가는 일은 없습니다.

레코드는 제공되는 순간 플랜에 집계됩니다: 화면, API 응답, 대량 파일 어디서든. 차단 장부는 내보내기가 채우며 검색은 채우지 않습니다. 대량 엔드포인트는 장부에 있는 레코드를 항상 건너뜁니다.

레코드는 파일로 나갈 때 장부에 적히고, 검색 응답에 나타날 때는 적히지 않습니다. 한 검색 안에서는 커서가 중복 없음을 보증합니다. 필터가 겹치는 두 검색 사이에서는, 보았지만 내보내지 않은 레코드가 다시 나올 수 있습니다. exhausted 가 검색의 끝을 표시합니다.

장부는 키가 아니라 계정에 속합니다. 모든 키와 웹 앱이 같은 장부를 읽고 쓰며, 만료되지 않습니다. 3월에 내보낸 레코드는 12월에도 차단된 상태입니다. 잃어버린 목록을 되찾아야 하면 대시보드의 CSV 다운로드가 include_exported=true를 받으며, 다시 과금되지 않습니다. 그 레코드들은 처음 제공될 때 이미 집계되었습니다.

제한

이 숫자들을 여기에 공개하는 이유는, 프로덕션에서야 알게 되는 일이 없게 하기 위해서입니다.

모든 응답에는 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"
  }
}

데이터로 할 수 있는 일

레코드는 당신 자신의 아웃리치용으로 허가됩니다. 재판매, 재게시, 판매하는 제품에 포함하는 것은 금지입니다. 제공된 레코드에는 가져간 키에 묶인 추적 가능한 마커가 있어, 다른 곳에 나타난 목록은 출처 계정까지 추적됩니다. 전문은 약관 에 있습니다.

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_..." }
    }
  }
}

웹훅

검색을 저장하고 엔드포인트를 붙이면, 새 매칭이 도착하는 대로 그리로 POST됩니다. 모든 전달에는 x-f100-timestamp 및 x-f100-signature가 실립니다. 엔드포인트를 만들 때 표시된 시크릿으로 서명을 검증하고, 타임스탬프가 5분 넘게 지난 것은 거부하세요. 우리 POST와 남의 POST를 구분 못 하는 수신부는 열린 엔드포인트입니다.

실패는 물러섰다가 재시도합니다. 열 번 연속 실패하면 엔드포인트가 꺼지고 오류가 계정 페이지에 표시됩니다. 죽은 URL이 영원히 두드려지는 일은 없습니다.

일부러 없는 것

보강, 즉 이메일로 사람을 찾는 기능은 제공하지 않습니다. 특정 개인의 직접 조회는 API 전체의 남용 방지 설계를 무너뜨립니다.

필요한 것이 없나요? 문의 양식 이 사람에게 닿습니다.