Free100Leads

API

Última actualización 19 August 2026

Conseguir una clave

Las claves se crean en tu cuenta y se muestran una sola vez. Guardamos un hash, así que nadie puede consultarla después, ni nosotros. Si la pierdes, creas otra. La revocación es inmediata.

Una clave se ve así: f100_live_…. Ese prefijo es fijo para que los escáneres de secretos la reconozcan si llega a un repositorio público. Trátala como una contraseña: solo en el servidor, nunca en un navegador ni en una app móvil.

Hacer una petición

Todo vive bajo https://api.free100leads.com/v1. Envía la clave como token bearer.

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

Buscar

GET /v1/search necesita al menos uno de country, industry_id o size_bucket. Es el mismo mínimo que tiene la web: no hay forma de pedirlo todo.

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

Paginación, y por qué no hay número de página

Guarda el next_cursor y devuélvelo para continuar. Nunca recibes el mismo registro dos veces dentro de una búsqueda, hasta que exhausted vuelve en true.

El cursor va firmado y ligado a tu cuenta y a los filtros exactos que usaste. Uno emitido para una búsqueda alemana se rechaza en una francesa, y uno emitido a otra cuenta se rechaza en la tuya. Empieza una búsqueda nueva omitiéndolo.

Deliberadamente no hay forma de pedir un registro por id, ni parámetro offset. Ambos permitirían recorrer toda la base en paralelo, que es justo lo que este diseño evita.

Los demás endpoints

No comprar el mismo contacto dos veces

Dos cosas distintas impiden que un registro te llegue dos veces.

Dentro de una búsqueda, el cursor es la garantía. El recorrido solo avanza, así que paginar una búsqueda no puede devolverte un registro que ya te dio, por muchas páginas que tomes. No te pide nada más que devolver next_cursor .

Entre exportaciones, un libro de registro es la garantía. Cada fila que sale como CSV queda anotada en tu cuenta. Las exportaciones siguientes la omiten, y /v1/search deja de devolverla, así que un contacto que ya te llevaste no reaparece en una búsqueda dos meses después, ni cae en tu CRM por segunda vez.

Los registros cuentan contra tu plan cuando se entregan: en pantalla, en una respuesta de la API o en un archivo masivo. El libro de supresión se llena con exportaciones, no con búsquedas. El endpoint masivo siempre omite registros ya anotados.

Un registro se anota cuando sale como archivo, no cuando aparece en una respuesta de búsqueda. Dentro de una búsqueda, el cursor garantiza que no hay repetidos. Entre dos búsquedas con filtros solapados, un registro que viste pero nunca exportaste puede volver. exhausted marca el final de una búsqueda.

El libro pertenece a la cuenta, no a una clave, así que todas las claves y la web leen y escriben el mismo, y no caduca: un registro exportado en marzo sigue suprimido en diciembre. Si necesitas recuperar una lista perdida, la descarga CSV de tu panel acepta include_exported=true, y eso no te cobra de nuevo. Esos registros se contaron la primera vez que se entregaron.

Límites

Estos números se publican aquí para que nunca los descubras en producción.

Cada respuesta lleva RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Un 429 además lleva Retry-After en segundos. El uso cuenta los registros que recibiste de verdad, nunca los que pediste.

Los límites diarios suben hasta el ritmo completo del plan durante tu primera semana. Los totales mensuales nunca se reducen.

Errores

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

Qué puedes hacer con los datos

Los registros se licencian para tu propia prospección. No los revendas, no los republiques ni los metas en un producto que vendas. Los registros entregados llevan marcas trazables ligadas a la clave que los obtuvo, así que una lista que aparezca en otro sitio se puede rastrear hasta la cuenta de origen. Los términos lo detallan por completo.

MCP

Apunta Claude, Codex o cualquier otro agente compatible con MCP a https://api.free100leads.com/v1/mcp con la misma clave. Habla JSON-RPC sobre HTTP y ofrece tres herramientas: search_leads, get_facets y get_usage. Ejecutan el mismo código que los endpoints de arriba, así que un agente tiene la misma cuota, los mismos límites y las mismas reglas de cursor. No hay una cuota aparte que vigilar.

La mayoría de los clientes MCP usan un bloque de configuración como este, con tu propia clave en vez del marcador:

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

Webhooks

Guarda una búsqueda, adjunta un endpoint y los nuevos resultados se publican allí según llegan. Cada entrega lleva x-f100-timestamp y x-f100-signature. Comprueba la firma con el secreto mostrado al crear el endpoint, y rechaza cualquier entrega con más de cinco minutos de antigüedad. Un receptor que no distingue nuestro POST de cualquier otro tiene un endpoint abierto.

Los fallos esperan y reintentan. Diez fallos seguidos apagan el endpoint y el error aparece en tu página de cuenta, así una URL muerta deja de reintentarse para siempre.

Lo que falta a propósito

No ofrecemos enriquecimiento, es decir, buscar a una persona por su email. Consultar a un individuo concreto desharía el diseño antiabuso de toda la API.

¿Te falta algo? El formulario de contacto llega a una persona.