PushLeads Logo
PushLeadsAPI Documentation

Introducción

Primeros PasosAutenticaciónManejo de Errores

Endpoints

ContactosListasCampañasEmail API

API de PushLeads

v1.0

Integra PushLeads con tus sistemas para automatizar la gestión de contactos, listas y campañas de marketing multicanal.

REST API
JSON Response

Primeros Pasos

La API de PushLeads te permite integrar funcionalidades de marketing multicanal directamente en tus aplicaciones. Todos los endpoints están disponibles en:

https://app.pushleads.co/api/v1

Antes de comenzar

Necesitas una cuenta de PushLeads y una API Key.Genera tu API Key aquí

Autenticación

Todas las peticiones a la API deben incluir tu API Key. Puedes autenticarte de dos formas:

Opción 1: Header Authorization (Recomendado)

curl -X GET "https://app.pushleads.co/api/v1/contacts" \
  -H "Authorization: Bearer pk_live_tu_api_key_aqui"

Opción 2: Header X-API-Key

curl -X GET "https://app.pushleads.co/api/v1/contacts" \
  -H "X-API-Key: pk_live_tu_api_key_aqui"

Manejo de Errores

La API utiliza códigos de estado HTTP estándar para indicar el resultado de las peticiones.

CódigoDescripción
200Petición exitosa
201Recurso creado exitosamente
400Petición inválida - revisa los parámetros
401No autorizado - API Key inválida o faltante
403Prohibido - sin permisos para este recurso
404Recurso no encontrado
500Error interno del servidor

Formato de Error

{
  "error": "Descripción del error",
  "code": "ERROR_CODE"
}

Contactos

GET/api/v1/contacts

Obtiene la lista de contactos del workspace.

Parámetros de Query

ParámetroTipoDescripción
pagenumberPágina (default: 1)
limitnumberContactos por página (default: 50, max: 100)
searchstringBuscar por nombre, email o teléfono

Ejemplo

curl -X GET "https://app.pushleads.co/api/v1/contacts?page=1&limit=20" \
  -H "Authorization: Bearer pk_live_tu_api_key"

Respuesta

{
  "contacts": [
    {
      "id": "uuid",
      "name": "Juan Pérez",
      "email": "juan@email.com",
      "phone": "+573001234567",
      "company": "Empresa SA",
      "status": "active",
      "source": "api",
      "created_at": "2025-01-06T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
POST/api/v1/contacts

Crea un nuevo contacto.

Body (JSON)

CampoTipoRequeridoDescripción
namestring*Nombre del contacto
emailstring-Correo electrónico
phonestring-Teléfono con código de país
companystring-Empresa
positionstring-Cargo
birthDatestring-Fecha de nacimiento (YYYY-MM-DD)
tagsstring[]-Etiquetas
customFieldsobject-Campos personalizados

Ejemplo

curl -X POST "https://app.pushleads.co/api/v1/contacts" \
  -H "Authorization: Bearer pk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "María García",
    "email": "maria@empresa.com",
    "phone": "+573001234567",
    "company": "TechCorp",
    "tags": ["lead", "premium"],
    "customFields": {
      "origen": "website"
    }
  }'
GET/api/v1/contacts/:id

Obtiene los detalles de un contacto específico.

Ejemplo

curl -X GET "https://app.pushleads.co/api/v1/contacts/uuid-del-contacto" \
  -H "Authorization: Bearer pk_live_tu_api_key"

Listas

GET/api/v1/lists

Obtiene todas las listas del workspace.

Ejemplo

curl -X GET "https://app.pushleads.co/api/v1/lists" \
  -H "Authorization: Bearer pk_live_tu_api_key"

Respuesta

{
  "lists": [
    {
      "id": "uuid",
      "name": "Clientes VIP",
      "description": "Clientes premium",
      "color": "#3B82F6",
      "contactCount": 150,
      "created_at": "2025-01-06T12:00:00Z"
    }
  ]
}
POST/api/v1/lists

Crea una nueva lista de contactos.

Body (JSON)

CampoTipoRequeridoDescripción
namestring*Nombre de la lista
descriptionstring-Descripción de la lista
colorstring-Color en hexadecimal (#3B82F6)

Ejemplo

curl -X POST "https://app.pushleads.co/api/v1/lists" \
  -H "Authorization: Bearer pk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Leads Webinar",
    "description": "Registrados al webinar de enero",
    "color": "#10B981"
  }'
GET/api/v1/lists/:id

Obtiene los detalles de una lista específica.

Parámetros de Query

ParámetroTipoDescripción
includeContactsbooleanIncluir contactos de la lista (default: false)

Ejemplo

curl -X GET "https://app.pushleads.co/api/v1/lists/uuid-lista?includeContacts=true" \
  -H "Authorization: Bearer pk_live_tu_api_key"
POST/api/v1/lists/:id/contacts

Agrega contactos a una lista existente.

Body (JSON)

CampoTipoDescripción
contactIdsstring[]Array de IDs de contactos existentes

Ejemplo

curl -X POST "https://app.pushleads.co/api/v1/lists/uuid-lista/contacts" \
  -H "Authorization: Bearer pk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["uuid-contacto-1", "uuid-contacto-2"]
  }'

Campañas

GET/api/v1/campaigns

Obtiene todas las campañas del workspace.

Parámetros de Query

ParámetroTipoDescripción
typestringFiltrar por tipo: email, sms
statusstringFiltrar por estado: draft, scheduled, sending, sent
POST/api/v1/campaigns Email

Crea una campaña de email marketing.

Body (JSON)

CampoTipoRequeridoDescripción
typestring*"email"
namestring*Nombre de la campaña
subjectstring*Asunto del email
htmlContentstring*Contenido HTML del email
fromNamestring*Nombre del remitente
fromEmailstring*Email del remitente
listIdstring*ID de la lista de contactos

Ejemplo

curl -X POST "https://app.pushleads.co/api/v1/campaigns" \
  -H "Authorization: Bearer pk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "name": "Newsletter Enero",
    "subject": "¡Novedades de enero!",
    "htmlContent": "<h1>Hola {{name}}</h1><p>Contenido...</p>",
    "fromName": "Mi Empresa",
    "fromEmail": "noreply@miempresa.com",
    "listId": "uuid-lista"
  }'
POST/api/v1/campaigns SMS

Crea una campaña de SMS.

Body (JSON)

CampoTipoRequeridoDescripción
typestring*"sms"
namestring*Nombre de la campaña
messagestring*Contenido del SMS (max 160 caracteres)
senderIdstring-ID del sender (nombre o número)
listIdstring*ID de la lista de contactos

Ejemplo

curl -X POST "https://app.pushleads.co/api/v1/campaigns" \
  -H "Authorization: Bearer pk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "name": "Promo Flash",
    "message": "Hola {{name}}, 50% OFF solo hoy. Visita mitienda.com",
    "listId": "uuid-lista"
  }'
POST/api/v1/campaigns/:id/send

Envía una campaña existente a todos los contactos de su lista.

Importante

Esta acción es irreversible. Asegúrate de revisar la campaña antes de enviarla.

Ejemplo

curl -X POST "https://app.pushleads.co/api/v1/campaigns/uuid-campana/send" \
  -H "Authorization: Bearer pk_live_tu_api_key"

Respuesta

{
  "success": true,
  "message": "Campaign sending started",
  "campaignId": "uuid-campana",
  "totalRecipients": 150,
  "status": "sending"
}

Email API

Envio directo de emails unitarios y masivos

Ideal para integraciones externas

Usa este endpoint para enviar codigos OTP, notificaciones transaccionales o correos masivos desde cualquier sistema externo. Los destinatarios se guardan automaticamente como contactos.

POST/api/v1/email/sendRequiere: email:send o campaigns:write

Envia uno o mas correos electronicos directamente sin necesidad de crear una campana. Soporta envio de codigos OTP, templates del workspace o HTML/texto personalizado.

Body (JSON)

CampoTipoRequeridoDescripcion
tostring | object | array*Email o array de emails/objetos. Max 1000 destinatarios.
"{email, name?, firstName?, lastName?, phone?}"
subjectstring*Asunto del email
htmlstring*Contenido HTML del correo
textstring*Contenido en texto plano
templateIdstring*ID de un template existente en el workspace
otpobject*Objeto OTP: {code, expiresInMinutes?, appName?}
fromstring-Email del remitente (default: noreply@pushleads.co)
fromNamestring-Nombre del remitente
replyTostring-Email de respuesta
variablesobject-Variables personalizadas para {{key}}
tagsstring[]-Etiquetas para el envio
saveAsContactboolean-Guardar destinatario como contacto (default: true)
listIdstring-Agregar contacto a esta lista
sourcestring-Origen del contacto (ej: "mi-app", "zapier")

Nota: Debes incluir al menos uno de: html, text, templateId o otp.

Ejemplo 1: Enviar codigo OTP

curl -X POST "https://app.pushleads.co/api/v1/email/send" \
  -H "Authorization: Bearer pk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "usuario@email.com",
    "subject": "Tu codigo de verificacion",
    "otp": {
      "code": "847291",
      "expiresInMinutes": 10,
      "appName": "Mi Aplicacion"
    }
  }'

Ejemplo 2: Email unitario con HTML

curl -X POST "https://app.pushleads.co/api/v1/email/send" \
  -H "Authorization: Bearer pk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "email": "maria@empresa.com",
      "firstName": "Maria",
      "lastName": "Garcia"
    },
    "subject": "Bienvenida, {{firstName}}!",
    "html": "<h1>Hola {{nombre}}</h1><p>Gracias por registrarte.</p>",
    "from": "noreply@midominio.com",
    "fromName": "Mi Empresa",
    "tags": ["bienvenida", "onboarding"],
    "source": "registro-web"
  }'

Ejemplo 3: Envio masivo

curl -X POST "https://app.pushleads.co/api/v1/email/send" \
  -H "Authorization: Bearer pk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [
      {"email": "juan@email.com", "firstName": "Juan"},
      {"email": "maria@email.com", "firstName": "Maria"},
      "otro@email.com"
    ],
    "subject": "Oferta especial para ti, {{firstName}}",
    "templateId": "template_xxx",
    "variables": {
      "descuento": "30%",
      "url_oferta": "https://mitienda.com/promo"
    },
    "listId": "list_xxx",
    "tags": ["promo", "julio"]
  }'

Respuesta

{
  "success": true,
  "data": {
    "sent": 2,
    "failed": 1,
    "total": 3,
    "results": [
      {
        "email": "juan@email.com",
        "status": "sent",
        "contactId": "con_1234567_abc"
      },
      {
        "email": "maria@email.com",
        "status": "sent",
        "contactId": "con_1234568_def"
      },
      {
        "email": "otro@email.com",
        "status": "failed",
        "error": "SendGrid error 400: ..."
      }
    ]
  }
}
REFVariables de personalizacion

Puedes usar las siguientes variables en el subject, html y text. Se reemplazan automaticamente con los datos del destinatario.

VariableDescripcion
{{firstName}}Primer nombre
{{lastName}}Apellido
{{fullName}} / {{nombre}}Nombre completo
{{email}} / {{correo}}Correo electronico
{{phone}} / {{telefono}}Telefono
{{mi_variable}}Cualquier variable custom via el campo variables

Rate Limits

Para mantener la estabilidad del servicio, aplicamos límites de velocidad a las peticiones.

PlanLímiteVentana
Free100 peticionespor hora
Pro1,000 peticionespor hora
Enterprise10,000 peticionespor hora

¿Necesitas ayuda?

Nuestro equipo de soporte está disponible para ayudarte con la integración.

© 2025 PushLeads. Todos los derechos reservados.