Free100Leads

API

Última atualização 19 August 2026

Conseguindo uma chave

As chaves são criadas na sua conta e mostradas uma vez. Guardamos um hash, então ninguém consegue consultá-la depois, nem nós. Perdeu, cria outra. A revogação é imediata.

Uma chave se parece com f100_live_…. O prefixo é fixo para que scanners de segredos a reconheçam se chegar a um repositório público. Trate como senha: só no servidor, nunca no navegador, nunca em app móvel.

Fazendo uma requisição

Tudo vive sob https://api.free100leads.com/v1. Envie a chave como token bearer.

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

Buscando

GET /v1/search precisa de pelo menos um entre country, industry_id ou size_bucket. É o mesmo piso do site: não há como pedir tudo.

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

Paginação, e por que não há número de página

Guarde o next_cursor e devolva-o para continuar. Você nunca recebe o mesmo registro duas vezes numa busca, até que exhausted volte como true.

O cursor é assinado e preso à sua conta e aos filtros exatos que você usou. Um emitido para uma busca alemã é recusado numa francesa, e um emitido para outra conta é recusado na sua. Comece uma busca nova omitindo-o.

De propósito não há como buscar um registro por id, nem parâmetro offset. Os dois permitiriam varrer a base inteira em paralelo, exatamente o que este design impede.

Os outros endpoints

Não comprar o mesmo contato duas vezes

Duas coisas diferentes impedem um registro de chegar duas vezes.

Dentro de uma busca, o cursor é a garantia. A varredura só anda para a frente, então paginar uma busca não devolve um registro que ela já entregou, por mais páginas que você pegue. Só exige devolver next_cursor .

Entre exportações, um livro-razão é a garantia. Cada linha que sai como CSV fica registrada na sua conta. Exportações futuras a pulam, e /v1/search para de devolvê-la, então um contato que você já levou não reaparece numa busca dois meses depois, nem cai no seu CRM de novo.

Registros contam contra o plano quando são entregues: na tela, numa resposta da API ou num arquivo em massa. O livro de supressão é preenchido por exportações, não por buscas. O endpoint em massa sempre pula registros já anotados.

Um registro entra no livro quando sai como arquivo, não quando aparece numa resposta de busca. Dentro de uma busca, o cursor garante que não há repetição. Entre duas buscas com filtros sobrepostos, um registro visto mas nunca exportado pode voltar. exhausted marca o fim de uma busca.

O livro pertence à conta, não a uma chave, então todas as chaves e o app web leem e escrevem o mesmo, e ele não expira: um registro exportado em março segue suprimido em dezembro. Se precisar recuperar uma lista perdida, o download CSV do seu painel aceita include_exported=true, e isso não cobra de novo. Esses registros foram contados na primeira entrega.

Limites

Estes números são publicados aqui para você nunca descobri-los em produção.

Toda resposta carrega RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Um 429 também carrega Retry-After em segundos. O uso conta os registros que você de fato recebeu, nunca os que pediu.

Os limites diários sobem até o ritmo pleno do plano na sua primeira semana. Totais mensais nunca são reduzidos.

Erros

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

O que você pode fazer com os dados

Os registros são licenciados para a sua própria prospecção. Não os revenda, não os republique nem os embuta num produto que você vende. Registros entregues carregam marcas rastreáveis ligadas à chave que os buscou, então uma lista que aparecer em outro lugar pode ser rastreada até a conta de origem. Os termos dizem isso por completo.

MCP

Aponte Claude, Codex ou qualquer outro agente compatível com MCP para https://api.free100leads.com/v1/mcp com a mesma chave. Ele fala JSON-RPC sobre HTTP e oferece três ferramentas: search_leads, get_facets e get_usage. Elas rodam o mesmo código dos endpoints acima, então um agente tem a mesma cota, os mesmos limites e as mesmas regras de cursor. Não há cota separada para acompanhar.

A maioria dos clientes MCP usa um bloco de configuração como este, com sua própria chave no lugar do marcador:

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

Webhooks

Salve uma busca, anexe um endpoint, e novos resultados são postados nele conforme chegam. Cada entrega carrega x-f100-timestamp e x-f100-signature. Verifique a assinatura contra o segredo mostrado na criação do endpoint e rejeite qualquer entrega com mais de cinco minutos. Um receptor que não distingue nosso POST de qualquer outro tem um endpoint aberto.

Falhas recuam e tentam de novo. Dez falhas seguidas desligam o endpoint e o erro aparece na página da sua conta, então uma URL morta para de ser tentada para sempre.

O que falta de propósito

Enriquecimento, ou seja, procurar uma pessoa pelo email, não é oferecido. A consulta direta de um indivíduo desfaria o design antiabuso da API inteira.

Falta algo que você precisa? O formulário de contato chega a uma pessoa.