Endpoints

Referencia rápida de recursos — customers, health, playbooks, tasks, users, analytics.

Referencia rápida de los endpoints principales. La spec completa y autoritativa está en api.lealup.com/v1/openapi.json.

Convenciones

Todos los paths prefijados con /v1/.
Todos requieren Authorization: Bearer {token} — ver Autenticación.
POST/PATCH esperan Content-Type: application/json.
Respuestas son JSON (application/json) o application/problem+json en errores.
Paginación: cursor en query cursor=..., devuelve next_cursor y has_more.

Customers

`GET /v1/customers`

Lista clientes del workspace.

Query params:

status — active | trial | churned | paused (múltiples con coma).
owner_id — filtrar por owner.
segment_id — filtrar por segmento.
health_status — healthy | neutral | at_risk.
min_arr, max_arr — rango de ARR.
renewal_within_days — 30, 60, 90.
q — búsqueda full-text en nombre, email_domain.
limit — default 50, max 200.
cursor — paginación.

Respuesta:

{
  "data": [{"id": "...", "name": "...", ...}],
  "next_cursor": "eyJ...",
  "has_more": true
}

`POST /v1/customers`

Crea un cliente.

Body:

{
  "name": "Acme Corp",
  "email_domain": "acme.com",
  "arr": 145000,
  "owner_email": "[email protected]",
  "status": "active",
  "renewal_date": "2026-06-15",
  "custom_fields": {
    "tier": "Platinum",
    "industry": "Fintech"
  }
}

Headers recomendados: Idempotency-Key.

Respuesta: 201 Created con el customer completo (incluye id, tenant_id, created_at).

`GET /v1/customers/{id}`

Detalle de un cliente. Incluye health score actual, renewal info, tareas pendientes.

`PATCH /v1/customers/{id}`

Update parcial. Solo campos enviados se actualizan.

{
  "arr": 180000,
  "custom_fields": {
    "tier": "Platinum"
  }
}

`DELETE /v1/customers/{id}`

Soft-delete. Reversible 30 días via Admin → Clientes → Papelera.

Para hard-delete (GDPR): DELETE /v1/customers/{id}?hard=true — requiere scope admin:*.

`POST /v1/customers/bulk-import`

Import masivo (equivalente a CSV vía UI).

Body:

{
  "customers": [/* hasta 1000 */],
  "mode": "create_or_update",
  "conflict_resolution": "skip"
}

Retorna job_id — poll en GET /v1/jobs/{job_id}.

Contacts

`GET /v1/customers/{id}/contacts`

Lista contactos de un cliente.

`POST /v1/customers/{id}/contacts`

Crea contacto.

{
  "name": "Maria Perez",
  "email": "[email protected]",
  "title": "VP Operations",
  "is_champion": true,
  "whatsapp_number": "+56911112222"
}

Health

`GET /v1/customers/{id}/health`

Score actual + desglose por dimensiones.

`GET /v1/customers/{id}/health/history`

Serie temporal (default últimos 90 días).

Query: from, to (ISO 8601), granularity (daily default, weekly).

`POST /v1/customers/{id}/health/recalculate`

Fuerza recálculo inmediato (útil después de importar eventos en batch).

`GET /v1/health/model`

Devuelve la configuración del modelo de salud del workspace (pesos, umbrales, dimensiones activas).

`PATCH /v1/health/model`

Actualiza el modelo. Requiere scope health:write + rol admin.

Playbooks y tasks

`GET /v1/playbooks`

Lista playbooks del workspace.

`POST /v1/playbooks`

Crea playbook.

{
  "name": "Enterprise At-Risk",
  "trigger": {
    "type": "condition",
    "expression": "health_score < 60 AND segment == 'Enterprise'"
  },
  "actions": [
    {"type": "create_task", "title": "Call champion", "assignee": "owner"},
    {"type": "notify", "channel": "slack", "target": "#cs-alerts"}
  ],
  "enabled": true
}

`GET /v1/playbooks/{id}/runs`

Historial de ejecuciones (con qué clientes matcharon, qué acciones se lanzaron).

`GET /v1/tasks`

Tareas del workspace.

Query:

owner_id, assignee_id
status — pending | in_progress | completed | skipped.
due_before, due_after — fechas ISO.
customer_id, playbook_id.

`PATCH /v1/tasks/{id}`

Update status o reassignment.

`POST /v1/tasks/{id}/complete`

Completa con resultado estructurado.

{
  "outcome": "resolved",
  "notes": "Champion validó que el drop de uso era por deployment interno, no churn signal"
}

Users

`GET /v1/users`

Lista usuarios del workspace (admin only).

`GET /v1/users/me`

Perfil del actor actual (user o api_key).

`POST /v1/users`

Invita usuario (admin only, scope users:write).

{
  "email": "[email protected]",
  "role": "csm",
  "locale": "es",
  "timezone": "America/Santiago",
  "initial_territory_ids": ["..."]
}

`PATCH /v1/users/{id}/role`

Cambia rol. Admin only.

Analytics

`GET /v1/analytics/portfolio`

Resumen del portfolio: ARR total, # clientes por status, distribución de salud, top risks.

`GET /v1/analytics/renewals`

Pipeline de renovaciones por mes.

Query: from, to, forecast_category.

`GET /v1/analytics/cohorts`

Cohort analysis de retención.

Query: cohort_period — month | quarter. months_out — default 12.

Events (ingesta)

Ver Ingesta de eventos para el tratamiento completo.

`POST /v1/events`

Ingesta batch de eventos.

{
  "events": [/* hasta 1000 */]
}

`GET /v1/events`

Query de eventos (debugging). Rate-limited.

Webhooks (outbound)

Ver Webhooks.

`GET /v1/webhook-subscriptions`

`POST /v1/webhook-subscriptions`

`DELETE /v1/webhook-subscriptions/{id}`

Integraciones

`GET /v1/integrations`

Estado de integraciones del workspace (Gmail, Calendar, Slack, etc.).

`POST /v1/integrations/{name}/connect`

Inicia flow OAuth. Retorna URL de autorización.

`DELETE /v1/integrations/{name}`

Desconecta.

Rate limits

Per workspace, per endpoint class:

Endpoint class	Rate limit (default)
Reads (GET)	1000 req/min
Writes (POST, PATCH, DELETE)	300 req/min
Ingest (`POST /v1/events`)	60 batches/min (hasta 1000 eventos cada uno)
Bulk (`POST /v1/customers/bulk-import`)	10 req/hour

Headers en cada response:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset (unix timestamp)

Si excedes: 429 Too Many Requests + header Retry-After (segundos).

Tiers Scale/Enterprise tienen límites más altos. Contacta ventas si necesitas más.

Errores — formato (RFC 7807)

{
  "type": "https://api.lealup.com/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "detail": "Field 'arr' must be a positive number",
  "instance": "/v1/customers",
  "trace_id": "01HXYZ123ABC",
  "errors": [
    {"field": "arr", "code": "must_be_positive", "message": "..."}
  ]
}

Status codes comunes

200 OK
201 Created
204 No Content (DELETEs)
400 validation error
401 unauthenticated
403 forbidden (scope/permission)
404 not found (también cuando cruzas workspace)
409 conflict (duplicado, estado inválido)
422 unprocessable (semantic error, ej. renewal_date < today)
429 rate limited
500 server error (reporta con trace_id)

Ingesta de eventos — alimentar health.
Webhooks — recibir señales salientes.

On this page