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 отмечает конец поиска.

Журнал принадлежит аккаунту, а не ключу: все ключи и веб-приложение читают и пишут один и тот же, и он не истекает. Запись, экспортированная в марте, подавлена и в декабре. Если нужно восстановить потерянный список, скачивание 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 с тем же ключом. Он говорит на JSON-RPC поверх HTTP и даёт три инструмента: search_leads, get_facets и get_usage. Они выполняют тот же код, что и эндпоинты выше: у агента та же квота, те же лимиты и те же правила курсора. Отдельной квоты, за которой нужно следить, нет.

Большинство MCP-клиентов используют такой блок конфигурации, с вашим собственным ключом вместо заполнителя:

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

Вебхуки

Сохраните поиск, привяжите эндпоинт, и новые совпадения будут отправляться туда по мере появления. Каждая доставка несёт x-f100-timestamp и x-f100-signature. Проверяйте подпись секретом, показанным при создании эндпоинта, и отклоняйте всё с меткой времени старше пяти минут. Приёмник, не отличающий наш POST от чужого, — это открытый эндпоинт.

Сбои ждут и повторяются. Десять сбоев подряд выключают эндпоинт, и ошибка появляется на странице аккаунта: мёртвый URL не дёргается вечно.

Чего нет намеренно

Обогащение, то есть поиск человека по email, не предлагается. Прямой запрос конкретного человека разрушил бы всю антизлоупотребительную конструкцию API.

Не хватает чего-то нужного? форму обратной связи доходит до человека.