POST
/v1/waitlist/signupsAdds 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
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": "[email protected]",
"name": "Jamie",
"metadata": { "utm_source": "launch-page" }
}'
Response
201 Created
{
"data": {
"id": "wl_7hqm4tzvbc82nkxrdp9sfjwe",
"object": "waitlist_signup",
"email": "[email protected]",
"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.
Key the idempotency header on the email address
Use something like waitlist:[email protected]. 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 |