Quickstart: Tu Primera Solicitud en 5 Minutos

Esta guía te llevará desde cero hasta obtener tu primer resultado con MasLeads API.

Prerrequisitos

  • Cuenta de MasLeads con plan Professional, Elite o Custom
  • API Key activa (cómo obtenerla en Autenticación)

Paso 1: Verifica tu API Key

Primero, comprobemos que tu API Key funciona:

curl -X GET "https://api.masleads.com/api/v1/usage" \
  -H "X-API-Key: sk_live_tu_api_key_aqui"

import requests

headers = {"X-API-Key": "sk_live_tu_api_key_aqui"}
response = requests.get(
    "https://api.masleads.com/api/v1/usage",
    headers=headers
)
print(response.json())

const response = await fetch("https://api.masleads.com/api/v1/usage", {
  headers: { "X-API-Key": "sk_live_tu_api_key_aqui" }
});
const data = await response.json();
console.log(data);

Respuesta esperada:

{
    "credits_available": 10086,
    "credits_limit_monthly": 1000,
    "credits_used_this_month": 0,
    "period_end": "2026-02-01T10:10:41.946954",
    "period_start": "2026-01-01T00:00:00",
    "plan": "standard"
}

Paso 2: Crea un Job

Envía leads para procesar. Puedes solicitar email o phone. No puedes solicitar ambos a la vez.

curl -X POST "https://api.masleads.com/api/v1/enrich/leads" \
  -H "X-API-Key: sk_live_tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "field": "email",
    "leads": [
      {
        "linkedin_url": "https://www.linkedin.com/in/johndue/",
        "external_id": "Lead-001"
      },
      {
        "linkedin_url": "https://www.linkedin.com/in/foobar/",
        "external_id": "Lead-002"
      }
    ],
    "webhook_url": "https://yourapp.com/webhooks/masleads"
  }'

import requests

headers = {
    "X-API-Key": "sk_live_tu_api_key_aqui",
    "Content-Type": "application/json"
}
payload = {
    "field": "email",
    "leads": [
        {"linkedin_url": "https://www.linkedin.com/in/johndue/", "external_id": "Lead-001"},
        {"linkedin_url": "https://www.linkedin.com/in/foobar/", "external_id": "Lead-002"}
    ],
    "webhook_url": "https://yourapp.com/webhooks/masleads"
}

response = requests.post(
    "https://api.masleads.com/api/v1/enrich/leads",
    headers=headers,
    json=payload
)
print(response.json())

const response = await fetch("https://api.masleads.com/api/v1/enrich/leads", {
  method: "POST",
  headers: {
    "X-API-Key": "sk_live_tu_api_key_aqui",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    field: "email",
    leads: [
      { linkedin_url: "https://www.linkedin.com/in/johndue/", external_id: "Lead-001" },
      { linkedin_url: "https://www.linkedin.com/in/foobar/", external_id: "Lead-002" }
    ],
    webhook_url: "https://yourapp.com/webhooks/masleads"
  })
});
const data = await response.json();
console.log(data);

Respuesta:

{
  "job_id": "job_e3351fb3e67a431da96d17dec9",
  "status": "pending",
  "field": "email",
  "total_leads": 2,
  "credits_charged": 2,
  "created_at": "2026-01-09T10:13:57.356979",
  "webhook_url": "https://yourapp.com/webhooks/masleads",
  "webhook_secret_set": false
}

Nota: El cobro total se realiza en el momento de crear el job. Los créditos por leads no encontrados se reembolsan automáticamente.

Paso 3: Consulta el Estado (Polling)

El procesamiento toma entre segundos y minutos. Consulta el estado:

curl -X GET "https://api.masleads.com/api/v1/jobs/job_e3351fb3e67a431da96d17dec9" \
  -H "X-API-Key: sk_live_tu_api_key_aqui"

Estados posibles:

Estado Significado
pending En cola, aún no procesado
processing Procesamiento en curso
completed Listo para descargar resultados
failed Error en el procesamiento

Respuesta cuando está en progreso:

{
  "job_id": "job_e3351fb3e67a431da96d17dec9",
  "status": "processing",
  "field": "email",
  "total_leads": 2,
  "leads_processed": 0,
  "leads_found": 0,
  "leads_not_found": 0,
  "leads_error": 0,
  "created_at": "2026-01-09T10:15:50",
  "updated_at": "2026-01-09T10:15:51",
  "completed_at": null
}

Respuesta cuando está completo:

{
  "job_id": "job_e3351fb3e67a431da96d17dec9",
  "status": "completed",
  "field": "email",
  "total_leads": 2,
  "leads_processed": 2,
  "leads_found": 1,
  "leads_not_found": 0,
  "leads_error": 1,
  "created_at": "2026-01-09T10:15:50",
  "updated_at": "2026-01-09T10:16:30",
  "completed_at": "2026-01-09T10:16:30"
}

Paso 4: Obtén los Resultados

Cuando status sea completed, descarga los datos. La respuesta es paginada:

curl -X GET "https://api.masleads.com/api/v1/jobs/job_e3351fb3e67a431da96d17dec9/results?page=1&per_page=50" \
  -H "X-API-Key: sk_live_tu_api_key_aqui"

Paginación

Los resultados se devuelven paginados para manejar jobs con muchos leads:

Parámetro Default Máximo Descripción
page 1 - Número de página
per_page 50 100 Leads por página

Si tu job tiene más leads que per_page, usa el campo pagination.total_pages para iterar:

# Página 1
curl "https://api.masleads.com/api/v1/jobs/{job_id}/results?page=1&per_page=50"

# Página 2
curl "https://api.masleads.com/api/v1/jobs/{job_id}/results?page=2&per_page=50"

Respuesta

{
  "job_id": "job_4d92187e7b144fafa8e21ad9f4",
  "status": "completed",
  "field": "email",
  "total_leads": 1,
  "results": {
    "found": 0,
    "not_found": 0,
    "error": 1
  },
  "credits": {
    "charged": 1,
    "refunded": 1,
    "net": 0
  },
  "leads": [
    {
      "external_id": "CRM-001",
      "linkedin_url": "https://www.linkedin.com/in/jquinterosmv2/",
      "status": "error",
      "error_code": "timeout",
      "result": null,
      "refunded": true,
      "request_uuid": "41e6636a-1ca4-407a-aec2-b10612795d5b"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_leads": 1,
    "total_pages": 1
  },
  "created_at": "2026-01-08T14:39:34",
  "completed_at": "2026-01-08T15:10:12"
}

Estados de leads

Status Descripción Crédito
found Email/teléfono encontrado Consumido
not_found No se encontró información Reembolsado
error Error de procesamiento (ver error_code) Reembolsado

Ejemplos de Código

Para ejemplos completos en Python, JavaScript y más, visita la sección de Ejemplos.

Próximos Pasos

Anterior: ← Introducción | Siguiente: Autenticación →