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 |
WhatsApp API
Usa PushLeads como proveedor de mensajería para tu propio chatbot
Sin comisión por mensaje con la línea oficial
Con provider: "meta" el mensaje sale por la línea de WhatsApp Cloud API conectada en tu workspace y Meta cobra directo a tu cuenta de WhatsApp Business. PushLeads no agrega comisión por mensaje. Para que solo tu chatbot responda, deja la línea sin agente IA en Canales: la conversación queda en el inbox pero nadie contesta desde PushLeads.
/api/v1/messaging/resourcesRequiere: messaging:readDevuelve las líneas (metaPhoneNumberId para Meta, senderPhone para Twilio) y las plantillas aprobadas con sus variables. Copia de aquí los identificadores que usarás al enviar.
/api/v1/whatsapp/sendRequiere: whatsapp:send · Idempotency-KeyEnvía un mensaje individual. type: "text" solo funciona dentro de la ventana de 24 horas desde el último mensaje del cliente en esa línea (si no, responde 409 whatsapp_window_closed); fuera de ella usa type: "template" con una plantilla aprobada.
curl -X POST "https://app.pushleads.co/api/v1/whatsapp/send" \
-H "Authorization: Bearer pk_live_tu_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: reply-conv_123-0001" \
-d '{
"to": "+573001234567",
"provider": "meta",
"metaPhoneNumberId": "1098765432100",
"type": "text",
"text": "¡Hola! Soy el asistente de la tienda. ¿En qué te ayudo?"
}'
# Plantilla aprobada (fuera de la ventana de 24 h)
{
"to": "+573001234567",
"provider": "meta",
"metaPhoneNumberId": "1098765432100",
"type": "template",
"metaTemplateId": "1234567890",
"variables": { "1": "Ana", "2": "PED-123" },
"headerMediaUrl": "https://tu-cdn.com/factura.pdf"
}Respuesta 202 con data.id y status: "accepted". Los recibos posteriores (sent, delivered, read, failed) actualizan el mensaje y se avisan por el webhook message.status.
/api/v1/messages/:idRequiere: messages:readEstado actual del envío: processing, accepted, sent, delivered, read, failed o unknown, con deliveredAt, readAt, errorCode y errorMessage.
Plantillas de WhatsApp
Crea, consulta, sincroniza y elimina plantillas sin entrar al panel
| Método | Ruta | Permiso | Descripción |
|---|---|---|---|
| GET | /api/v1/whatsapp/templates | templates:read | Lista todas (filtros ?provider=meta|twilio, ?status=approved|pending|rejected|draft). |
| POST | /api/v1/whatsapp/templates | templates:write · Idempotency-Key | Crea la plantilla. Meta: entra en revisión de inmediato. Twilio: borrador y envío a aprobación (submit: false para solo guardar). |
| GET | /api/v1/whatsapp/templates/:id | templates:read | Consulta al proveedor el estado de aprobación y lo actualiza (?refresh=false para leer solo la copia local). |
| POST | /api/v1/whatsapp/templates/:id/submit | templates:write | Twilio: envía un borrador o una plantilla rechazada a aprobación. |
| POST | /api/v1/whatsapp/templates/sync | templates:write | Trae a PushLeads las plantillas que ya existen en tu WABA o cuenta de Twilio. |
| DELETE | /api/v1/whatsapp/templates/:id | templates:write | Elimina la plantilla (en Meta también se borra de la WABA, solo ese idioma). |
Crear una plantilla en la línea oficial (Meta)
curl -X POST "https://app.pushleads.co/api/v1/whatsapp/templates" \
-H "Authorization: Bearer pk_live_tu_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: tpl-confirmacion-pedido-v1" \
-d '{
"provider": "meta",
"metaPhoneNumberId": "1098765432100",
"name": "confirmacion_pedido",
"language": "es",
"category": "utility",
"headerText": "Pedido confirmado",
"body": "Hola {{1}}, tu pedido {{2}} fue confirmado. Te avisaremos cuando salga a reparto.",
"samples": ["Ana", "PED-123"],
"footerText": "Responde a este mensaje si necesitas ayuda",
"buttons": [{ "type": "URL", "title": "Ver pedido", "url": "https://tienda.com/pedidos" }]
}'Las variables del cuerpo deben ser consecutivas ({{1}}, {{2}}...) y samples les da un ejemplo a cada una (Meta lo exige para revisar). Encabezados multimedia: headerFormat IMAGE, VIDEO o DOCUMENT con headerMediaUrl HTTPS pública. La respuesta trae status (pending, approved, rejected) y metaTemplateId, que es el valor que usarás en /whatsapp/send. Suscríbete al evento template.status para enterarte de la aprobación sin consultar.
Webhooks
Recibe en tu servidor los mensajes entrantes y los recibos de entrega
Registra una URL HTTPS en Configuración → API keys → Webhooks o con la API (webhooks:manage). Cada evento llega como un POST JSON firmado. Un chatbot externo típico se suscribe a message.received, decide la respuesta y la envía con POST /api/v1/whatsapp/send usando la misma línea del evento.
| Evento | Cuándo | Campos principales de data |
|---|---|---|
message.received | Un cliente escribe a una línea de WhatsApp (Meta o Twilio) o SMS del workspace. | messageId, conversationId, contactId, channel, provider, line.metaPhoneNumberId / line.senderPhone, from.phone, from.name, text, messageType, media[], providerMessageId, timestamp, humanControlled |
message.status | El proveedor confirma sent, delivered, read o failed de un mensaje enviado por la API. | messageId, status, previousStatus, to, providerMessageId, errorCode, errorMessage, deliveredAt, readAt |
template.status | Meta aprueba, rechaza o pausa una plantilla de la línea oficial. | templateId, metaTemplateId, name, language, status, reason |
Ejemplo de entrega
POST https://tu-servidor.com/pushleads/webhook
Content-Type: application/json
X-PushLeads-Event: message.received
X-PushLeads-Delivery: whd_7f1c...
X-PushLeads-Signature: t=1763200000,v1=5f3a9c...
{
"id": "evt_1b2c...",
"type": "message.received",
"createdAt": "2026-11-15T10:00:00.000Z",
"workspaceId": "ws_abc",
"data": {
"messageId": "msg_1763200000_ab12cd",
"conversationId": "conv_...",
"contactId": "contact_...",
"channel": "whatsapp",
"provider": "meta",
"line": { "provider": "meta", "metaPhoneNumberId": "1098765432100", "senderPhone": null, "phone": "+573101234567" },
"from": { "phone": "+573001234567", "identity": null, "name": "Ana" },
"text": "Hola, ¿tienen envíos a Medellín?",
"messageType": "text",
"media": [],
"providerMessageId": "wamid.HBgM...",
"timestamp": "2026-11-15T09:59:58.000Z",
"humanControlled": true,
"isNewConversation": false
}
}Verificar la firma (Node.js)
import { createHmac, timingSafeEqual } from "node:crypto"
export function verifyPushLeads(secret, signatureHeader, rawBody) {
const parts = Object.fromEntries(signatureHeader.split(",").map(p => p.split("=")))
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t))
if (age > 300) return false
const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex")
return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(parts.v1, "hex"))
}- Responde 2xx en menos de 10 segundos y procesa en segundo plano. Cualquier otra respuesta o un timeout se reintenta tras 1, 5, 15, 60, 180, 360 y 720 minutos; el octavo fallo es definitivo.
- Usa el header
X-PushLeads-Deliverypara descartar duplicados si un reintento llega después de haber procesado la entrega original. - El secreto se muestra una sola vez al crear el webhook; puedes rotarlo desde el panel o con
PATCH /api/v1/webhooks/:idyrotateSecret: true. - Las entregas recientes, con código HTTP y error, se consultan en el panel o en
GET /api/v1/webhooks/:id/deliveries.POST /api/v1/webhooks/:id/testenvía un eventoping.
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.
