Skip to main content
Waitlist mode holds the door: people sign up, nothing mints a session, and you let them in when you are ready. The reason it belongs here rather than in a form builder is that the list is made of contacts from its first minute. First-touch attribution, the anonymous-to-identified merge, the audit trail and the active-contact meter all already work on contacts — so “convert the waitlist into real accounts” is a timestamp, not a migration. Nobody ever migrates a spreadsheet into their auth.
It is a per-environment switch, so a launch can be rehearsed in test while live still holds the line. It only exists in hosted mode: in federated mode your own backend decides who exists, and a gate of ours there would be a gate on a door we do not own.

​
Turning it on

In the panel, under API keys → Identidade dos contatos, or over the API:
GET /v1/config/{publishable_key} starts answering "waitlist": true, which is what lets a sign-up screen change shape without a deploy.

​
Collecting

202, always — the same posture the rest of the hosted surface holds: this endpoint never becomes the place somebody learns which addresses are on the list. A confirmation goes to the inbox, carrying no link and no credential, because there is nothing yet to click. Signing up twice keeps the first place in line and the first answers. People forget they already signed up, and that must not cost them their position.
Pass the anonymous_id your page already has (@userkit/js does it for you) and the entry inherits the visit: the UTM parameters and the referrer that brought this person to the landing page are on the contact, and they are still there the day they become a paying customer.

​
With the SDK

<SignUp /> renders the waitlist form on its own while the mode is on — an address, no password, no social buttons — because it reads the config rather than taking it as a prop. A sign-up form you shipped months before launch keeps working on launch day.
Directly, when you have your own form:

​
Or through the ordinary sign-up

POST /v1/contact-auth/signup joins the line too while the mode is on, and it answers { "waitlist": true } so a custom form can say so. The password the person chose parks on the entry and attaches when they are let in and their address is proven — never before. A password on an address nobody confirmed is not evidence of anything, which is the same reasoning that closes the pre-created-account takeover.

​
The line actually holds

While somebody is waiting, no route mints a session for them: not the password, not a magic link, not an email code, and not “continue with Google”. Every one of them answers 403 waitlisted. That is enforced where sessions are minted rather than at each door, for the same reason two-factor is. A line you can walk around by choosing another button is a mailing list with extra steps.
Anonymous visitors are never held. The widget mints a visitor session on every landing-page load, and a waitlist whose landing page cannot run the widget is a waitlist with no attribution — which is most of the reason to keep the list here.

​
Letting people in

Admitting is the act that turns an entry into an account somebody can use:
1

The line stops holding them

Every sign-in route works for that person from this moment.
2

The way in is mailed

A single link that proves the address, attaches the password they parked, and signs them in. One click from “you are in” to being in — anything longer loses the people who waited.
It is idempotent: an entry already admitted is skipped, so a second call mails nothing.
Turning waitlist mode off does not admit anybody. The two are separate on purpose: the people already in line have a password parked on their entry that never attached, and flipping the switch alone would leave them discovering that at the login screen. Admit everybody first, then turn the mode off — or leave it on and admit as you go.

​
Reading the queue

Entries come back in joining order, and that order is the position. Reading takes customers:read; admitting takes customers:write, because it is what creates the account.