Custom frontend guide

This guide wires the whole public surface together: a form you own, Waitlyze-owned verification and storage, referral sharing, your domain, and your sender. Follow it in order - each step assumes the previous one works.

1. Collect signups with the APICopy Anchor Link

Build any form (React, plain HTML, mobile app backend) and POST from your server with a Signup API key. Never ship the key to the browser - proxy through your backend.

const response = await fetch("https://waitlyze.com/api/waitlist", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": orderId, // reuse on retry; see Signup API
  },
  body: JSON.stringify({
    apiKey: process.env.WAITLYZE_API_KEY,
    waitlistId: "YOUR_WAITLIST_ID",
    email,
    referral_code: refCode, // optional; snake_case or referralCode
  }),
});
const { data } = await response.json();
// data.position, data.referral_code, data.referral_link → render confirmation UI

Show data.position (“You're #9 in line”) and, when present, data.referral_link with a copy button. On 409, read data.position - the email already joined, so show its place instead of an error wall. Poll GET /api/waitlist?waitlistId=…&email=… for a “check my spot” box.

2. When to use the embed insteadCopy Anchor Link

If you do not need custom logic, skip the API: paste the embed snippet (data-key-id is a public waitlist ID, no secret). The embed forwards ?r=CODE and UTM parameters automatically, sizes itself, and needs no backend. Many teams combine both - embed for the marketing site, API for in-product or mobile flows - because both feed the same waitlist, position engine, and referral graph.

3. Turn on referralsCopy Anchor Link

In Waitlist settings → Referral sharing, enable sharing (Referrals). From then on:

• API responses include referral_code + referral_link for every signup.
• Pass a friend's code as referral_code (API), ?r=CODE (hosted page), or inherit it from your page URL (embed).
• Credit is awarded when the invitee verifies and the referral is CLEAR/APPROVED - gate rewards on the referral.completed webhook, never on signup alone. (Queue positions additionally require the inviter to be verified.)
• Review flagged referrals in Subscribers → Referral review.

4. Serve it from your domainCopy Anchor Link

Add join.example.com in Waitlist settings → Custom domain (Custom domains). It serves the same published revision as the hosted /w/slug page, so your API-built confirmation screens can link to a first-party URL. referral_link values in API responses still point at the Waitlyze hosted URL - rewrite the origin to your domain when rendering if you prefer (/w/slug?r=CODE path shape is identical).

5. Send from your domainCopy Anchor Link

Connect Resend (Settings → Integrations → Resend) so waitlist email can use your verified sender. The workspace connection is the shared fallback for verification, broadcast, and automation email. Keep it Active before launch so verification messages can be delivered reliably.

Per-waitlist sender credentials are also supported through authenticated waitlist settings endpoints; see Resend. They are not a complete override yet: broadcast, automation, and test-send paths still use the workspace sender because they do not pass a waitlist ID through sender resolution. Do not assume those paths use a waitlist-specific From address.

Launch checklistCopy Anchor Link

• Waitlist is Published (drafts reject every channel).
• Test signup via API returns 200 with position + referral_link.
• Duplicate email returns 409 with the existing position.
• Status lookup returns the same position for the test email.
• referral.completed webhook arrives on a verified referral (test with two real addresses).
• Resend status is Active; verification email arrives from your domain.
• Custom domain reads Ready (or ship on the hosted URL first).

NextCopy Anchor Link