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ó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

GET/api/v1/contacts

Obtiene 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
  }
}

POST/api/v1/contacts

Crea 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"
    }
  }'

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)

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

GET/api/v1/lists/:id

Obtiene 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"

POST/api/v1/lists/:id/contacts

Agrega 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

GET/api/v1/campaigns

Obtiene 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

POST/api/v1/campaigns Email

Crea 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"
  }'

POST/api/v1/campaigns SMS

Crea 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"
  }'

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

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.

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

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

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

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

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

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

Campo

Tipo

Requerido

Descripción

name

string

Nombre de la lista

description

string

Descripción de la lista

color

string

Color en hexadecimal (#3B82F6)

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

Parámetro

Tipo

Descripción

includeContacts

boolean

Incluir contactos de la lista (default: false)

Campo

Tipo

Descripción

contactIds

string[]

Array de IDs de contactos existentes

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"] }'

Parámetro

Tipo

Descripción

type

string

Filtrar por tipo: email, sms

status

string

Filtrar por estado: draft, scheduled, sending, sent

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

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

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

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

Plan

Límite

Ventana

Free

100 peticiones

por hora

Pro

1,000 peticiones

por hora

Enterprise

10,000 peticiones

por hora