# Start a waitlist

URL: /start/guides/start-a-waitlist · Id: `guide:start-a-waitlist`

> Say "start a waitlist" and get a signup box on your page, a place in line for each person, and invites sent in batches you choose.

Collect people who want in, then let them in a batch at a time. Each batch is small enough to talk to everyone in it.

Needs: [Startup](/business/nouns/startup)

**Before it runs**

- You leave the chat: Never: it all happens in the chat.
- First question at Idea: “Let people in by signup order, or by best fit first?”
- First question at Building: “How many people this time?”
- First question at Live: “How many people this time?”
- What it costs: Nothing.
- To undo it: Close the Waitlist. Everyone on it stays a Lead.

## What you get
- 1 waitlist box on your page (Waitlist)
- 1 Lead per signup, with a place in line (Lead)
- 1 confirmation email from your name (Message)
- 20 people let in, each with an invite email (Lead)

## Your agent does
**For agents**

- Guide: `guide:start-a-waitlist`, status `live`. Page: [/start/guides/start-a-waitlist.md](/start/guides/start-a-waitlist.md).
- Approval: none. Run it when the founder asks.
- Leaves the chat: never.
- Needs first: [Startup](/business/nouns/startup).
- Run: call the steps in order, each through the API, SDK, CLI or MCP tab below; a later step passes the `$id` an earlier one returns. Each value marked example is the sample business’s: pass the founder’s own.

| Step | Verb | Inputs (type, required, this guide’s value) | Returns |
| --- | --- | --- | --- |
| 1 | [`Waitlist.create`](/business/nouns/waitlist/create) (`verb:Waitlist.create`) | `invited` integer: example `1`; `rank` string: example `"signup"` | `waitlist` Waitlist |
| 2 | [`Waitlist.admit`](/business/nouns/waitlist/admit) (`verb:Waitlist.admit`) | `waitlist` Waitlist (an id), required: the `$id` step 1 returns; `count` integer, required: example `20` | `leads` Lead[], `waitlist` Waitlist |

Returns: the last call answers with `leads`, `waitlist` and its `action`, whose `status` is `done`, `pending` (waiting on an Approval or a Worker), `failed`, `canceled` or `refused`:

```json
{
  "api": "https://api.sb/leaseline.app",
  "leads": [
    {
      "$id": "https://api.sb/leaseline.app/leads/lead_1",
      "$type": "Lead"
    }
  ],
  "waitlist": {
    "$id": "https://api.sb/leaseline.app/waitlists/waitlist_1",
    "$type": "Waitlist",
    "rank": "signup"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/action_1",
    "operation": "Waitlist.admit",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/action_1"
  }
}
```

Next: offer “Let in only managers with more than 50 units”, or “Email everyone still waiting a short update”.

Calls: `Waitlist.create` → `Waitlist.admit`

Ask:

```text
Start a waitlist.
Collect emails from people who want in.
Let people in from the waitlist in batches.
```

API:

```bash
# 1. Waitlist.create
WAITLIST=$(curl -X POST https://api.sb/leaseline.app/waitlists \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invited":1,"rank":"signup"}' | jq -r '.waitlist["$id"] | split("/") | last')

# 2. Waitlist.admit
curl -X POST https://api.sb/leaseline.app/waitlists/$WAITLIST/admit \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count":20}'
```

SDK:

```ts
import { $ } from 'startup-builder'

const waitlist = await $.Waitlist.create({ invited: 1, rank: 'signup' })
await $.Waitlist.admit({ waitlist: waitlist.$id, count: 20 })
```

CLI:

```bash
WAITLIST=$(npx startup-builder do Waitlist.create --json '{"invited":1,"rank":"signup"}' | jq -r '.waitlist["$id"] | split("/") | last')
npx startup-builder do Waitlist.admit --json '{"waitlist":"'"$WAITLIST"'","count":20}'
```

MCP:

```json
{
  "name": "do",
  "arguments": {
    "code": "const waitlist = await $.Waitlist.create({ invited: 1, rank: 'signup' })\nreturn await $.Waitlist.admit({ waitlist: waitlist.$id, count: 20 })"
  }
}
```

The same sentence does more as the business grows:

| State | Calls | Asks first |
| --- | --- | --- |
| [Idea](/business/lifecycle/states/idea) | [`Waitlist.create`](/business/nouns/waitlist/create) | Let people in by signup order, or by best fit first? |
| [Building](/business/lifecycle/states/building) | [`Waitlist.admit`](/business/nouns/waitlist/admit) | How many people this time? |
| [Live](/business/lifecycle/states/live) | [`Waitlist.admit`](/business/nouns/waitlist/admit) | How many people this time? |

## Change it
- Let in only managers with more than 50 units.
- Email everyone still waiting a short update.
- Close the waitlist and open sign-up to all.

## Under the hood
- Systems: [Waitlists](/systems/waitlists), [CRM](/systems/crm), [Mailboxes](/systems/mailboxes)
- Nouns: [Waitlist](/business/nouns/waitlist), [Lead](/business/nouns/lead), [Message](/business/nouns/message)
- Events: [`Waitlist.joined`](/business/events/Waitlist.joined), [`Waitlist.admitted`](/business/events/Waitlist.admitted)

Each signup joins by [`Waitlist.join`](/business/nouns/waitlist/join) and becomes a [Lead](/business/nouns/lead). [`Waitlist.admit`](/business/nouns/waitlist/admit) lets in the next people in line, by signup order or by best fit.