Look up an entry

Fetch a single entry by email or phone — the call behind "you're #123 on the list, share your link to move up" in your own app.

GET /sdk/v1/waitlist/{waitlistId}/entries?email=…

GET /sdk/v1/waitlist/{waitlistId}/entries?phone=…

• Auth: Server key with the waitlist:read grant — Authorization: Bearer <key>. Call it from your backend only; never expose a server key (or this endpoint's results for arbitrary identifiers) to the browser.
• Identifier: pass email or phone — whichever you have. Omitting both is a 400.
• Matching: email is case-insensitive; phone must be E.164 (+15550100199). URL-encode the value (ada%40example.com, %2B15550100199) if your HTTP client doesn't — note a raw + in a query string decodes to a space.

Path form

GET /sdk/v1/waitlist/{waitlistId}/entries/{email} still works for email lookups. Prefer the query form: a phone number's leading + cannot travel safely in a path segment.

Response

The entry object — position, status, referral code and count.

{
  "id": "5f0c6a8e-…",
  "waitlistId": "wl_launch",
  "identifierKind": "email",
  "email": "ada@example.com",
  "phone": "",
  "metadata": { "name": "Ada Lovelace", "plan": "pro" },
  "position": 1,
  "referrals": 3,
  "referralCode": "481920",
  "status": "waiting",
  "source": "landing_page",
  "signedUpAt": "2026-07-01T09:30:00.000Z"
}

Example

curl

curl "https://api.uselucerna.app/sdk/v1/waitlist/wl_launch/entries/ada%40example.com" \
  -H "Authorization: Bearer $LUCERNA_SERVER_KEY"

JavaScript

const email = encodeURIComponent("ada@example.com");
const res = await fetch(
  `https://api.uselucerna.app/sdk/v1/waitlist/wl_launch/entries/${email}`,
  {
    headers: { Authorization: `Bearer ${process.env.LUCERNA_SERVER_KEY}` },
  },
);

if (res.status === 404) {
  // Not on the list — show your signup form instead.
}
if (!res.ok) {
  const error = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const { position, referralCode } = await res.json();

Errors

Status	code	When
401	unauthorized	Missing or invalid server key.
403	forbidden	The key was not granted waitlist:read.
404	not_found	No waitlist matches waitlistId, or the email is not on it.

See Errors for the response shape and retry guidance.