:::endpoint POST /v1/waitlist/signups

Adds an email address to your waitlist, hands out the reward you configured, and
emails them the confirmation.

## Parameters

| Parameter  | Type             | Description                                                      |
| ---------- | ---------------- | ---------------------------------------------------------------- |
| `email`    | string, required | Where to send the confirmation. Must be unique within your firm. |
| `name`     | string, optional | Shown in your dashboard. Up to 255 characters.                   |
| `metadata` | object, optional | Up to 20 string values of 500 characters. Returned unchanged.    |

There is no parameter for the discount. What they get is decided by your waitlist
settings, so a leaked key cannot mint a bigger discount than you configured.

## Request

```bash
curl -X POST https://api.proppertrading.com/v1/waitlist/signups \
  -H "Authorization: Bearer sk_live_a1b2c3d4_9f83c2e15b7a4d6e8091c3f5a7b9d1e2" \
  -H "Idempotency-Key: 6c9b1a77-2f4e-4a3d-8b52-91d0e7f4c318" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jamie@example.com",
    "name": "Jamie",
    "metadata": { "utm_source": "launch-page" }
  }'
```

## Response

`201 Created`

```json
{
    "data": {
        "id": "wl_7hqm4tzvbc82nkxrdp9sfjwe",
        "object": "waitlist_signup",
        "email": "jamie@example.com",
        "name": "Jamie",
        "status": "pending",
        "reward_code": "LAUNCH-K4M9XR2P",
        "source": "api",
        "metadata": { "utm_source": "launch-page" },
        "created_at": "2026-08-03T17:44:13+00:00",
        "notified_at": null,
        "converted_at": null,
        "unsubscribed_at": null,
        "last_sent_at": "2026-08-03T17:44:13+00:00"
    },
    "meta": { "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey" }
}
```

`reward_code` is `null` when you hand out no code, and also when the reward is
configured but incomplete. Treat it as optional in your page: show the code block
only when there is one.

:::tip Key the idempotency header on the email address
Use something like `waitlist:jamie@example.com`. A double-clicked form or a retry
after a timeout then returns the first response instead of a second attempt, and
a second attempt would fail with `email_already_on_waitlist` anyway.
:::

## Errors

| Status | Code                        | Meaning                             |
| ------ | --------------------------- | ----------------------------------- |
| 400    | `waitlist_disabled`         | Open your waitlist in the dashboard |
| 400    | `missing_idempotency_key`   | Add an `Idempotency-Key` header     |
| 409    | `email_already_on_waitlist` | That address is already on the list |
| 422    | `validation_failed`         | See `errors` in the response        |