API Quickstart

From 0 to your first successful request in ~5 minutes — create a customer and log an event.

This guide takes you from 0 to your first successful request against the LealUp API. By the end you'll have:

Created an API key.
Created a customer.
Logged a usage event for that customer.
Queried the resulting health score.

Estimated time: 5 minutes.

Prerequisites

Active LealUp account (if you don't have one, create one — 30-day trial).
admin role to create API keys.
curl or any HTTP client.

1. Create an API key

Go to Admin → API → API Keys.
Click New key.
Name: quickstart. Scopes: customers:write, customers:read, events:write, health:read.
Expires: 7 days (enough to test, forces rotation).
Copy the displayed key (lealup_sk_test_...).

2. Export the key as a variable

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

(Use https://api.lealup.com for production.)

3. Verify the key works

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

Expected response:

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

If you get 401, verify the key is copied correctly and that you're still on dev.

4. Create a customer

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

Response:

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

Save the id:

export CUSTOMER_ID="01HCUS123ABC..."

About Idempotency-Key — if you retry the same request with the same Idempotency-Key, LealUp returns the same response without creating a duplicate. Use it whenever a POST creates something.

5. Log an event

Events are usage signals that feed the 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"
      }
    ]
  }'

Response:

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

6. Query the health score

Wait ~30 seconds for the calculation to process, then:

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

Response:

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

The score of a newly created customer with few events is low — that's expected.

7. Check the customer in the UI

Head to your LealUp in the browser, search for "Acme Corp (test)". You should see:

The customer created.
The 2 events in the timeline.
The freshly calculated health score.

Cleanup

If this was only a test:

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

(Soft-delete — reversible for 30 days.)

And revoke the key:

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

Next steps

Endpoints — full resource reference.
Event ingestion — ingest at scale (batching, schema, rate limits).
Webhooks — receive events from LealUp in your system (e.g., churn alert).

Troubleshooting

`401 unauthenticated`

Verify the key is in the header correctly (format Bearer KEY).
Confirm the key is for dev if you're using the dev base URL.

`400 validation_error`

The body has invalid fields. Check the response detail, it lists exactly which field failed.

`409 duplicate`

email_domain already exists on another customer (unique per account). Use a different one.

`500 server_error`

Unlikely. Report with the trace_id to [email protected].

On this page