API de PushLeads
v1.0
Integra PushLeads con tus sistemas para automatizar la gestión de contactos, listas y campañas de marketing multicanal.
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/v1Antes 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ódigo | Descripción |
|---|---|
200 | Petición exitosa |
201 | Recurso creado exitosamente |
400 | Petición inválida - revisa los parámetros |
401 | No autorizado - API Key inválida o faltante |
403 | Prohibido - sin permisos para este recurso |
404 | Recurso no encontrado |
500 | Error interno del servidor |
Formato de Error
{
"error": "Descripción del error",
"code": "ERROR_CODE"
}Contactos
/api/v1/contactsObtiene la lista de contactos del workspace.
Parámetros de Query
| Parámetro | Tipo | Descripción |
|---|---|---|
page | number | Página (default: 1) |
limit | number | Contactos por página (default: 50, max: 100) |
search | string | Buscar 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
}
}/api/v1/contactsCrea un nuevo contacto.
Body (JSON)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
name | string | * | Nombre del contacto |
email | string | - | Correo electrónico |
phone | string | - | Teléfono con código de país |
company | string | - | Empresa |
position | string | - | Cargo |
birthDate | string | - | Fecha de nacimiento (YYYY-MM-DD) |
tags | string[] | - | Etiquetas |
customFields | object | - | 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"
}
}'/api/v1/contacts/:idObtiene 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
/api/v1/listsObtiene 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"
}
]
}/api/v1/listsCrea una nueva lista de contactos.
Body (JSON)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
name | string | * | Nombre de la lista |
description | string | - | Descripción de la lista |
color | string | - | 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"
}'/api/v1/lists/:idObtiene los detalles de una lista específica.
Parámetros de Query
| Parámetro | Tipo | Descripción |
|---|---|---|
includeContacts | boolean | Incluir 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"/api/v1/lists/:id/contactsAgrega contactos a una lista existente.
Body (JSON)
| Campo | Tipo | Descripción |
|---|---|---|
contactIds | string[] | 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
/api/v1/campaignsObtiene todas las campañas del workspace.
Parámetros de Query
| Parámetro | Tipo | Descripción |
|---|---|---|
type | string | Filtrar por tipo: email, sms |
status | string | Filtrar por estado: draft, scheduled, sending, sent |
/api/v1/campaigns EmailCrea una campaña de email marketing.
Body (JSON)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
type | string | * | "email" |
name | string | * | Nombre de la campaña |
subject | string | * | Asunto del email |
htmlContent | string | * | Contenido HTML del email |
fromName | string | * | Nombre del remitente |
fromEmail | string | * | Email del remitente |
listId | string | * | 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"
}'/api/v1/campaigns SMSCrea una campaña de SMS.
Body (JSON)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
type | string | * | "sms" |
name | string | * | Nombre de la campaña |
message | string | * | Contenido del SMS (max 160 caracteres) |
senderId | string | - | ID del sender (nombre o número) |
listId | string | * | 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"
}'/api/v1/campaigns/:id/sendEnví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.
/api/v1/email/sendRequiere: email:send o campaigns:writeEnvia 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)
| Campo | Tipo | Requerido | Descripcion |
|---|---|---|---|
to | string | object | array | * | Email o array de emails/objetos. Max 1000 destinatarios."{email, name?, firstName?, lastName?, phone?}" |
subject | string | * | Asunto del email |
html | string | * | Contenido HTML del correo |
text | string | * | Contenido en texto plano |
templateId | string | * | ID de un template existente en el workspace |
otp | object | * | Objeto OTP: {code, expiresInMinutes?, appName?} |
from | string | - | Email del remitente (default: noreply@pushleads.co) |
fromName | string | - | Nombre del remitente |
replyTo | string | - | Email de respuesta |
variables | object | - | Variables personalizadas para {{key}} |
tags | string[] | - | Etiquetas para el envio |
saveAsContact | boolean | - | Guardar destinatario como contacto (default: true) |
listId | string | - | Agregar contacto a esta lista |
source | string | - | 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: ..."
}
]
}
}Variables de personalizacionPuedes usar las siguientes variables en el subject, html y text. Se reemplazan automaticamente con los datos del destinatario.
| Variable | Descripcion |
|---|---|
{{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.
| Plan | Límite | Ventana |
|---|---|---|
| Free | 100 peticiones | por hora |
| Pro | 1,000 peticiones | por hora |
| Enterprise | 10,000 peticiones | por hora |
¿Necesitas ayuda?
Nuestro equipo de soporte está disponible para ayudarte con la integración.
