Quickstart API

De 0 a primer request exitoso en ~5 minutos — crear un cliente y registrar un evento.

Esta guía te lleva de 0 a tu primer request exitoso contra la API de LealUp. Al terminar vas a haber:

Creado una API key.
Creado un cliente.
Registrado un evento de uso para ese cliente.
Consultado el health score resultante.

Tiempo estimado: 5 minutos.

Prerequisitos

Workspace de LealUp activo (si no, crea uno — trial de 30 días).
Rol admin para crear API keys.
curl o cualquier cliente HTTP.

1. Crear una API key

Entra a Admin → API → API Keys.
Click Nueva key.
Name: quickstart. Scopes: customers:write, customers:read, events:write, health:read.
Expira: 7 días (suficiente para probar, obliga rotar).
Copia la key mostrada (lealup_sk_test_...).

2. Exportar la key como variable

export LEALUP_KEY="lealup_sk_test_abc123..."
export LEALUP_BASE="https://api.dev.lealup.com"

(Usa https://api.lealup.com para producción.)

3. Verificar que la key funciona

curl $LEALUP_BASE/v1/users/me \
  -H "Authorization: Bearer $LEALUP_KEY"

Respuesta esperada:

{
  "id": "01HXYZ...",
  "email": "[email protected]",
  "type": "api_key",
  "name": "quickstart",
  "tenant_id": "01HTEN...",
  "scopes": ["customers:write", "customers:read", "events:write", "health:read"]
}

Si obtienes 401, verifica que la key esté bien copiada y que sigas en dev.

4. Crear un cliente

curl -X POST $LEALUP_BASE/v1/customers \
  -H "Authorization: Bearer $LEALUP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-acme-001" \
  -d '{
    "name": "Acme Corp (test)",
    "email_domain": "acme-test.com",
    "arr": 50000,
    "owner_email": "[email protected]",
    "status": "active"
  }'

Respuesta:

{
  "id": "01HCUS123ABC...",
  "tenant_id": "01HTEN...",
  "name": "Acme Corp (test)",
  "email_domain": "acme-test.com",
  "arr": 50000,
  "owner_id": "01HUSR...",
  "status": "active",
  "health_score": null,
  "created_at": "2026-04-15T14:23:00Z"
}

Guarda el id:

export CUSTOMER_ID="01HCUS123ABC..."

Sobre Idempotency-Key — si reintentas el mismo request con el mismo Idempotency-Key, LealUp devuelve la misma respuesta sin crear un duplicado. Úsalo siempre en POSTs que crean cosas.

5. Registrar un evento

Los eventos son señales de uso que alimentan el health score.

curl -X POST $LEALUP_BASE/v1/events \
  -H "Authorization: Bearer $LEALUP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-event-001" \
  -d '{
    "events": [
      {
        "customer_id": "'$CUSTOMER_ID'",
        "user_email": "[email protected]",
        "event_name": "report_exported",
        "timestamp": "2026-04-15T14:25:00Z",
        "properties": {
          "report_type": "quarterly",
          "format": "pdf"
        }
      },
      {
        "customer_id": "'$CUSTOMER_ID'",
        "user_email": "[email protected]",
        "event_name": "dashboard_viewed",
        "timestamp": "2026-04-15T14:26:00Z"
      }
    ]
  }'

Respuesta:

{
  "accepted": 2,
  "rejected": 0,
  "errors": []
}

6. Consultar el health score

Espera ~30 segundos para que el cálculo procese, luego:

curl "$LEALUP_BASE/v1/customers/$CUSTOMER_ID/health" \
  -H "Authorization: Bearer $LEALUP_KEY"

Respuesta:

{
  "customer_id": "01HCUS123ABC...",
  "score": 52,
  "status": "neutral",
  "dimensions": {
    "usage": {"value": 65, "weight": 0.40},
    "engagement": {"value": 40, "weight": 0.30},
    "support": {"value": 50, "weight": 0.20},
    "sentiment": {"value": 50, "weight": 0.10}
  },
  "updated_at": "2026-04-15T14:30:00Z"
}

El score de un cliente recién creado con pocos eventos es bajo — normal.

7. Revisar el cliente en la UI

Entra a tu workspace en el navegador, busca "Acme Corp (test)". Deberías ver:

El cliente creado.
Los 2 eventos en el timeline.
El health score recién calculado.

Cleanup

Si esto fue solo una prueba:

curl -X DELETE "$LEALUP_BASE/v1/customers/$CUSTOMER_ID" \
  -H "Authorization: Bearer $LEALUP_KEY"

(Soft-delete — se puede revertir 30 días.)

Y revoca la key:

# via UI: Admin → API → API Keys → quickstart → Revocar

Siguientes pasos

Endpoints — referencia completa de recursos.
Ingesta de eventos — ingesta en escala (batching, schema, rate limits).
Webhooks — recibir eventos de LealUp en tu sistema (ej. alerta de churn).

Troubleshooting

`401 unauthenticated`

Verifica que la key esté en el header correctamente (formato Bearer KEY).
Confirma que la key es de dev si usas el base URL de dev.

`400 validation_error`

El body tiene campos inválidos. Revisa el detail del response, lista exactamente qué campo falló.

`409 duplicate`

email_domain ya existe en otro cliente (único por workspace). Usa otro.

`500 server_error`

Improbable. Reporta con el trace_id a [email protected].

On this page