API de LealUp

LealUp expone una REST API versionada para integración programática. Esta sección te deja productivo con la API en ~15 minutos.

Para quién es esta documentación

• Ingenieros de producto que quieren enviar eventos de uso para alimentar el health score.
• Equipos de ops que automatizan creación de clientes, asignación de ownership o sync desde sus sistemas.
• Partners integrando LealUp como parte de su stack (CRMs, plataformas de soporte, BI).

Si solo quieres usar LealUp desde la UI, no necesitas esto. Ve a Para CSMs o Para Admins.

Fundamentos

Entornos

LealUp ofrece dos entornos públicos:

• Producción (api.lealup.com) — datos reales, webhooks reales, SLA 99.9%, keys lealup_sk_live_*.
• Dev (api.dev.lealup.com) — para probar integraciones, keys lealup_sk_test_*.

Sobre el entorno dev:

• Sin SLA — best effort, puede caerse sin aviso durante deploys.
• Los datos pueden resetearse trimestralmente — no guardes nada que necesites conservar.
• Misma versión de API que producción (deployamos primero a dev).
• Datos aislados — cuentas, clientes y eventos de dev no existen en prod y viceversa.
• Ideal para: validar firmas de webhook, probar ingesta de eventos, desarrollar integraciones antes de ir a live.
• No ideal para: persistir data de QA de tu propio entorno, demos a clientes reales, load testing (límites más bajos).

Cada workspace puede emitir tanto keys live como test desde Admin → API → API Keys.

Mapa de recursos

La API cubre los recursos core de LealUp:

Clientes y contactos

• GET|POST /v1/customers — listar, crear.
• GET|PATCH|DELETE /v1/customers/{id} — detalle, editar, soft-delete.
• GET /v1/customers/{id}/contacts — contactos de un cliente.
• POST /v1/customers/bulk-import — import masivo (también via UI CSV).

Salud

• GET /v1/customers/{id}/health — score actual + dimensiones.
• GET /v1/customers/{id}/health/history — serie temporal (90 días).
• POST /v1/customers/{id}/health/recalculate — forzar recálculo.

Playbooks y tareas

• GET|POST /v1/playbooks — listar, crear.
• GET /v1/tasks — tareas (filtros: owner, status, due_date).
• PATCH /v1/tasks/{id} — actualizar status.
• POST /v1/tasks/{id}/complete — completar con resultado.

Eventos (ingesta)

• POST /v1/events — ingesta batch (hasta 1000 eventos por request).
• GET /v1/events — query de eventos (debugging).
• Ver Ingesta de eventos.

Usuarios y equipo

• GET|POST /v1/users — listar, invitar.
• GET /v1/users/me — perfil actual.
• PATCH /v1/users/{id}/role — cambiar rol (admin only).

Webhooks (outbound)

• GET|POST /v1/webhook-subscriptions — gestionar subscripciones salientes.
• Ver Webhooks.

Analytics y dashboards

• GET /v1/analytics/portfolio — resumen del portfolio.
• GET /v1/analytics/renewals — pipeline de renovaciones.
• GET /v1/dashboards/{id}/widgets — datos de dashboards custom.

Aislamiento de datos

Cada request está scopeado a tu cuenta de LealUp automáticamente:

• Con OAuth: el token incluye el identificador de tu cuenta (claim tenant_id en el JWT). Se resuelve sin que tengas que hacer nada.
• Con API key: la key pertenece a una sola cuenta, por lo que se infiere del header Authorization.

Los datos nunca cruzan cuentas por construcción. Si intentas GET /v1/customers/{id} con un id que pertenece a otra cuenta, devolvemos 404 (no 403, para no filtrar existencia).

En los JSON response verás el campo tenant_id — es el identificador técnico de tu cuenta, útil cuando reportas issues a soporte.

SDKs

• TypeScript — @lealup/sdk (npm). Tipos generados desde OpenAPI, zod validators incluidos.
• Python — lealup-sdk (PyPI). Async-first, Pydantic models.
• Go — en beta.
• Ruby, PHP, Java — no oficiales aún. Puedes generar desde OpenAPI con openapi-generator.

Siguientes pasos

1. Autenticación — obtener credenciales.
2. Quickstart — hello world en 5 min.
3. Endpoints — referencia por recurso.
4. Ingesta de eventos — alimentar health score.
5. Webhooks — recibir eventos salientes.

Soporte

• Spec completa: api.lealup.com/v1/openapi.json
• Status page: status.lealup.com
• Issues y requests: [email protected]
• Partners enterprise: canal dedicado Slack post-contrato.