Quickstart

Add your first signup to a waitlist in under a minute.

1. Get your server key

In the dashboard, open Waitlist → API and copy the server key for your production environment. It looks like:

ck_srv_waitlist_prod_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

Keep it secret

The server key grants write access to your waitlist. Use it only from your backend and store it as an environment variable — never ship it in browser-side code. See Authentication.

2. Find your waitlist id

The waitlistId is the short id shown in the dashboard next to the waitlist (for example wl_launch). It's the same id used in your API setup snippets.

3. Capture a signup

Send the signup from your backend:

curl

curl -X POST https://api.uselucerna.app/sdk/v1/waitlist/signup \
  -H "Authorization: Bearer $LUCERNA_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "waitlistId": "wl_launch",
    "entries": [
      { "email": "ada@example.com" }
    ]
  }'

JavaScript

const res = await fetch("https://api.uselucerna.app/sdk/v1/waitlist/signup", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LUCERNA_SERVER_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    waitlistId: "wl_launch",
    entries: [{ email: "ada@example.com" }],
  }),
});

const result = await res.json();
// { success: true, created: 1, skipped: 0 }

A 201 Created response means the signup landed:

{ "success": true, "created": 1, "skipped": 0 }

If that email was already on the waitlist, you'll get 200 OK with "created": 0, "skipped": 1 instead — the request is safe to retry and never creates duplicates.

4. Send a batch (optional)

You can submit up to 100 entries in a single request, each with optional metadata for later segmentation:

curl

curl -X POST https://api.uselucerna.app/sdk/v1/waitlist/signup \
  -H "Authorization: Bearer $LUCERNA_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "waitlistId": "wl_launch",
    "entries": [
      { "email": "ada@example.com", "metadata": { "plan": "pro" } },
      { "email": "grace@example.com", "referredBy": "ada@example.com" }
    ]
  }'

JavaScript

await fetch("https://api.uselucerna.app/sdk/v1/waitlist/signup", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LUCERNA_SERVER_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    waitlistId: "wl_launch",
    entries: [
      { email: "ada@example.com", metadata: { plan: "pro" } },
      { email: "grace@example.com", referredBy: "ada@example.com" },
    ],
  }),
});

That's the whole integration. See the signup reference for every field, or the invite endpoints to build your own join flow.