LealUp API

LealUp exposes a versioned REST API for programmatic integration. This section gets you productive with the API in ~15 minutes.

Who this documentation is for

• Product engineers who want to send usage events to feed the health score.
• Ops teams automating customer creation, ownership assignment, or sync from their systems.
• Partners integrating LealUp as part of their stack (CRMs, support platforms, BI).

If you just want to use LealUp from the UI, you don't need this. Head to For CSMs or For Admins.

Fundamentals

Environments

LealUp offers two public environments:

• Production (api.lealup.com) — real data, real webhooks, 99.9% SLA, lealup_sk_live_* keys.
• Dev (api.dev.lealup.com) — for integration testing, lealup_sk_test_* keys.

About the dev environment:

• No SLA — best effort, can go down without notice during deploys.
• Data may reset quarterly — don't store anything you need to keep.
• Same API version as production (we deploy to dev first).
• Isolated data — accounts, customers, and events in dev don't exist in prod and vice versa.
• Ideal for: validating webhook signatures, testing event ingestion, developing integrations before going live.
• Not ideal for: your QA environment's persistent test data, demos to real customers, load testing (lower limits).

Every workspace can issue both live and test keys from Admin → API → API Keys.

Resource map

The API covers LealUp's core resources:

Customers and contacts

• GET|POST /v1/customers — list, create.
• GET|PATCH|DELETE /v1/customers/{id} — detail, edit, soft-delete.
• GET /v1/customers/{id}/contacts — a customer's contacts.
• POST /v1/customers/bulk-import — bulk import (also available via CSV in the UI).

Health

• GET /v1/customers/{id}/health — current score + dimensions.
• GET /v1/customers/{id}/health/history — time series (90 days).
• POST /v1/customers/{id}/health/recalculate — force recalculation.

Playbooks and tasks

• GET|POST /v1/playbooks — list, create.
• GET /v1/tasks — tasks (filters: owner, status, due_date).
• PATCH /v1/tasks/{id} — update status.
• POST /v1/tasks/{id}/complete — complete with outcome.

Events (ingestion)

• POST /v1/events — batch ingestion (up to 1000 events per request).
• GET /v1/events — event query (debugging).
• See Event ingestion.

Users and team

• GET|POST /v1/users — list, invite.
• GET /v1/users/me — current profile.
• PATCH /v1/users/{id}/role — change role (admin only).

Webhooks (outbound)

• GET|POST /v1/webhook-subscriptions — manage outgoing subscriptions.
• See Webhooks.

Analytics and dashboards

• GET /v1/analytics/portfolio — portfolio summary.
• GET /v1/analytics/renewals — renewal pipeline.
• GET /v1/dashboards/{id}/widgets — custom dashboard data.

Data isolation

Every request is scoped to your LealUp account automatically:

• With OAuth: the token includes your account identifier (claim tenant_id in the JWT). Resolved without you doing anything.
• With API key: the key belongs to one account only, so it's inferred from the Authorization header.

Your data never crosses accounts by construction. If you try GET /v1/customers/{id} with an id that belongs to another account, we return 404 (not 403, to avoid leaking existence).

In JSON responses you'll see the tenant_id field — it's the technical identifier of your account, useful when reporting issues to support.

SDKs

• TypeScript — @lealup/sdk (npm). Types generated from OpenAPI, zod validators included.
• Python — lealup-sdk (PyPI). Async-first, Pydantic models.
• Go — in beta.
• Ruby, PHP, Java — not yet official. You can generate from OpenAPI with openapi-generator.

Next steps

1. Authentication — get credentials.
2. Quickstart — hello world in 5 min.
3. Endpoints — reference by resource.
4. Event ingestion — feed the health score.
5. Webhooks — receive outbound events.

Support

• Full spec: api.lealup.com/v1/openapi.json
• Status page: status.lealup.com
• Issues and requests: [email protected]
• Enterprise partners: dedicated Slack channel post-contract.