# WhoComing
> WhoComing is an RSVP widget and REST API for a site you already own. Guests RSVP on your page without an account. Embed with ``, or call the API at https://api.whocoming.com/v1 with a `wc_live_` or `wc_test_` secret key.
The full text of these docs is at https://whocoming.com/llms-full.txt. The OpenAPI 3.1 document is at https://api.whocoming.com/v1/openapi.json.
## Start here
- [WhoComing docs](https://whocoming.com/docs): Put an RSVP form on your own site with one script tag, a React component or a REST API.
- [Quickstart](https://whocoming.com/docs/quickstart): A real RSVP in a real event in under five minutes. The first two need no account.
## Guides
- [Plain HTML](https://whocoming.com/docs/guides/html): Two lines on any page. No build step, no framework, no key.
- [Next.js](https://whocoming.com/docs/guides/nextjs): Add the RSVP widget to a Next.js App Router page, and create RSVPs from a server action.
- [WordPress](https://whocoming.com/docs/guides/wordpress): Add the RSVP widget to a WordPress page or post with a Custom HTML block. No plugin needed.
- [Webflow](https://whocoming.com/docs/guides/webflow): Add the RSVP widget to a Webflow page with a Code Embed element.
- [Vue, Svelte and others](https://whocoming.com/docs/guides/other-frameworks): The widget is a standard custom element, so it works in every framework without a wrapper.
## Concepts
- [Events](https://whocoming.com/docs/concepts/events): What an event holds, how its time works, and the difference between status and visibility.
- [Recurring series](https://whocoming.com/docs/concepts/series): One rule, many events. A series creates its occurrences ahead of time so each date has its own guest list.
- [RSVPs and statuses](https://whocoming.com/docs/concepts/rsvps): What an RSVP is, the four statuses, where RSVPs come from, and how guests change their own.
- [Capacity and waitlist](https://whocoming.com/docs/concepts/capacity-and-waitlist): How seats are counted, what happens when an event is full, and how the waitlist moves.
- [Test mode](https://whocoming.com/docs/concepts/test-mode): wc_test_ keys work on a separate copy of your data, send no real email, and are never counted toward your plan.
- [Plans and limits](https://whocoming.com/docs/concepts/plans-and-limits): What each plan includes, how RSVPs are counted, and what happens at a limit.
- [Locked RSVPs on Free](https://whocoming.com/docs/concepts/locked-rsvps): Over the Free plan's monthly limit, RSVPs are still accepted. Their details are hidden until you upgrade.
## Embed
- [Embed reference](https://whocoming.com/docs/embed): The element, its attributes, and what it does on your page.
- [Theming](https://whocoming.com/docs/embed/theming): Restyle the widget with five CSS variables and three ::part() names.
- [DOM events](https://whocoming.com/docs/embed/events): The widget fires whocoming:ready, whocoming:rsvp and whocoming:error on the element. They bubble and cross the Shadow DOM.
- [Text and translation](https://whocoming.com/docs/embed/strings): Override any text in the widget with the strings attribute, one key at a time or all of it for a translation.
- [Iframe and legacy script](https://whocoming.com/docs/embed/fallbacks): Two other ways to place the widget, for site builders that block scripts or only accept a single tag.
- [Privacy](https://whocoming.com/docs/embed/privacy): The widget sets no cookies, runs no analytics and stores nothing unless the guest asks it to remember them.
## API
- [Authentication and scopes](https://whocoming.com/docs/api/authentication): Secret keys for your server, scopes per key, and the public surface that needs no key.
- [Pagination](https://whocoming.com/docs/api/pagination): Lists return { data, next_cursor }. Pass the cursor back to get the next page.
- [Idempotency](https://whocoming.com/docs/api/idempotency): Send an Idempotency-Key on creating requests so a retry can never create a second RSVP or event.
- [Rate limits](https://whocoming.com/docs/api/rate-limits): Requests per minute per key, set by your plan, with the standard RateLimit headers on every response.
- [Limits](https://whocoming.com/docs/api/limits): The size and range limits on every request, and what happens when one is passed.
- [Versioning](https://whocoming.com/docs/api/versioning): /v1 only ever grows. Anything breaking waits for /v2, and /v1 keeps working for 12 months after that.
- [Errors](https://whocoming.com/docs/errors): Every error is RFC 9457 problem JSON with a stable code. The full list of codes and their HTTP statuses.
- [Webhooks](https://whocoming.com/docs/webhooks): Get a signed HTTP POST when guests RSVP, cancel, move off the waitlist or check in, and when events change.
- [SDK](https://whocoming.com/docs/sdk): @whocoming/sdk, a small typed client for the API, and @whocoming/react, the widget as a React component.
- [Data rights](https://whocoming.com/docs/data-rights): Export everything you hold about a guest, erase a guest by email, and how long guest details are kept.
## API reference: Events
- [List events](https://whocoming.com/docs/reference/events/list-events): Events in the key's mode, soonest first.
- [Create an event](https://whocoming.com/docs/reference/events/create-event): Create a one-off event. Accepts `Idempotency-Key`.
- [Get an event](https://whocoming.com/docs/reference/events/get-event): Read one event, including private ones.
- [Update an event](https://whocoming.com/docs/reference/events/update-event): Change the fields you send. Set `status` to `cancelled` to cancel the event and notify guests.
- [Delete an event](https://whocoming.com/docs/reference/events/delete-event): Delete an event and its RSVPs. To keep the guest list and tell guests, cancel it with PATCH instead.
## API reference: RSVPs
- [List an event's RSVPs](https://whocoming.com/docs/reference/rsvps/list-rsvps): The guest list, oldest first. Filter with `status`.
- [Create an RSVP](https://whocoming.com/docs/reference/rsvps/create-rsvp): Add a guest. Capacity and the waitlist apply. One RSVP per email per event (409 `already_registered`). Accepts `Idempotency-Key`.
- [Get an RSVP](https://whocoming.com/docs/reference/rsvps/get-rsvp): Read one RSVP.
- [Update an RSVP](https://whocoming.com/docs/reference/rsvps/update-rsvp): Change the fields you send.
- [Delete an RSVP](https://whocoming.com/docs/reference/rsvps/delete-rsvp): Remove the RSVP and its guest data for good. To keep a record, set `status` to `cancelled` instead.
- [Check in a guest](https://whocoming.com/docs/reference/rsvps/check-in-rsvp): Mark the guest as arrived. Checking in twice keeps the first time. Only an RSVP with status `going` can be checked in: a cancelled, not going or waitlisted RSVP answers 409 `rsvp_not_going`.
## API reference: Guests
- [Erase a guest](https://whocoming.com/docs/reference/guests/erase-guest): Delete every RSVP for this email address in the organization, in the key's mode only, and remove the guest's name, email and answers from webhook deliveries not yet sent. Freed seats go to the waitlist, so someone may be promoted. Usage already counted this month is not refunded. This cannot be undone.
- [Export a guest's data](https://whocoming.com/docs/reference/guests/export-guest): Everything held about one email address, for a data access request.
## API reference: Public
- [Get a public event](https://whocoming.com/docs/reference/public/get-public-event): Event details, form fields, theme and counts for the widget. No guest personal data. Private, draft and unknown events all answer 404 `event_not_found`. No key needed. CORS is open to any origin. Cached at the CDN for 15 seconds (`s-maxage=15, stale-while-revalidate=60`).
- [Download the event as a calendar file](https://whocoming.com/docs/reference/public/get-public-event-calendar): An iCalendar (.ics) file for "Add to calendar". A cancelled event has `STATUS:CANCELLED`. Private, draft and unknown events answer 404 `event_not_found`. No key needed. CORS is open to any origin. Cached at the CDN for 15 seconds (`s-maxage=15, stale-while-revalidate=60`).
- [RSVP as a guest](https://whocoming.com/docs/reference/public/create-public-rsvp): Create an RSVP from the browser. Requires a Turnstile token whenever the event's `turnstile_site_key` is not null (403 `bot_check_failed` without a valid one). Limited to 5 per minute and 30 per hour per IP per event. If the organizer set allowed origins, the `Origin` header must match (403 `origin_not_allowed`). An email already going or on the waitlist answers 409 `already_registered` and re-sends that guest their manage link (at most once an hour). Send an `Idempotency-Key` to make retries safe: a retry returns the first response, manage token included. Never cached.
- [List an organization's upcoming events](https://whocoming.com/docs/reference/public/list-public-org-events): Upcoming public live-mode events for a calendar, soonest first. Unlisted and private events are left out. An unknown slug and a sandbox organization both answer 404 `not_found`. No key needed. CORS is open to any origin. Cached at the CDN for 15 seconds (`s-maxage=15, stale-while-revalidate=60`).
- [View your RSVP](https://whocoming.com/docs/reference/public/get-public-rsvp): A guest's own RSVP and its event, through the manage token. `name` and `email` are null when the RSVP is locked or its details were removed. Rate limited per IP and per token. Never cached.
- [Change or cancel your RSVP](https://whocoming.com/docs/reference/public/update-public-rsvp): Change the fields you send. Set `status` to `cancelled` to cancel; the seat goes to the waitlist. The email cannot be changed here. An ended event answers 409 `event_ended`, and a cancelled one accepts only `cancelled`. Rate limited per IP and per token. Never cached.
## API reference: Sandbox
- [Create a sandbox](https://whocoming.com/docs/reference/sandbox/create-sandbox): Create a 24-hour test organization with a `wc_test_` key and a sample event. No sign-up. Limited per IP (429 `sandbox_limit`).
## API reference: Series
- [List series](https://whocoming.com/docs/reference/series/list-series): Recurring series in the key's mode, oldest first. List an occurrence's events with `GET /v1/events?series_id=`.
- [Create a recurring series](https://whocoming.com/docs/reference/series/create-series): Create a weekly, every-two-weeks or monthly series. Occurrences are created as events about 90 days ahead. Free allows one active series (`plan_limit`). Accepts `Idempotency-Key`.
- [Get a series](https://whocoming.com/docs/reference/series/get-series): Read one series.
- [Update a series](https://whocoming.com/docs/reference/series/update-series): Change the fields you send. Applies to future occurrences: a new title or template updates them, and a schedule change replaces the future occurrences nobody has RSVPed to.
- [End a series](https://whocoming.com/docs/reference/series/end-series): Stop creating new occurrences. The series is kept with `status: ended`. Future occurrences nobody has RSVPed to are removed; occurrences with RSVPs stay, so cancel those one by one to tell their guests.
## API reference: Usage
- [Get usage](https://whocoming.com/docs/reference/usage/get-usage): RSVPs counted this month and the plan's limits.
## API reference: Webhooks
- [List webhook deliveries](https://whocoming.com/docs/reference/webhooks/list-webhook-deliveries): The delivery log, newest first.
- [Redeliver a webhook](https://whocoming.com/docs/reference/webhooks/retry-webhook-delivery): Queue the delivery to be sent again within a minute, with the same `webhook-id`.
- [List webhook endpoints](https://whocoming.com/docs/reference/webhooks/list-webhook-endpoints): Endpoints in the key's mode. Secrets are never listed.
- [Create a webhook endpoint](https://whocoming.com/docs/reference/webhooks/create-webhook-endpoint): Register a URL for webhook deliveries. The response is the only time the signing `secret` is shown. The URL must use https and a public address; in test mode `http://localhost` and `http://127.0.0.1` also work. Plan limits apply (`plan_limit`). Accepts `Idempotency-Key`.
- [Get a webhook endpoint](https://whocoming.com/docs/reference/webhooks/get-webhook-endpoint): Read one endpoint. The secret is never shown again.
- [Update a webhook endpoint](https://whocoming.com/docs/reference/webhooks/update-webhook-endpoint): Change the URL or event types, or pause and resume.
- [Delete a webhook endpoint](https://whocoming.com/docs/reference/webhooks/delete-webhook-endpoint): Stop deliveries and remove the endpoint.
- [A guest RSVPed](https://whocoming.com/docs/reference/webhooks/rsvp-created): A new RSVP, from any source. `data.status` is `going`, `not_going` or `waitlisted`. When a guest who had cancelled RSVPs again, `rsvp.updated` is sent instead.
- [An RSVP changed](https://whocoming.com/docs/reference/webhooks/rsvp-updated): Name, email, extra guests, answers or status changed, a cancelled guest RSVPed again, or a check-in was undone.
- [An RSVP was cancelled or deleted](https://whocoming.com/docs/reference/webhooks/rsvp-cancelled): The guest or organizer cancelled. When the RSVP was deleted instead, `data` holds identifiers only and `deleted: true`.
- [A guest moved off the waitlist](https://whocoming.com/docs/reference/webhooks/rsvp-promoted): A seat freed up and this waitlisted guest is now `going`.
- [A guest checked in](https://whocoming.com/docs/reference/webhooks/rsvp-checked-in): Sent once per RSVP, the first time it is checked in.
- [An event was created](https://whocoming.com/docs/reference/webhooks/event-created): Including each occurrence a recurring series creates.
- [An event changed](https://whocoming.com/docs/reference/webhooks/event-updated): Any change to the event's details, including publishing a draft.
- [An event was cancelled](https://whocoming.com/docs/reference/webhooks/event-cancelled): If the event was published, its going and waitlisted guests are emailed.