# WhoComing developer docs Source: https://whocoming.com/docs. Production API: https://api.whocoming.com. Widget script: https://cdn.whocoming.com/embed.js. # WhoComing docs URL: https://whocoming.com/docs Put an RSVP form on your own site with one script tag, a React component or a REST API. WhoComing is an RSVP component for a site you already own. Guests RSVP on your page, never create an account and never leave. You get capacity, a waitlist, confirmation emails, check-in and webhooks, on every plan including Free. ## Three ways in Two lines of HTML. Works on any site you can paste into: WordPress, Webflow, Squarespace, plain HTML. `@whocoming/react` wraps the same widget with typed props and an `onRsvp` callback. Create events and RSVPs from your server, with idempotency keys, test mode and webhooks. New here? The [quickstart](https://whocoming.com/docs/quickstart) gets a real RSVP into a real event in under five minutes, and the first two minutes need no account. ```html ``` ## Our versioning promise `/v1` only ever grows. We add endpoints and fields; we never remove or rename a field, change its type or make validation stricter. Anything breaking waits for `/v2`, and `/v1` keeps working for **12 months** after `/v2` ships. [More on versioning](https://whocoming.com/docs/api/versioning). ## What is where - **[Guides](https://whocoming.com/docs/guides/html):** the exact snippet for plain HTML, Next.js, WordPress, Webflow and other frameworks. - **[Concepts](https://whocoming.com/docs/concepts/events):** events, recurring series, RSVPs, capacity and the waitlist, test mode, plans. - **[Embed reference](https://whocoming.com/docs/embed):** attributes, theming, DOM events, text overrides, privacy. - **[API](https://whocoming.com/docs/api/authentication):** keys and scopes, [errors](https://whocoming.com/docs/errors), pagination, idempotency, rate limits. - **[Webhooks](https://whocoming.com/docs/webhooks):** event types, signatures, retries. - **[SDK](https://whocoming.com/docs/sdk):** `@whocoming/sdk` for TypeScript and `@whocoming/react`. - **[API reference](https://whocoming.com/docs/reference/events/list-events):** every endpoint, with a playground. For coding agents, the whole of these docs is at [/llms-full.txt](https://whocoming.com/llms-full.txt) and the index at [/llms.txt](https://whocoming.com/llms.txt). --- # Quickstart URL: https://whocoming.com/docs/quickstart A real RSVP in a real event in under five minutes. The first two need no account. "Copy as prompt" text for a coding agent: ```text Add a WhoComing RSVP form to this project for the event evt_demo0000000000000001. WhoComing is an RSVP widget and API. Guests RSVP without an account and never leave the page. Pick the option that fits this codebase: 1. Plain HTML, or any site where I can paste markup (WordPress, Webflow, Astro, Vue, Svelte). Put this where the form should appear: The script tag can go once per page, in the head or anywhere before the element. 2. React or Next.js. Install @whocoming/react and render: import { WhoComingRsvp } from "@whocoming/react"; console.log(detail.rsvpId, detail.status)} /> In the Next.js App Router, render it from a client component ("use client"). 3. Server side only. Create RSVPs with the REST API and a secret key kept on the server: curl -X POST https://api.whocoming.com/v1/events/evt_demo0000000000000001/rsvps \ -H "Authorization: Bearer $WHOCOMING_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"name":"Ada Lovelace","email":"ada@example.com","guests":1}' Rules: - Never put a secret key (wc_live_... or wc_test_...) in browser code. The widget needs no key. - Use a wc_test_ key while building. Test mode sends no real email and does not count toward usage. - Style the widget with the CSS variables --wc-accent, --wc-radius, --wc-font, --wc-bg and --wc-text, or with ::part(card), ::part(button) and ::part(input). Docs: https://whocoming.com/docs/quickstart Full docs as plain text: https://whocoming.com/llms-full.txt ``` ## 1. Get a sandbox (no account) One request gives you a test organization, a `wc_test_` secret key and a sample event. Everything in it is deleted after 24 hours. ```bash curl -X POST https://api.whocoming.com/v1/sandbox ``` ```json title="Response (shortened)" { "organization": { "id": "org_...", "name": "...", "slug": "..." }, "api_key": "wc_test_...", "expires_at": "2026-11-16T15:04:05Z", "event": { "id": "evt_...", "title": "...", "mode": "test", "...": "..." } } ``` Keep `api_key` and `event.id`. The key is shown only once. Sandboxes are limited per IP address; if you hit the limit you get a `429` with the code `sandbox_limit`. In the examples below, replace `evt_demo0000000000000001` with your `event.id` and `wc_test_...` with your `api_key`. ## 2. Add an RSVP Pick the way that fits your project. Paste this into any HTML page, where the form should appear: ```html title="index.html" ``` Serve the folder (for example `npx serve .`) and open the page. Click **RSVP**, fill in a name and email, and send. The widget needs no key. It talks only to the public part of the API, which shows what a guest may see and nothing more. ```bash npm install @whocoming/react ``` ```tsx title="Rsvp.tsx" import { WhoComingRsvp } from "@whocoming/react"; export function Rsvp() { return ( console.log("RSVP", detail.rsvpId, detail.status)} /> ); } ``` In the Next.js App Router, put `"use client"` at the top of the file. Render it, click **RSVP** and send the form. Create the RSVP from your server with the secret key: ```bash curl -X POST https://api.whocoming.com/v1/events/evt_demo0000000000000001/rsvps \ -H "Authorization: Bearer wc_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"name":"Ada Lovelace","email":"ada@example.com","guests":1}' ``` ```json title="201 Created" { "id": "rsvp_...", "event_id": "evt_demo0000000000000001", "mode": "test", "name": "Ada Lovelace", "email": "ada@example.com", "status": "going", "guests": 1, "answers": null, "source": "api", "locked": false, "checked_in_at": null, "created_at": "2026-11-15T15:04:05Z", "updated_at": "2026-11-15T15:04:05Z" } ``` If the event were full, `status` would be `waitlisted` (when the event has a waitlist) or you would get a `409` with the code `capacity_reached`. ## 3. See it on the guest list ```bash curl "https://api.whocoming.com/v1/events/evt_demo0000000000000001/rsvps?status=going" \ -H "Authorization: Bearer wc_test_..." ``` ```json { "data": [{ "id": "rsvp_...", "name": "Ada Lovelace", "status": "going", "guests": 1, "...": "..." }], "next_cursor": null } ``` That's a real RSVP. It is in test mode, so no email went out and it does not count toward any plan. ## Next - Keep it: [create a free account](https://whocoming.com/sign-in) and swap in your own event ID and key. The code does not change. - Put it on your platform: [plain HTML](https://whocoming.com/docs/guides/html), [Next.js](https://whocoming.com/docs/guides/nextjs), [WordPress](https://whocoming.com/docs/guides/wordpress), [Webflow](https://whocoming.com/docs/guides/webflow). - Make it yours: [theming](https://whocoming.com/docs/embed/theming) and [text](https://whocoming.com/docs/embed/strings). - React to RSVPs on your server: [webhooks](https://whocoming.com/docs/webhooks). --- # Plain HTML URL: https://whocoming.com/docs/guides/html Two lines on any page. No build step, no framework, no key. Paste this where the RSVP form should appear: ```html ``` Replace `evt_demo0000000000000001` with your event's ID, from the dashboard or from `GET /v1/events`. ## Where to paste it - **The script tag** goes once per page. Put it in `` or anywhere before the closing ``. `async` means it never blocks your page from rendering. - **The element** goes where the card should appear. It fills the width of its container, between 280 and 480 pixels wide, so put it in a column or a card. Several events on one page? Load the script once and add one element per event: ```html ``` ## Match your site ```html ``` See [attributes](https://whocoming.com/docs/embed) and [theming](https://whocoming.com/docs/embed/theming) for the full list. ## Know when someone RSVPs The element fires DOM events you can listen to, for analytics or a thank-you message: ```html ``` See [DOM events](https://whocoming.com/docs/embed/events). ## If scripts are blocked Some site builders do not allow script tags. Use the [iframe](https://whocoming.com/docs/embed/fallbacks#iframe) instead. --- # Next.js URL: https://whocoming.com/docs/guides/nextjs Add the RSVP widget to a Next.js App Router page, and create RSVPs from a server action. ## The widget ```bash npm install @whocoming/react ``` ```tsx title="app/events/rsvp.tsx" "use client"; import { WhoComingRsvp } from "@whocoming/react"; export function Rsvp({ eventId }: { eventId: string }) { return ( console.log("RSVP", detail.rsvpId, detail.status)} /> ); } ``` ```tsx title="app/events/page.tsx" import { Rsvp } from "./rsvp"; export default function EventsPage() { return (

Friday Night Magic

); } ``` The page itself stays a Server Component; only the small `rsvp.tsx` file runs in the browser. ### Without the React package The custom element works in JSX as is. Load the script with `next/script` and tell TypeScript about the tag once: ```tsx title="app/events/page.tsx" import Script from "next/script"; export default function EventsPage() { return ( <> ``` 4. Replace the event ID with yours, then **Preview** or **Update**. The editor shows the code, not the widget. Use **Preview** to see the card. ## If the script disappears on save WordPress removes ` ``` 3. Replace the event ID with yours, **Save and close**, then publish. The Designer canvas does not run scripts, so the widget appears only on the published site or in preview. ## Use it on many pages Put the script tag in **Site settings, Custom code, Head code** once: ```html ``` Then each Code Embed needs only the element: ```html ``` ## With a CMS collection Add a plain text field such as **WhoComing event ID** to your Events collection. In the collection template, put a Code Embed with the element and insert the field as the `event` value using **Add field**: ```html ``` Each event page then shows its own RSVP form. ## Styling The widget takes your site's font. Set colors on the element with a class or in the page's custom code: ```html ``` See [theming](https://whocoming.com/docs/embed/theming). --- # Vue, Svelte and others URL: https://whocoming.com/docs/guides/other-frameworks The widget is a standard custom element, so it works in every framework without a wrapper. `` is a [custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements). Every framework that renders HTML can render it. Load the script once, then use the tag like any other. ```html ``` ## Vue Tell Vue the tag is not a Vue component, so it does not warn: ```ts title="vite.config.ts" import vue from "@vitejs/plugin-vue"; import { defineConfig } from "vite"; export default defineConfig({ plugins: [ vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === "whocoming-rsvp" } }, }), ], }); ``` ```vue title="Rsvp.vue" ``` ## Svelte ```svelte title="Rsvp.svelte" ``` The event name contains a colon, so listen with `addEventListener` rather than an `on...` attribute. ## Astro ```astro title="src/components/Rsvp.astro" --- const { eventId } = Astro.props; --- ``` ## Angular Add `CUSTOM_ELEMENTS_SCHEMA` to the component that uses the tag: ```ts title="rsvp.component.ts" import { Component, CUSTOM_ELEMENTS_SCHEMA, Input } from "@angular/core"; @Component({ selector: "app-rsvp", standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ``, }) export class RsvpComponent { @Input({ required: true }) eventId!: string; } ``` ## Anything else Squarespace (Code block), Wix (Embed HTML), Framer (Embed), Ghost (HTML card), Shopify (Custom Liquid section) and plain server templates all take the same two lines. If a builder strips script tags, use the [iframe](https://whocoming.com/docs/embed/fallbacks#iframe). When the element's attributes change (for example a different `event`), the widget updates in place. Removing the element from the page tears it down. --- # Events URL: https://whocoming.com/docs/concepts/events What an event holds, how its time works, and the difference between status and visibility. An event is one thing people RSVP to: a date and time, a place (or an online link), an optional cap, and optional questions. ```bash curl -X POST https://api.whocoming.com/v1/events \ -H "Authorization: Bearer wc_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "title": "Friday Night Magic", "starts_at": "2027-01-08T18:30:00", "ends_at": "2027-01-08T22:00:00", "timezone": "America/Detroit", "location_name": "Gotta Gacha", "capacity": 32, "max_guests": 1, "waitlist_enabled": true, "price_note": "$10 at the door", "fields": [{ "key": "deck", "label": "Deck name", "type": "text", "required": false }] }' ``` Only `title`, `starts_at` and `timezone` are required. Full field list: [Create an event](https://whocoming.com/docs/reference/events/create-event). Every field has a size or range [limit](https://whocoming.com/docs/api/limits), and `online_url` and `cover_image_url` must be `https://` links. ## Time - `timezone` is an IANA name such as `America/Detroit`. The widget and hosted page show times in the event's zone. - You may send `starts_at` and `ends_at` without an offset (`2027-01-08T18:30:00`); they are then read in the event's `timezone`. That is usually what you want, because it stays right across daylight saving changes. - Responses always include the offset: `2027-01-08T18:30:00-05:00`. - `ends_at` is optional. Without it, the event counts as ended once `starts_at` has passed. ## Status | `status` | Meaning | | --- | --- | | `draft` | Not taking RSVPs from guests. The API and dashboard can still add guests. | | `published` | Live. The default when you create an event through the API. | | `cancelled` | Set with `PATCH`. Guests who were going or waitlisted are emailed, and an `event.cancelled` webhook is sent. | To remove an event and its guest list for good, use `DELETE /v1/events/{id}`. To keep the list and tell guests, cancel it instead. ## Visibility | `visibility` | Widget and link | Listed on your calendar | Indexed by search engines | | --- | --- | --- | --- | | `public` | Yes | Yes | Yes | | `unlisted` | Yes | No | No | | `private` | No | No | No | A private event is visible only through the secret-key API and the dashboard. The public API answers `404 event_not_found` for it. ## Custom questions `fields` is an ordered list of questions shown on the form, up to 100 (fewer on smaller plans). Each has a `key` (lowercase letters, digits and underscores, unique within the event), a `label`, a `type` and `required`, and a `select` question has `options` (at least one, no repeats): | `type` | Answer in `answers` | | --- | --- | | `text`, `textarea` | String | | `select` | String, one of `options` | | `number` | Number | | `checkbox` | Boolean | Answers come back on each RSVP keyed by field `key`, for example `{ "deck": "Mono red aggro" }`. The number of fields per event depends on your [plan](https://whocoming.com/docs/concepts/plans-and-limits). Answers are checked against the questions wherever they come from. Each value must have its question's type (a `select` answer must be one of the `options`), and a key the event has no question for is refused with `400 validation_failed`, naming the field as `answers.`. Text answers are trimmed, and empty ones are left out. One difference: - **Guests** (the widget, hosted pages and the manage link) must answer every `required` question. - **Your API key** may leave required questions out, so you can import guests who never saw the form. What you do send is still checked. For a `checkbox`, a required question means the box must be ticked. The dashboard's form editor has a ready-made "I am 13 or older, or I am a parent or guardian RSVPing for a child" checkbox; forms never ask for a date of birth. ## Counts Every event carries `counts`: ```json { "going": 12, "waitlisted": 0, "spots_left": 20 } ``` `going` counts seats, not RSVPs: an RSVP with `guests: 1` takes two seats. `spots_left` is `null` when the event has no cap. See [capacity and the waitlist](https://whocoming.com/docs/concepts/capacity-and-waitlist). --- # Recurring series URL: 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. A series is a repeating event, like "every Friday at 6:30 pm". It is a rule, not a guest list: WhoComing creates a separate event for each date about 90 days ahead, and guests RSVP to those events. Each occurrence has its own ID, capacity count and waitlist. ```bash curl -X POST https://api.whocoming.com/v1/series \ -H "Authorization: Bearer wc_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "title": "Friday Night Magic", "recurrence": { "frequency": "weekly", "weekday": "friday" }, "timezone": "America/Detroit", "starts_on": "2027-01-08", "start_time": "18:30", "duration_minutes": 210, "template": { "location_name": "Gotta Gacha", "capacity": 32, "waitlist_enabled": true } }' ``` ## Recurrence | `recurrence` | Means | | --- | --- | | `{ "frequency": "weekly", "weekday": "friday" }` | Every Friday | | `{ "frequency": "every_two_weeks", "weekday": "friday" }` | Every other Friday, counted from `starts_on` | | `{ "frequency": "monthly", "weekday": "friday", "week_of_month": 2 }` | The second Friday of each month | | `{ "frequency": "monthly", "weekday": "sunday", "week_of_month": -1 }` | The last Sunday of each month | `week_of_month` is `1` to `4`, or `-1` for the last one. The response also carries `rrule`, the same rule as an iCalendar RRULE, for reference. ## Time `start_time` is a wall-clock time (`HH:MM`, 24-hour) in the series `timezone`, so "6:30 pm" stays 6:30 pm after daylight saving changes. `duration_minutes` sets each occurrence's end. `starts_on` is the first possible date; `ends_on` (optional) the last. ## Template `template` holds the event settings copied onto every occurrence: location, capacity, waitlist, plus-ones, visibility, price note, cover image and custom fields. ## Changing and ending - `PATCH /v1/series/{id}` changes the fields you send. Changes apply to future occurrences. - To change one date only (a holiday, a special guest), update that occurrence's event with `PATCH /v1/events/{id}`. - `DELETE /v1/series/{id}` ends the series: no new occurrences are created. The series is kept with `status: "ended"`, and events already created stay, with their guests. Occurrences carry `series_id`, so `GET /v1/events` results can be grouped by series. The Free plan allows one active series; Starter and Pro allow any number. See [plans and limits](https://whocoming.com/docs/concepts/plans-and-limits). --- # RSVPs and statuses URL: https://whocoming.com/docs/concepts/rsvps What an RSVP is, the four statuses, where RSVPs come from, and how guests change their own. An RSVP is one guest's answer to one event: a name, an email, how many extra guests they bring, answers to your questions, and a status. Guests never create an account. ## Statuses | `status` | Meaning | Takes seats | | --- | --- | --- | | `going` | Coming. | Yes, `1 + guests` | | `waitlisted` | The event was full; they are in line for a spot. | No | | `not_going` | Answered no. Useful for invitations. | No | | `cancelled` | Was going or waitlisted, then cancelled. | No | You can create an RSVP as `going` (the default) or `not_going`. `waitlisted` is decided for you when the event is full. Set `cancelled` with `PATCH` to cancel; the seat is freed and the [waitlist](https://whocoming.com/docs/concepts/capacity-and-waitlist) moves up. ## One RSVP per email per event A second RSVP with the same email for the same event is refused with `409 already_registered`. Through the widget, the guest gets their manage link emailed again instead, so they can change the first one. Nobody can edit someone else's RSVP by knowing their email. If the earlier RSVP was `cancelled` or `not_going`, a new RSVP reuses it (same ID) and switches it back on. ## Sources `source` records where an RSVP came from: `embed` (the widget), `page` (a hosted event page), `api` or `dashboard`. You never set it on the secret-key API; it is always `api` there. The public RSVP endpoint takes `source: "embed"` (the default) or `"page"`, and the widget sends `page` when its [`source` attribute](https://whocoming.com/docs/embed#attributes) says so. Guests can only RSVP through `embed` and `page` while an event is published and has not ended; your API key and the dashboard can still add guests to draft, private or past events. ## Guests change their own RSVP Every RSVP made through the widget or a hosted page gets a manage link, emailed to the guest and shown after they RSVP. It opens a page where they can change their plus-ones and answers, or cancel. Under the hood that is the public `GET` and `PATCH /v1/public/rsvps/{manage_token}`. ## Check-in `POST /v1/rsvps/{id}/check-in` marks a guest as arrived and sets `checked_in_at`. Checking in twice keeps the first time. Only a `going` RSVP can be checked in: a cancelled, not going or waitlisted one answers `409 rsvp_not_going`. In the dashboard's door list, a check-in can be undone whatever the guest's status. ## Delete or cancel - `PATCH /v1/rsvps/{id}` with `{ "status": "cancelled" }` keeps a record and frees the seat. - `DELETE /v1/rsvps/{id}` removes the RSVP and its guest data for good. To remove a person from every event at once, see [data rights](https://whocoming.com/docs/data-rights). --- # Capacity and waitlist URL: https://whocoming.com/docs/concepts/capacity-and-waitlist How seats are counted, what happens when an event is full, and how the waitlist moves. ## Seats `capacity` is a number of seats, or `null` for no limit. Each going RSVP takes `1 + guests` seats, so Ada plus one friend takes two. `max_guests` caps the plus-ones per RSVP (0 to 100); asking for more answers `422 too_many_guests`. `counts` on every event shows where you stand: ```json { "going": 30, "waitlisted": 3, "spots_left": 2 } ``` The widget turns that into "30 going, 2 spots left". ## When an RSVP does not fit Seat checks happen inside the database with the event row locked, so two guests can never take the last seat at the same moment. | The event | The RSVP gets | | --- | --- | | Has room for `1 + guests` | `going` | | Is full (or the party does not fit) and `waitlist_enabled` is `true` | `waitlisted` | | Is full and has no waitlist | `409 capacity_reached` | ## How the waitlist moves When seats free up (a cancellation, a deleted RSVP, or you raise or remove `capacity`), waitlisted guests are promoted in the order they joined. A party too big for the free seats is skipped, and the next one that fits moves up. Each promoted guest: - changes to `going`, - gets an email saying they are in, - triggers an `rsvp.promoted` [webhook](https://whocoming.com/docs/webhooks). Promotion stops once an event is cancelled or has ended. ## Over your plan's RSVP limit Capacity is about seats at your event. Your plan's monthly RSVP count is separate, and it never turns a guest away. See [locked RSVPs](https://whocoming.com/docs/concepts/locked-rsvps). --- # Test mode URL: 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. Every organization has two modes, live and test, each with its own events, RSVPs, series and webhook endpoints. The key you use picks the mode: | Key prefix | Mode | | --- | --- | | `wc_live_` | Live: real guests, real email, counted toward your plan | | `wc_test_` | Test: everything else | ## What test mode guarantees - **Isolated data.** A test key can never read or change live data, and the other way round. Asking a test key for a live event's ID answers `404`, as if it did not exist. Every object carries `mode` so you can tell which side it came from. - **No real email.** Confirmations, reminders and waitlist emails are recorded as `skipped` but never sent, even to a real address. - **Not metered.** Test RSVPs never count toward your monthly RSVP limit and are never locked. - **Webhooks still fire**, to the endpoints you registered in test mode, with `"mode": "test"` in the envelope. They are signed and retried exactly like live ones. That is how you test your handler. - **The dashboard has a switch.** The mode toggle at the top of the dashboard shows test data, test keys and test webhook endpoints; nothing you do there touches live guests. - **Same API.** Endpoints, fields, errors and rate limits behave exactly as in live mode, so moving to live is a key swap. ## The sandbox `POST /v1/sandbox` creates a throwaway test organization with a key and a sample event, without an account. It lasts 24 hours. The [quickstart](https://whocoming.com/docs/quickstart) uses it. ## Going live 1. Create a live key in the dashboard. 2. Create your real events (test events do not move over). 3. Register your webhook endpoints again with the live key; each mode has its own endpoints and signing secrets. 4. Swap `wc_test_` for `wc_live_` in your server's environment. The widget needs no key. It follows the event: a test event shows test data. --- # Plans and limits URL: https://whocoming.com/docs/concepts/plans-and-limits What each plan includes, how RSVPs are counted, and what happens at a limit. The API, the widget and hosted pages are on every plan, including Free. | | Free | Starter | Pro | | --- | --- | --- | --- | | Price, monthly | $0 | $19 | $49 | | Price, annual | $0 | $190 | $490 | | RSVPs per month, pooled | 100 | 1,000 | 5,000 | | Events | Unlimited | Unlimited | Unlimited | | Embed, API, hosted pages | Yes | Yes | Yes | | Custom fields per event | 5 | 20 | Unlimited | | API keys | 2 | 5 | 20 | | Webhook endpoints | 1 | 5 | 20 | | Team members | 1 | 3 | 10 | | Reminder emails | No | Yes | Yes | | Active recurring series | 1 | Unlimited | Unlimited | | Remove "RSVP by WhoComing" | No | No | Yes | | API requests per minute, per key | 60 | 300 | 600 | | Over the RSVP limit | Accepted and locked | $10 per extra 1,000 | $10 per extra 1,000 | This table is rendered from the same plan definitions the API enforces. ## How RSVPs are counted - An RSVP counts when it is created in live mode as `going` or `waitlisted`. Cancelling it later does not give it back. - RSVPs are pooled across every event in your organization. - The period is the calendar month in UTC. - Test mode never counts. - `GET /v1/usage` returns this month's count, your limit and your other limits. ```json title="GET /v1/usage (shortened)" { "mode": "live", "plan": "free", "rsvps": { "used": 87, "limit": 100, "remaining": 13, "locked": 0, "overage_blocks": 0 }, "limits": { "api_keys": 2, "webhook_endpoints": 1, "rate_limit_per_minute": 60, "...": "..." } } ``` ## At a limit - **RSVPs on Free:** the guest is never turned away. Their RSVP is accepted and confirmed as usual, and its details are locked until you upgrade or the month ends. See [locked RSVPs](https://whocoming.com/docs/concepts/locked-rsvps). - **RSVPs on Starter and Pro:** nothing changes for you or the guest. Extra RSVPs are billed in blocks of 1,000 at the end of the month. - **Everything else** (API keys, webhook endpoints, custom fields, active series): creating one more answers `403 plan_limit`. - **Requests per minute:** over the per-key rate answers `429 rate_limited`. See [rate limits](https://whocoming.com/docs/api/rate-limits). The owner gets an email at 80% and at 100% of the monthly RSVP limit. --- # Locked RSVPs on Free URL: 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. WhoComing never turns a guest away because of your bill. On the Free plan, once your organization reaches its monthly RSVP limit (see [plans and limits](https://whocoming.com/docs/concepts/plans-and-limits)), the next RSVPs are **locked**: - The guest sees the normal success message and gets the normal confirmation email, with their manage link. - Counts stay accurate. Capacity and the waitlist work as usual. - You can see that the RSVP exists, but not who it is. ## What a locked RSVP looks like Everywhere you read RSVPs (the API, webhooks, the dashboard and CSV exports), a locked RSVP has `locked: true` and no personal details: ```json { "id": "rsvp_...", "event_id": "evt_demo0000000000000001", "mode": "live", "name": null, "email": null, "status": "going", "guests": 1, "answers": null, "source": "embed", "locked": true, "checked_in_at": null, "created_at": "2026-11-20T18:02:11Z", "updated_at": "2026-11-20T18:02:11Z" } ``` Your code should treat `name`, `email` and `answers` as nullable anyway: they are also `null` after the [retention period](https://whocoming.com/docs/data-rights#retention). ## Unlocking Locks clear when you upgrade to Starter or Pro, or at the start of the next month. Nothing needs to be re-sent: the RSVPs were already confirmed. `GET /v1/usage` reports how many RSVPs are locked this month in `rsvps.locked`. Test mode is never metered, so test RSVPs are never locked. --- # Embed reference URL: https://whocoming.com/docs/embed The element, its attributes, and what it does on your page. ```html ``` `embed.js` is a small loader (under 2 KB gzipped). It registers the `` element, shows a loading card straight away, and fetches the widget itself (under 30 KB gzipped) once, however many elements are on the page. ## Attributes | Attribute | Values | Default | Notes | | --- | --- | --- | --- | | `event` | Event ID | Required | The event to show, such as `evt_demo0000000000000001`. | | `theme` | `auto`, `light`, `dark` | `auto` | `auto` follows the visitor's system setting. | | `accent` | Hex color, such as `#3451f5` | Organization accent, else neutral | Button and focus color. Text on top switches between dark and light for contrast. | | `compact` | Boolean | Off | Tighter spacing, no price note or waitlist note, and the button sits beside the title when there is room. For sidebars and lists. | | `hide-count` | Boolean | Off | Hides "12 going, 4 spots left". | | `strings` | JSON object | English defaults | Overrides any UI text. See [Text and translation](https://whocoming.com/docs/embed/strings). | | `api-base` | URL | `https://api.whocoming.com` | Where the widget sends requests. Only for local development against your own server. | | `source` | `embed`, `page` | `embed` | Where the RSVP is recorded as coming from, shown as the RSVP's `source`. WhoComing's hosted pages set `page`; leave it out on your own site. Any other value counts as `embed`. | | `no-jsonld` | Boolean | Off | Stops the widget adding its Event JSON-LD to your page. Use it when the page already has Event markup for this event, so search engines see one Event, not two. | Boolean attributes are on when present: ``. `compact="false"` also counts as off. Changing an attribute updates the widget in place, so frameworks that re-render attributes just work. ## What the guest sees The card shows the title, date and place in the event's timezone, and the count ("12 going, 4 spots left"). The button opens the form: name, email, plus-ones (when the event allows them), your [custom questions](https://whocoming.com/docs/concepts/events#custom-questions), and "Remember me on this device". After sending, the guest sees a confirmation, "Add to calendar" links (Google Calendar, and an `.ics` file for Apple and Outlook) and their manage link. The card also handles a full event (with or without a waitlist), an ended or cancelled event, a missing event, and network errors with a retry button. ## What it adds to your page - **Event structured data.** For a public, live event, the widget adds one ` ``` --- # Theming URL: https://whocoming.com/docs/embed/theming Restyle the widget with five CSS variables and three ::part() names. The widget takes your page's font by default and comes in light and dark. Everything else you set from your own stylesheet. ## Light and dark ```html ``` `theme` is `auto` (follow the visitor's system setting, the default), `light` or `dark`. ## CSS variables Set these on the element, or on any ancestor: | Variable | Sets | Default | | --- | --- | --- | | `--wc-accent` | Primary button and focus color | Organization accent, else the text color | | `--wc-radius` | Corner radius of the card and controls | `0.75em` | | `--wc-font` | Font family | Inherited from your page | | `--wc-bg` | Card background | White, or near-black in dark | | `--wc-text` | Text color. Muted text and borders are mixed from it and `--wc-bg` | Near-black, or near-white in dark | ```css whocoming-rsvp { --wc-accent: #3451f5; --wc-radius: 4px; --wc-font: "Georgia", serif; --wc-bg: #fffaf0; --wc-text: #1f1a17; } ``` Text on the accent switches between dark and light automatically, so any accent stays readable. The `accent` attribute wins over `--wc-accent`, and both win over the organization's accent from the dashboard. The widget reads `--wc-accent` when it starts and when an attribute changes; set it before the widget loads rather than animating it. ## Parts For anything the variables do not cover, style the widget's parts with `::part()`: | Part | Element | | --- | --- | | `card` | The outer card | | `button` | Every button: RSVP, send, back, retry | | `input` | Every text field, select and text area in the form | ```css whocoming-rsvp::part(card) { box-shadow: 0 8px 24px rgb(0 0 0 / 0.08); border: none; } whocoming-rsvp::part(button) { text-transform: uppercase; letter-spacing: 0.04em; } whocoming-rsvp::part(input) { background: #f6f6f6; } ``` Parts and variables are the supported styling surface. Class names inside the Shadow DOM may change in any release; these will not. ## Sizing The widget is `display: block` and fills its container between 280 and 480 pixels wide. Control width with the container, or on the element: ```css whocoming-rsvp { max-width: 360px; margin-inline: auto; } ``` --- # DOM events URL: 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. Listen on the element, or anywhere above it (every event bubbles and is `composed`, so it leaves the Shadow DOM): ```js document.addEventListener("whocoming:rsvp", (event) => { const { rsvp_id, status } = event.detail; console.log("RSVP", rsvp_id, status); }); ``` `event.target` is the `` element that fired it, which tells you which event it was when a page has several. ## `whocoming:ready` The event loaded and the card is showing. Fired once per event ID. ```ts detail: { event: string; // "evt_demo0000000000000001" state: "open" | "full_waitlist" | "full" | "ended" | "cancelled"; } ``` ## `whocoming:rsvp` A guest sent the form and the RSVP was saved. ```ts detail: { rsvp_id: string; // "rsvp_..." status: "going" | "waitlisted"; } ``` This is the browser-side signal, good for analytics and thank-you messages. For anything that must not be missed (adding a guest to your CRM, for example), use the `rsvp.created` [webhook](https://whocoming.com/docs/webhooks), which is retried until your server confirms it. ## `whocoming:error` Something went wrong. The widget already shows the guest a message; this is for your logs. ```ts detail: { code: string; } ``` `code` is one of the API's [error codes](https://whocoming.com/docs/errors) (such as `capacity_reached`, `already_registered`, `rate_limited` or `event_not_found`), or one of these, which come from the browser side: | `code` | Meaning | | --- | --- | | `missing_event` | The element has no `event` attribute. | | `load_failed` | The widget script could not be downloaded (offline, or blocked by an extension or policy). | | `network_error` | A request to the API never got an answer. | | `bot_check_failed` | The Cloudflare Turnstile check could not run or did not pass. | | `internal_error` | An unexpected response. | ## TypeScript ```ts type WhoComingReady = CustomEvent<{ event: string; state: string }>; type WhoComingRsvp = CustomEvent<{ rsvp_id: string; status: string }>; type WhoComingError = CustomEvent<{ code: string }>; document.addEventListener("whocoming:rsvp", (event) => { const { detail } = event as WhoComingRsvp; }); ``` With React, [`@whocoming/react`](https://whocoming.com/docs/sdk#react) exposes these as `onReady`, `onRsvp` and `onError` props. --- # Text and translation URL: 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. Every word the widget shows can be replaced. Pass a JSON object in the `strings` attribute; keys you leave out keep their English default. ```html ``` Use single quotes around the attribute so the JSON's double quotes do not need escaping. ## Rules - Unknown keys, non-string values and invalid JSON are ignored. A broken override never breaks the widget. - `{placeholders}` are filled in for you: `"{going} going, {left} spots left"`. Keep the ones you need; an unknown placeholder is shown as written. - `locale` is not text. It sets the language for dates (a BCP 47 tag such as `fr` or `es-MX`). When empty, the widget uses your page's ``. ## A full translation ```html ... ``` From JavaScript, build the object and set it with `JSON.stringify`: ```js const widget = document.querySelector("whocoming-rsvp"); widget.setAttribute("strings", JSON.stringify({ rsvp: "Save my seat" })); ``` ## Every key This list is read from the widget's source, so it is always complete. | Key | Default | Notes | | --- | --- | --- | | `locale` | (empty) | Not text: the BCP 47 language for dates, such as `fr`. Empty means the page's `lang`. | | `loading` | Loading event | | | `rsvp` | RSVP | | | `joinWaitlist` | Join the waitlist | | | `countFirst` | Be the first to RSVP | | | `countGoing` | {going} going | Placeholders: `{going}`. | | `countSpots` | {going} going, {left} spots left | Placeholders: `{going}`, `{left}`. | | `countOneSpot` | {going} going, 1 spot left | Placeholders: `{going}`. | | `countSpotsOnly` | {left} spots left | Placeholders: `{left}`. | | `countFull` | {going} going, no spots left | Placeholders: `{going}`. | | `countWaitlist` | {going} going, {waitlisted} on the waitlist | Placeholders: `{going}`, `{waitlisted}`. | | `online` | Online | | | `full` | This event is full. | | | `fullWaitlistNote` | It's full, but you can join the waitlist. We'll email you if a spot opens up. | | | `ended` | This event has ended. | | | `cancelled` | This event was cancelled. | | | `loadError` | We couldn't load this event. | | | `notFound` | We couldn't find this event. | | | `missingEvent` | This RSVP widget is missing its event ID. | | | `retry` | Try again | | | `formTitle` | Your details | | | `name` | Name | | | `email` | Email | | | `guests` | Bringing anyone? | | | `guestsNone` | Just me | | | `guestsSome` | Me + {n} | Placeholders: `{n}`, the number of extra guests. | | `chooseOne` | Choose one | | | `optional` | (optional) | | | `remember` | Remember me on this device | | | `submit` | Send RSVP | | | `submitWaitlist` | Join the waitlist | | | `sending` | Sending | | | `back` | Back | | | `honeypot` | Leave this empty | Label of the hidden anti-spam field. Screen readers can reach it. | | `needName` | Please enter your name. | | | `needEmail` | Please enter a valid email address. | | | `needField` | Please fill this in. | | | `needTick` | Please tick this box. | | | `fixErrors` | Please check the highlighted fields. | | | `goingTitle` | You're in | | | `goingBody` | We sent the details to {email}. | Placeholders: `{email}`. | | `waitlistTitle` | You're on the waitlist | | | `waitlistBody` | We'll email {email} if a spot opens up. | Placeholders: `{email}`. | | `addToCalendar` | Add to calendar | | | `googleCalendar` | Google Calendar | | | `icsCalendar` | Apple or Outlook | | | `manage` | Change or cancel your RSVP | | | `badge` | RSVP by WhoComing | | | `badgePitch` | Running your own event? Collect RSVPs free. | | | `errAlreadyRegistered` | You're already on the list for this event. We've emailed your manage link again. | | | `errCapacityReached` | Sorry, the last spot just went. | | | `errRateLimited` | Too many tries. Please wait a minute and try again. | | | `errBotCheckFailed` | We couldn't check that you're not a bot. Please try again. | | | `errEventCancelled` | This event was cancelled, so it can't take RSVPs. | | | `errEventEnded` | This event has ended, so it can't take RSVPs. | | | `errTooManyGuests` | That's more guests than this event allows. | | | `errNotOpen` | This event isn't taking RSVPs right now. | | | `errOriginNotAllowed` | This website isn't set up to take RSVPs for this event. | | | `errValidation` | Please check your details and try again. | | | `errGeneric` | Something went wrong. Please try again. | | --- # Iframe and legacy script URL: 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. ## Iframe For hosts that do not allow ` ``` Without a script, the iframe keeps the `height` you gave it. Pick one that fits your form (more custom questions need more room). ### Trade-offs compared with the element - The iframe only grows to fit its content with the script above. - Your CSS variables and `::part()` rules cannot reach inside it, and it does not fire [DOM events](https://whocoming.com/docs/embed/events) on your page. - Event structured data is not added to your page. Use the element when you can. ## Legacy single script Some builders accept one script tag but no custom HTML. Put the event on the script itself, and the widget is inserted right after it: ```html ``` Every [attribute](https://whocoming.com/docs/embed) works with a `data-` prefix: ```html ``` This form places one widget per script tag. For several events on one page, use the element. --- # Privacy URL: 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. What the widget does on your visitors' browsers, in full: - **No cookies.** Requests to the API are sent without credentials, so no cookie is sent or set, whatever the API does. - **No analytics, no tracking pixels, no fingerprinting.** - **No storage by default.** Nothing goes into `localStorage`, `sessionStorage` or IndexedDB, unless the guest ticks **Remember me on this device**. Then their name and email are saved in `localStorage` under the key `whocoming:guest`, to fill the form next time. Sending an RSVP with the box unticked deletes it. - **Requests go to three places only:** our CDN for the widget's own script (`cdn.whocoming.com`), our API (`api.whocoming.com`), and Cloudflare Turnstile (`challenges.cloudflare.com`), which is loaded only when a guest sends the form, to keep bots out. Turnstile usually runs invisibly and shows a challenge only when Cloudflare needs one. - **No error reporting to third parties.** Errors are fired as a [`whocoming:error`](https://whocoming.com/docs/embed/events#whocomingerror) event on your page and go nowhere else. ## What a guest's RSVP stores Name, email, plus-ones, answers to your questions, and when they RSVPed. The IP address is hashed before it is used for rate limiting, and hashes are kept for at most 30 days. See [data rights](https://whocoming.com/docs/data-rights) for export, erasure and retention. ## Cookie banners Because the widget sets no cookies and stores nothing without the guest's own action, it does not by itself need a cookie consent banner in most jurisdictions. Check with your own advisers for your situation. --- # Authentication and scopes URL: https://whocoming.com/docs/api/authentication Secret keys for your server, scopes per key, and the public surface that needs no key. Base URL: `https://api.whocoming.com`. JSON in and out, `snake_case` field names. The OpenAPI 3.1 document is at [`/v1/openapi.json`](https://api.whocoming.com/v1/openapi.json), and every endpoint is in the [API reference](https://whocoming.com/docs/reference/events/list-events). ## Secret keys Send your key as a bearer token: ```bash curl https://api.whocoming.com/v1/events \ -H "Authorization: Bearer wc_test_..." ``` - `wc_live_...` keys work on live data. `wc_test_...` keys work on [test data](https://whocoming.com/docs/concepts/test-mode). - Create and revoke keys in the dashboard. A key is shown once, when you create it; we store only a hash. - Keys belong on your server. Never put one in browser code, a mobile app, or a `NEXT_PUBLIC_` variable. A missing, malformed, unknown or revoked key answers `401 unauthorized`. ## Scopes Each key carries a set of scopes. A call outside them answers `403 insufficient_scope`. | Scope | Allows | | --- | --- | | `events:read` | List and read events and series. | | `events:write` | Create, update, cancel and delete events and series. | | `rsvps:read` | List and read RSVPs. Export a guest's data. | | `rsvps:write` | Create, update, check in and delete RSVPs. Erase a guest. | | `webhooks:write` | Manage webhook endpoints, read the delivery log, redeliver. | `GET /v1/usage` works with any key. Give each integration the smallest set it needs: a check-in app needs only `rsvps:read` and `rsvps:write`. ## The public surface Routes under `/v1/public` need no key. They expose only what a guest may see or do, allow requests from any website (CORS), and are what the widget uses: | Endpoint | Does | | --- | --- | | `GET /v1/public/events/{id}` | Event details, form fields and counts. No guest data. | | `POST /v1/public/events/{id}/rsvps` | RSVP as a guest. Needs a Turnstile token. | | `GET`, `PATCH /v1/public/rsvps/{manage_token}` | A guest views, changes or cancels their own RSVP. | | `GET /v1/public/orgs/{slug}/events` | Upcoming public events, for a calendar. | | `GET /v1/public/events/{id}/calendar.ics` | The event as a calendar file. | | `POST /v1/sandbox` | A 24-hour test organization, for trying the API. | Public RSVPs are limited to 5 a minute and 30 an hour per IP address per event. If your organization set allowed websites in the dashboard, a public RSVP from any other origin answers `403 origin_not_allowed`. Private events are never served on the public surface. --- # Pagination URL: https://whocoming.com/docs/api/pagination Lists return { data, next_cursor }. Pass the cursor back to get the next page. Every list endpoint takes two query parameters: | Parameter | Meaning | | --- | --- | | `limit` | Page size, 1 to 100. Defaults to 50. | | `cursor` | The `next_cursor` from the previous page. Omit it for the first page. | And returns: ```json { "data": [{ "id": "evt_...", "...": "..." }], "next_cursor": "eyJ0IjoiMjAyNy0wMS0wOFQyMzozMDowMFoiLCJpIjoiZXZ0XyJ9" } ``` `next_cursor` is `null` on the last page. Treat it as an opaque string: pass it back exactly as you got it, and keep any filters (such as `status`) the same between pages. ## Every page, in a loop ```bash curl "https://api.whocoming.com/v1/events/evt_demo0000000000000001/rsvps?limit=100&status=going" \ -H "Authorization: Bearer wc_test_..." curl "https://api.whocoming.com/v1/events/evt_demo0000000000000001/rsvps?limit=100&status=going&cursor=eyJ0Ijoi..." \ -H "Authorization: Bearer wc_test_..." ``` ```ts async function allRsvps(eventId: string) { const rsvps = []; let cursor: string | null = null; do { const url = new URL(`https://api.whocoming.com/v1/events/${eventId}/rsvps`); url.searchParams.set("limit", "100"); if (cursor) url.searchParams.set("cursor", cursor); const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.WHOCOMING_API_KEY}` }, }); const page = await res.json(); rsvps.push(...page.data); cursor = page.next_cursor; } while (cursor); return rsvps; } ``` The [SDK](https://whocoming.com/docs/sdk) does this for you: `for await (const rsvp of wc.rsvps.list(eventId))`. ## Order | List | Order | | --- | --- | | `GET /v1/events` | Soonest first | | `GET /v1/series` | Newest first | | `GET /v1/events/{id}/rsvps` | Oldest first | | `GET /v1/webhook-deliveries` | Newest first | | `GET /v1/public/orgs/{slug}/events` | Soonest first, upcoming only | --- # Idempotency URL: https://whocoming.com/docs/api/idempotency Send an Idempotency-Key on creating requests so a retry can never create a second RSVP or event. Networks fail. If you send a request and never hear back, you cannot tell whether it ran. An `Idempotency-Key` makes the retry safe: the second request returns the first one's answer instead of doing the work again. ```bash curl -X POST https://api.whocoming.com/v1/events/evt_demo0000000000000001/rsvps \ -H "Authorization: Bearer wc_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 6f1c2a9e-1b7d-4c55-9b0e-3c1d2e4f5a6b" \ -d '{"name":"Ada Lovelace","email":"ada@example.com"}' ``` ## Where it works The creating requests: - `POST /v1/events` - `POST /v1/series` - `POST /v1/events/{id}/rsvps` - `POST /v1/webhook-endpoints` - `POST /v1/public/events/{id}/rsvps` (the public RSVP form; the widget sends a key with every submission) ## The rules - **The key** is any 1 to 255 printable ASCII characters. A fresh UUID per logical operation is the usual choice. Reuse it only for retries of that same operation. - **A replay** (same key, same method, path and body) within 24 hours gets the original status and body back, with the header `Idempotent-Replayed: true`. Nothing runs twice. - **The same key with a different request** answers `409 idempotency_conflict`, before anything is created. Body comparison ignores key order and whitespace in JSON. In particular, reusing a key for another guest never returns the first guest's RSVP. - **While the first request is still running**, a duplicate answers `409 idempotency_conflict`. Retry a moment later and you get the replay. - **Errors you can retry are not stored.** A `5xx` or `429` frees the key, so your retry with the same key actually runs. - Keys are separate per organization and per mode, so a test key and a live key never collide. ## On the public RSVP endpoint `POST /v1/public/events/{id}/rsvps` needs no API key, so its keys are kept per event's organization and mode instead. The rules above apply, with two differences: - `turnstile_token` is left out when comparing bodies, because a bot-check token works only once and a retry fetches a new one. A replay does not run the bot check again. - Only a successful `201` is stored. Any error frees the key, so the guest can fix the form and send again with the same key. A key is also tied to the guest's email: the same key with another email is a different request (`409 idempotency_conflict`), never the first guest's RSVP or manage link. ## And on top of that RSVPs are also protected by a rule in the database: one RSVP per email per event. Even without a key, a duplicate RSVP for the same email answers `409 already_registered` rather than creating a second one. The [SDK](https://whocoming.com/docs/sdk) takes an `idempotencyKey` option and retries `429` and `5xx` responses with backoff, reusing the same key. --- # Rate limits URL: https://whocoming.com/docs/api/rate-limits Requests per minute per key, set by your plan, with the standard RateLimit headers on every response. Secret-key requests are limited per key, per minute, by your plan: | Plan | Requests per minute, per key | | --- | --- | | Free | 60 | | Starter | 300 | | Pro | 600 | See [plans and limits](https://whocoming.com/docs/concepts/plans-and-limits) for the full table. Each key has its own budget, so a nightly sync on one key cannot starve your check-in app on another. ## Headers Rate-limited responses carry: | Header | Meaning | | --- | --- | | `RateLimit-Limit` | Requests allowed in the current window. | | `RateLimit-Remaining` | Requests left in it. | | `RateLimit-Reset` | Seconds until the window resets. | | `Retry-After` | On a `429` only: seconds to wait before trying again. | Over the limit, you get `429` with the code `rate_limited`: ```json { "type": "https://whocoming.com/docs/errors#rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "Too many requests. Try again in 12 seconds.", "request_id": "req_..." } ``` Wait `Retry-After` seconds and retry. A refused request does not use up any of your budget. The [SDK](https://whocoming.com/docs/sdk) does this for you. ## Public endpoints The public surface is limited per visitor's IP address, not per key: - RSVPs (`POST /v1/public/events/{id}/rsvps`): 5 a minute and 30 an hour, per IP address, per event. - Sandboxes (`POST /v1/sandbox`): a few per IP address per hour; over it answers `429 sandbox_limit`. IP addresses are hashed before they are counted. --- # Limits URL: https://whocoming.com/docs/api/limits The size and range limits on every request, and what happens when one is passed. Every text field, list and number you send has a limit. They are generous on purpose: a real venue should never meet one. The same field has the same limit on every endpoint. A request over a limit answers `400 validation_failed`, and `errors[]` names each field by its dotted path, such as `title`, `fields.2.key` or `answers.deck`. See [errors](https://whocoming.com/docs/errors). ## Links are `https://` only `online_url` and `cover_image_url` must start with `https://`. Guests open them from your page and the hosted page, and an `http://` link would load without encryption or be blocked as mixed content. Webhook endpoint URLs follow their own [rules](https://whocoming.com/docs/webhooks#which-urls-are-accepted). ## Custom questions and answers - A question's `key` is what its answer is stored under, so it never changes: lowercase letters, digits and underscores, unique within the event. The dashboard makes one from the question text ("Favorite deck?" becomes `favorite_deck`). - A `select` question needs at least one choice, and no choice may appear twice. - `answers` is an object keyed by question `key`. Each value is text, a number, `true` or `false` (or `null` for no answer); lists are not accepted. Text is checked against its question: up to 500 characters for a short answer, 5,000 for a long answer. ## Plans Some limits are lower on smaller plans: custom questions per event (Free 5, Starter 20), API keys, webhook endpoints and active series. Going over a plan limit answers `403 plan_limit` instead. See [plans and limits](https://whocoming.com/docs/concepts/plans-and-limits). ## Limits only grow Under [versioning](https://whocoming.com/docs/api/versioning) rules, a limit on `/v1` can be raised but never lowered, and a field's format never gets stricter. --- # Versioning URL: https://whocoming.com/docs/api/versioning /v1 only ever grows. Anything breaking waits for /v2, and /v1 keeps working for 12 months after that. The version is in the path: `https://api.whocoming.com/v1/...`. There is no date header to pin and no per-account version to upgrade. ## What we promise for `/v1` We may add: - new endpoints, - new optional request fields and query parameters, - new fields in responses, - new values in a list of event types or error codes, - new webhook event types, which are only sent to endpoints that subscribe to them, - new values in the response fields marked `x-open-enum` in the OpenAPI document and "New values may be added" in the reference: an RSVP's `source`, a question's `type`, a public event's `state`, a delivery's `status`, a usage `plan` and webhook event types, - higher [limits](https://whocoming.com/docs/api/limits): a longer maximum, more items, a wider range. Every other value list in a response (such as an RSVP's `status`, an event's `status` and `visibility`, and `mode`) is closed: a new value there would be a breaking change and waits for `/v2`. We will never, within `/v1`: - remove or rename an endpoint, a field or a parameter, - change a field's type, - make validation stricter (a request that works today keeps working): no new required field or parameter, no lower maximum, no new pattern or format, no value dropped from a list, - make a response field that is always there optional, or let it hold a new type (including `null`), - change what an error code means. A test in our build checks this promise on every change, not just intends it. It records every endpoint, parameter, status code, field, type, format, value list, pattern, length and range limit and required list of the published API, and fails on any change that would remove, rename, retype or tighten one of them. ## What that asks of you - Ignore response fields you do not know. - Do not fail on an error `code` or webhook `type` you do not know; treat it by its HTTP status. - Do not fail on a new value in an open list (see above): show it as-is or fall back to a default. - Store IDs as opaque strings; their length may vary. ## When `/v2` comes Anything breaking waits for `/v2`. When it ships, `/v1` keeps working, unchanged, for at least **12 months** alongside it, so you can move over when it suits you. ## The embed `https://cdn.whocoming.com/embed.js` follows the same rule: the element's tag, attributes, CSS variables, `::part()` names, DOM events and `strings` keys are only ever added to. What changed and when is in the [changelog](https://whocoming.com/changelog). --- # Errors URL: 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. Every error response has the content type `application/problem+json` and this shape: ```json { "type": "https://whocoming.com/docs/errors#validation_failed", "title": "The request is not valid", "status": 400, "code": "validation_failed", "detail": "One field is not valid. See errors for details.", "request_id": "req_4k9x2m7q1c8v5b3n6z0a", "errors": [{ "field": "starts_at", "message": "Required", "code": "required" }] } ``` | Field | Meaning | | --- | --- | | `code` | **Branch on this.** A stable string that never changes meaning. New codes may be added. | | `status` | The HTTP status, repeated. | | `title` | A short summary of the code. | | `detail` | What went wrong this time, in plain words. It may change; do not parse it. | | `type` | A link to this page, at the code's row. | | `request_id` | Quote it when you contact support. Every response, success or not, also sends it as the `X-Request-Id` header. | | `errors` | Only for field problems: one entry per field. | ## Field errors `errors[].field` is a dotted path into your request, such as `email`, `answers.deck` or `fields.0.key`. `errors[].code` is one of: `required`, `invalid_type`, `invalid_format`, `invalid_value`, `too_small`, `too_big`, `unrecognized_keys`, `invalid`. ## Error codes | Code | Status | What it means | | --- | --- | --- | | `validation_failed` | 400 | A field is missing or not valid. `errors[]` lists each field by its dotted path, such as `email` or `answers.deck`. | | `unauthorized` | 401 | No API key, a malformed `Authorization` header, or a key that is unknown or revoked. | | `insufficient_scope` | 403 | The key works but lacks the scope this endpoint needs. | | `not_found` | 404 | The path does not exist. | | `event_not_found` | 404 | No event with that ID in this organization and mode. A test key never sees live events, and the public API does not serve private events. | | `series_not_found` | 404 | No series with that ID in this organization and mode. | | `rsvp_not_found` | 404 | No RSVP with that ID, or the manage token is not valid. | | `webhook_endpoint_not_found` | 404 | No webhook endpoint with that ID in this mode. | | `delivery_not_found` | 404 | No webhook delivery with that ID in this mode. | | `capacity_reached` | 409 | The event is full and has no waitlist. | | `already_registered` | 409 | This email already has a going or waitlisted RSVP for the event. On the public API the guest is emailed their manage link again. | | `event_not_open` | 409 | The event is not taking RSVPs, for example because it is still a draft. | | `event_cancelled` | 409 | The event was cancelled. | | `event_ended` | 409 | The event has ended. | | `too_many_guests` | 422 | `guests` is higher than the event's `max_guests`. | | `plan_limit` | 403 | Your plan's limit for this resource is reached (API keys, webhook endpoints, custom fields or active series). RSVPs never fail with this code. | | `rate_limited` | 429 | Too many requests. Wait for the number of seconds in `Retry-After`. | | `idempotency_conflict` | 409 | This `Idempotency-Key` was already used with a different request body (for example another guest's email), or the first request is still running. Nothing was created. | | `origin_not_allowed` | 403 | The organization limits which websites may send RSVPs, and this page's origin is not on the list. | | `bot_check_failed` | 403 | The Turnstile token is missing or did not verify. | | `mode_mismatch` | 403 | The request mixes live and test data. | | `sandbox_limit` | 429 | Too many sandboxes from this IP address. Try again later. | | `rsvp_not_going` | 409 | Only an RSVP with status `going` can be checked in. Cancelled, not going and waitlisted RSVPs answer 409. Undoing a check-in works whatever the status. | | `internal_error` | 500 | Something went wrong on our side. Retry with backoff and quote the `request_id`. | ## Handling errors - **4xx** means the request needs to change. Retrying the same request gets the same answer, except `429`. - **429**: wait for the number of seconds in the `Retry-After` header, then retry. - **5xx**: retry with exponential backoff. Send an [`Idempotency-Key`](https://whocoming.com/docs/api/idempotency) on creating requests so a retry cannot create a duplicate. ```ts const res = await fetch(url, init); if (!res.ok) { const problem = await res.json(); switch (problem.code) { case "already_registered": // The guest is already on the list. Show them a friendly message. break; case "capacity_reached": // The event is full and has no waitlist. break; default: throw new Error(`${problem.code}: ${problem.detail} (${problem.request_id})`); } } ``` [`@whocoming/sdk`](https://whocoming.com/docs/sdk#errors) throws a typed `WhoComingError` with `code`, `status` and `requestId`. --- # Webhooks URL: 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. Register a URL and WhoComing sends it a signed `POST` every time something happens. Deliveries are written in the same database transaction as the change itself, so none are lost, and they are retried until your server answers with a `2xx`. ## Register an endpoint ```bash curl -X POST https://api.whocoming.com/v1/webhook-endpoints \ -H "Authorization: Bearer wc_test_..." \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/hooks/whocoming","events":["rsvp.created","rsvp.cancelled"]}' ``` ```json { "id": "whk_...", "mode": "test", "url": "https://example.com/hooks/whocoming", "events": ["rsvp.created", "rsvp.cancelled"], "disabled_at": null, "created_at": "2026-12-01T15:04:05Z", "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" } ``` Store `secret` now: it is shown only in this response. Leave out `events` to receive every type. Endpoints belong to a mode: one registered with a test key receives only test-mode events. The number of endpoints depends on your [plan](https://whocoming.com/docs/concepts/plans-and-limits). ### Which URLs are accepted - `https://` on a public host name, such as `https://example.com/hooks/whocoming`. - Not accepted: plain `http://`, a user name or password in the URL, single-word host names, local names (`.local`, `.internal`, `.lan`, `.localhost`, `.home.arpa`), and private, loopback, link-local or cloud metadata addresses written as an IP (`10.x`, `192.168.x`, `127.0.0.1`, `169.254.169.254`, `[::1]` and the like). The answer is 400 `validation_failed` on `url`. - When a delivery is sent, the host name is looked up again, and an address that turns out to be private is refused for that attempt. So a name that points at your internal network never receives a delivery, even if it was public when you registered it. To receive deliveries on your own computer, use a tunnel (see [Testing locally](#testing-locally)). ## Event types | Type | Sent when | | --- | --- | | `rsvp.created` | A guest RSVPed, from any source: widget, hosted page, API or dashboard. | | `rsvp.updated` | An RSVP changed: name, guests, answers or status. Also sent when a guest re-RSVPs after cancelling. | | `rsvp.cancelled` | An RSVP was cancelled or deleted. A deleted RSVP's `data` has `deleted: true`. | | `rsvp.promoted` | A spot opened and a waitlisted guest moved to going. | | `rsvp.checked_in` | A guest was checked in at the door. | | `event.created` | An event was created, including each occurrence of a series. | | `event.updated` | An event's details changed. | | `event.cancelled` | An event was cancelled. | ## The envelope Every delivery has the same outer shape: ```json { "id": "dlv_7b2d4f6h8j0l2n4p6r8t", "type": "rsvp.created", "created_at": "2026-12-01T15:04:05Z", "mode": "live", "data": { "id": "rsvp_9a2c4e6g8i0k2m4o6q8s", "event_id": "evt_demo0000000000000001", "mode": "live", "status": "going", "name": "Ada Lovelace", "email": "ada@example.com", "guests": 1, "answers": { "deck": "Mono red aggro" }, "source": "embed", "locked": false, "checked_in_at": null, "created_at": "2026-12-01T15:04:05Z", "updated_at": "2026-12-01T15:04:05Z" } } ``` For `rsvp.*` types, `data` is the RSVP as the API returns it. For `event.*` types, `data` is the event, without `counts` and `url`. A [locked RSVP](https://whocoming.com/docs/concepts/locked-rsvps) arrives with `name`, `email` and `answers` set to `null`. When an RSVP is deleted (by the organizer, or by [erasing a guest](https://whocoming.com/docs/data-rights)), `rsvp.cancelled` carries identifiers only, with `"deleted": true`. `source` says where the RSVP came from: `embed` (the widget), `page` (a WhoComing hosted page), `api` (a secret key) or `dashboard` (added by the organizer). The exact schema of every type is in the `webhooks` section of the [OpenAPI document](https://api.whocoming.com/v1/openapi.json), and the [SDK](https://whocoming.com/docs/sdk) has matching types (`RsvpCreatedWebhook` and so on), so a `switch` on `event.type` narrows `event.data`. ## Headers Deliveries follow [Standard Webhooks](https://www.standardwebhooks.com): | Header | Value | | --- | --- | | `webhook-id` | The delivery ID, the same as the envelope's `id`. | | `webhook-timestamp` | Unix time in seconds when it was sent. | | `webhook-signature` | `v1,` followed by a base64 HMAC-SHA256 signature. May hold several, separated by spaces. | The signature is HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed with your secret (the part after `whsec_`, base64-decoded). ## Verify with the SDK Always verify before trusting a delivery. You need the **raw** request body: parsing the JSON and serializing it again changes the bytes and breaks the signature. ```ts title="app/hooks/whocoming/route.ts" import { verifyWebhook, WebhookVerificationError } from "@whocoming/sdk"; export async function POST(request: Request) { const rawBody = await request.text(); let event; try { event = await verifyWebhook(rawBody, request.headers, process.env.WHOCOMING_WEBHOOK_SECRET); } catch (error) { if (error instanceof WebhookVerificationError) return new Response("Bad signature", { status: 400 }); throw error; } if (await alreadyHandled(event.id)) return new Response(null, { status: 204 }); switch (event.type) { case "rsvp.created": await addToGuestList(event.data); break; case "rsvp.cancelled": await removeFromGuestList(event.data.id); break; default: // New types may be added. Ignore the ones you do not use. break; } await markHandled(event.id); return new Response(null, { status: 204 }); } ``` With a client already set up, `await wc.webhooks.verify(rawBody, headers, secret)` does the same. Timestamps more than five minutes from your server's clock are refused, to stop replays. ## Verify by hand The signed content is the delivery ID, the timestamp and the raw body joined with dots. The key is the part of your secret after `whsec_`, base64-decoded. ```ts title="Node.js" import { createHmac, timingSafeEqual } from "node:crypto"; export function isValid(rawBody: string, headers: Headers, secret: string): boolean { const id = headers.get("webhook-id"); const timestamp = headers.get("webhook-timestamp"); const signatures = headers.get("webhook-signature"); if (!id || !timestamp || !signatures) return false; // Refuse anything older or newer than five minutes. if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest(); return signatures.split(" ").some((entry) => { const [version, signature] = entry.split(","); if (version !== "v1" || !signature) return false; const given = Buffer.from(signature, "base64"); return given.length === expected.length && timingSafeEqual(given, expected); }); } ``` ```python title="Python" import base64, hashlib, hmac, time def is_valid(raw_body: bytes, headers, secret: str) -> bool: msg_id = headers["webhook-id"] timestamp = headers["webhook-timestamp"] if abs(time.time() - int(timestamp)) > 300: return False key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + raw_body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() return any( hmac.compare_digest(sig, expected) for version, _, sig in (entry.partition(",") for entry in headers["webhook-signature"].split(" ")) if version == "v1" ) ``` Any [Standard Webhooks library](https://github.com/standard-webhooks/standard-webhooks) works too. ## Delivery and retries - **At least once.** A delivery counts as done when your endpoint answers with any `2xx`. Anything else (or no answer within 10 seconds) is retried. - **Retry schedule.** The first retry comes 30 seconds after a failure, and each wait doubles (1 minute, 2, 4, 8 and so on) up to two hours, with a little random spread so endpoints that failed together do not retry together. That is about eight tries in the first two hours, then one every two hours. Retries stop 24 hours after the delivery was created: it is then marked `failed` and the organization's owners are emailed. - **Ten failures in a row disable the endpoint.** `disabled_at` is set and nothing more is sent. Fix your handler, then turn it back on with `PATCH /v1/webhook-endpoints/{id}` and `{ "disabled": false }`, which also resets the count. A single success resets it too. - **Answer fast.** Return `2xx` as soon as you have stored the delivery, and do slow work afterwards. ## Treat `id` as an idempotency key Because delivery is at least once, the same delivery can arrive twice (for example when your server handled it but the answer was lost). Every attempt of one delivery carries the same `id` and `webhook-id`. Store the IDs you have handled and skip repeats, as in the example above. Deliveries are not guaranteed to arrive in order. Use `data.updated_at` to tell which version of an RSVP is newest. ## The delivery log ```bash curl "https://api.whocoming.com/v1/webhook-deliveries?status=failed" \ -H "Authorization: Bearer wc_test_..." ``` Each delivery shows its `status` (`pending` while retries remain, `delivered`, `failed`, or `skipped` when WhoComing decided not to send it), `attempts`, `next_attempt_at`, the last HTTP status and error, and the exact `payload` sent. Filter by `endpoint_id` or `status`. The log is for looking into recent deliveries, not an archive: - **After 30 days**, the guest's `name`, `email` and `answers` are removed from finished deliveries. The rest of the delivery stays. - **After 90 days**, finished deliveries (`delivered`, `skipped` and `failed`) are deleted. Deliveries still being retried are never deleted. - [Erasing a guest](https://whocoming.com/docs/data-rights) removes their details from stored deliveries at once. Keep your own copy of anything you need for longer. To send one again with the same `webhook-id`, for example after fixing a bug: ```bash curl -X POST https://api.whocoming.com/v1/webhook-deliveries/dlv_7b2d4f6h8j0l2n4p6r8t/retry \ -H "Authorization: Bearer wc_test_..." ``` The same log, with a redeliver button, is in the dashboard. ## Testing locally Your laptop is not reachable from the internet, so expose your local server through a tunnel: ```bash # Cloudflare (free, no account needed for a quick tunnel) cloudflared tunnel --url http://localhost:3000 # or ngrok ngrok http 3000 ``` 1. Copy the public `https://` URL the tunnel prints. 2. Register it with a **test** key: `https:///hooks/whocoming`. 3. Put the `secret` from the response in your local environment. 4. Create a test RSVP (the [quickstart](https://whocoming.com/docs/quickstart) cURL works) and watch it arrive. 5. Changed your handler? Redeliver the same delivery from the log instead of creating new data. Test-mode deliveries are signed and retried exactly like live ones. --- # SDK URL: https://whocoming.com/docs/sdk @whocoming/sdk, a small typed client for the API, and @whocoming/react, the widget as a React component. ## `@whocoming/sdk` ```bash npm install @whocoming/sdk ``` A thin TypeScript client for the REST API. No runtime dependencies, built on `fetch`, so it runs on Node 20 and later, Bun, Deno and edge runtimes. Fields are camelCase in your code and snake_case on the wire; the SDK converts both ways. ```ts import { WhoComing } from "@whocoming/sdk"; const wc = new WhoComing(process.env.WHOCOMING_API_KEY); const event = await wc.events.create({ title: "Friday Night Magic", startsAt: "2027-01-08T18:30:00", timezone: "America/Detroit", capacity: 32, }); const rsvp = await wc.rsvps.create( event.id, { name: "Ada Lovelace", email: "ada@example.com", guests: 1 }, { idempotencyKey: crypto.randomUUID() }, ); console.log(rsvp.status); // "going", or "waitlisted" when full ``` With no argument, `new WhoComing()` reads `WHOCOMING_API_KEY` from the environment. The client refuses to start in a browser, because a secret key must stay on your server. ### Resources | Property | Methods | | --- | --- | | `wc.events` | `list`, `create`, `get`, `update`, `delete` | | `wc.series` | `list`, `create`, `get`, `update`, `end` | | `wc.rsvps` | `list(eventId)`, `create(eventId, ...)`, `get`, `update`, `delete`, `checkIn` | | `wc.webhookEndpoints` | `list`, `create`, `get`, `update`, `delete` | | `wc.webhookDeliveries` | `list`, `retry` | | `wc.guests` | `erase`, `export` | | `wc.usage` | `get` | | `wc.webhooks` | `verify` | | `wc.public` | The [no-key client](#without-a-key), sharing this client's options | Each maps to one endpoint in the [API reference](https://whocoming.com/docs/reference/events/list-events). A few names differ from the HTTP verb: `series.end(id)` is `DELETE /v1/series/{id}` (no more dates are made, future dates with no RSVPs are removed, and dates with RSVPs stay), and `webhookEndpoints.get(id)` never returns the signing secret, which `create` shows once. ### Lists Every `list` method can be awaited for one page, or iterated for every item across pages: ```ts const { data, nextCursor } = await wc.events.list({ limit: 20 }); for await (const r of wc.rsvps.list("evt_demo0000000000000001", { status: "going" })) { console.log(r.name, r.guests); } const everyone = await wc.rsvps.list("evt_demo0000000000000001").toArray(); ``` Awaiting gives `{ data, nextCursor }`; pass `nextCursor` back as `cursor` for the next page, or let `for await` follow the cursors for you. `.pages()` iterates page by page. Nothing is requested until you await or iterate. ### Retries and idempotency The client retries `429`, `5xx` and network errors with backoff, twice by default, and honors `Retry-After`. Creating calls are only retried with an [idempotency key](https://whocoming.com/docs/api/idempotency); when you do not pass `idempotencyKey`, the SDK makes one per call so its own retries can never create a duplicate. Pass your own when you retry across process restarts. ```ts const wc = new WhoComing(process.env.WHOCOMING_API_KEY, { maxRetries: 3, timeoutMs: 10_000, }); ``` ### Errors Failures throw `WhoComingError`, with the API's stable [`code`](https://whocoming.com/docs/errors), the HTTP `status`, the `requestId` and any field `errors`: ```ts import { WhoComingError } from "@whocoming/sdk"; try { await wc.rsvps.create(eventId, { name: "Ada Lovelace", email: "ada@example.com" }); } catch (error) { if (error instanceof WhoComingError && error.code === "already_registered") { // Already on the list. } else { throw error; } } ``` The error classes, all exported from the package: | Class | When | `code` | | --- | --- | --- | | `WhoComingError` | The API answered with an error | The API's code, such as `capacity_reached` | | `WhoComingConnectionError` | The request never got an answer | `connection_error` | | `WhoComingTimeoutError` | No answer within `timeoutMs` | `timeout` | | `WebhookVerificationError` | `webhooks.verify` cannot trust a request | none; see `reason` | The first three are all `WhoComingError`s, so one `instanceof` check catches them. `code` is typed as the known codes plus `string`, because the API may add codes: keep a default branch. ### Verifying webhooks ```ts const payload = await wc.webhooks.verify(rawBody, request.headers, process.env.WHOCOMING_WEBHOOK_SECRET); ``` `verify` is async (it uses Web Crypto), so remember the `await`. It checks the signature and the timestamp (5 minutes either way by default; set `toleranceSeconds`), then returns the parsed, typed event. When the request cannot be trusted it rejects with `WebhookVerificationError`, whose `reason` says why; answer such a request with 400. Pass the raw body, not parsed JSON. The same check is exported as `verifyWebhook(rawBody, headers, secret)` for code that has no client. See [webhooks](https://whocoming.com/docs/webhooks#verify-with-the-sdk). ### Without a key `WhoComingPublic` calls the [public surface](https://whocoming.com/docs/api/authentication#the-public-surface) and is safe in the browser: ```ts import { WhoComingPublic } from "@whocoming/sdk"; const pub = new WhoComingPublic(); const event = await pub.events.get("evt_demo0000000000000001"); console.log(event.counts.spotsLeft); const sandbox = await pub.sandbox.create(); // a 24-hour test org, key and event ``` | Property | Methods | | --- | --- | | `pub.events` | `get(id)`, `calendar(id)` (the `.ics` file as text) | | `pub.rsvps` | `create(eventId, ...)` (needs a Turnstile token when the event has one), `get(manageToken)`, `update(manageToken, ...)` | | `pub.orgs` | `listEvents(slug)`, paginated like the lists above | | `pub.sandbox` | `create()` | `pub.rsvps.create` accepts `idempotencyKey` and is only retried when you pass one. ## `@whocoming/react` ```bash npm install @whocoming/react ``` The widget as a React component, with typed props and callbacks: ```tsx "use client"; import { WhoComingRsvp } from "@whocoming/react"; export function Rsvp() { return ( console.log("ready", detail.state)} onRsvp={(detail) => console.log("RSVP", detail.rsvpId, detail.status)} onError={(detail) => console.log("error", detail.code)} /> ); } ``` Props mirror the element's [attributes](https://whocoming.com/docs/embed) in camelCase (`hideCount`, `apiBase`, `source`, `noJsonld`), and the callbacks receive the `detail` of its [DOM events](https://whocoming.com/docs/embed/events), also in camelCase (`rsvpId`, `eventId`). Style it with the same [CSS variables and parts](https://whocoming.com/docs/embed/theming). Two props are for special cases: - `source`: where the RSVP is recorded as coming from, shown as the RSVP's `source`. Leave it out on your own site (`embed`); WhoComing's hosted pages set `"page"`. - `noJsonld`: the page already has Event structured data for this event, so the widget should not add its own. Search engines then see one Event, not two. ```tsx ``` We do not ship SDKs per framework. Vue, Svelte, Angular and the rest use the element directly; see [other frameworks](https://whocoming.com/docs/guides/other-frameworks). --- # Data rights URL: 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. When a guest asks what you hold about them, or asks you to delete it, you can answer with one call. Both calls work on the mode of the key you use, so use a live key for real guests. ## Export a guest's data ```bash curl "https://api.whocoming.com/v1/guests/export?email=ada@example.com" \ -H "Authorization: Bearer wc_live_..." ``` ```json { "email": "ada@example.com", "mode": "live", "exported_at": "2026-12-01T15:04:05Z", "rsvps": [ { "id": "rsvp_9a2c4e6g8i0k2m4o6q8s", "event_id": "evt_demo0000000000000001", "name": "Ada Lovelace", "email": "ada@example.com", "status": "going", "guests": 1, "answers": { "deck": "Mono red aggro" }, "...": "...", "event": { "id": "evt_demo0000000000000001", "title": "Friday Night Magic", "starts_at": "2027-01-08T18:30:00-05:00", "timezone": "America/Detroit" } } ] } ``` Every RSVP for that email in your organization, each with its event. Needs the `rsvps:read` scope. ## Erase a guest ```bash curl -X POST https://api.whocoming.com/v1/guests/erase \ -H "Authorization: Bearer wc_live_..." \ -H "Content-Type: application/json" \ -d '{"email":"ada@example.com"}' ``` ```json { "email": "ada@example.com", "mode": "live", "rsvps_erased": 3 } ``` Deletes every RSVP with that address across your organization, in the key's mode: a live key erases live RSVPs, a test key test ones. (In the dashboard, erasing covers both modes.) This cannot be undone. `rsvps_erased` is how many RSVPs were deleted. Needs the `rsvps:write` scope. What else happens: - **Counts go down.** The deleted RSVPs no longer hold seats, so the event's `going` and `spots_left` change. - **The waitlist can move up.** If the guest was going to a full event, the next person on the waitlist who fits is promoted and emailed, exactly as when someone cancels. - **Webhooks.** Each deleted RSVP that was not already cancelled sends `rsvp.cancelled` with identifiers only and `"deleted": true`, never the erased details. The guest's name, email and answers are also removed from deliveries already stored in the [delivery log](https://whocoming.com/docs/webhooks#the-delivery-log). - **Usage is not refunded.** RSVPs already counted this month stay counted. To remove one RSVP rather than a person, use `DELETE /v1/rsvps/{id}`. ## Retention Guest details do not stay forever. By default, 365 days after an event ends, the name, email and answers on its RSVPs are replaced with `null`. The RSVP itself (status, plus-ones, check-in time) stays, so your attendance numbers stay right. Your code should therefore treat `name`, `email` and `answers` as nullable on any RSVP. ## What we keep about visitors - IP addresses are never stored as is. They are hashed to apply rate limits, and the hashes are kept for at most 30 days. - The widget sets no cookies and stores nothing on the guest's device unless they ask to be remembered. See [embed privacy](https://whocoming.com/docs/embed/privacy). --- # API reference Base URL https://api.whocoming.com. Generated from the OpenAPI document. Errors are application/problem+json with a stable `code`; see https://whocoming.com/docs/errors. ## GET /v1/events **List events** Events in the key's mode, soonest first. Requires the `events:read` scope. Auth: secret key (Bearer). Parameters: - `limit` (query, integer): Page size, 1 to 100. Defaults to 50. - `cursor` (query, string): The `next_cursor` from the previous page. - `status` (query, "draft" | "published" | "cancelled") - `series_id` (query, string) - `starts_after` (query, string): Only events starting at or after this time. Success: 200, EventList. ## POST /v1/events **Create an event** Create a one-off event. Accepts `Idempotency-Key`. Requires the `events:write` scope. Auth: secret key (Bearer). Parameters: - `idempotency-key` (header, string): Send a unique value (a UUID works) to make retries safe. A replay within 24 hours returns the first response; the same key with a different body is a 409 `idempotency_conflict`. Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `title` | string | yes | | | `starts_at` | string | yes | ISO 8601. The offset is optional: without one, the time is read in the event's timezone. | | `ends_at` | string \| null | no | ISO 8601. The offset is optional: without one, the time is read in the event's timezone. | | `timezone` | string | yes | IANA timezone name. | | `slug` | string | no | Generated from the title when omitted. | | `status` | "draft" \| "published" | no | Defaults to `published`, so the event can take RSVPs right away. | | `description` | string \| null | no | | | `location_name` | string \| null | no | | | `location_address` | string \| null | no | | | `online_url` | string \| null | no | Link for an online event. `https://` only. | | `capacity` | integer \| null | no | Seats. `null` means no limit. | | `max_guests` | integer | no | Extra guests (plus-ones) each RSVP may bring. | | `waitlist_enabled` | boolean | no | | | `visibility` | "public" \| "unlisted" \| "private" | no | `public` events are listed and indexed. `unlisted` events work by link and embed but are not listed. `private` events are only visible through this API and the dashboard. | | `price_note` | string \| null | no | | | `cover_image_url` | string \| null | no | Image shown on the hosted page and in search results. `https://` only. | | `fields` | EventFieldInput[] | no | Custom questions, in display order. At most 100, or fewer on your plan. Each `key` must be unique. | Success: 201, Event. ## GET /v1/events/{id} **Get an event** Read one event, including private ones. Requires the `events:read` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Success: 200, Event. ## PATCH /v1/events/{id} **Update an event** Change the fields you send. Set `status` to `cancelled` to cancel the event and notify guests. Requires the `events:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `title` | string | no | | | `starts_at` | string | no | ISO 8601. The offset is optional: without one, the time is read in the event's timezone. | | `ends_at` | string \| null | no | ISO 8601. The offset is optional: without one, the time is read in the event's timezone. | | `timezone` | string | no | IANA timezone name. | | `slug` | string | no | | | `status` | "draft" \| "published" \| "cancelled" | no | Set `cancelled` to cancel the event and notify its guests. | | `description` | string \| null | no | | | `location_name` | string \| null | no | | | `location_address` | string \| null | no | | | `online_url` | string \| null | no | Link for an online event. `https://` only. | | `capacity` | integer \| null | no | Seats. `null` means no limit. | | `max_guests` | integer | no | Extra guests (plus-ones) each RSVP may bring. | | `waitlist_enabled` | boolean | no | | | `visibility` | "public" \| "unlisted" \| "private" | no | `public` events are listed and indexed. `unlisted` events work by link and embed but are not listed. `private` events are only visible through this API and the dashboard. | | `price_note` | string \| null | no | | | `cover_image_url` | string \| null | no | Image shown on the hosted page and in search results. `https://` only. | | `fields` | EventFieldInput[] | no | Custom questions, in display order. At most 100, or fewer on your plan. Each `key` must be unique. | Success: 200, Event. ## DELETE /v1/events/{id} **Delete an event** Delete an event and its RSVPs. To keep the guest list and tell guests, cancel it with PATCH instead. Requires the `events:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Success: 200, Deleted. ## GET /v1/events/{id}/rsvps **List an event's RSVPs** The guest list, oldest first. Filter with `status`. Requires the `rsvps:read` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) - `limit` (query, integer): Page size, 1 to 100. Defaults to 50. - `cursor` (query, string): The `next_cursor` from the previous page. - `status` (query, "going" | "not_going" | "waitlisted" | "cancelled"): Only RSVPs with this status. Success: 200, RsvpList. ## POST /v1/events/{id}/rsvps **Create an RSVP** Add a guest. Capacity and the waitlist apply. One RSVP per email per event (409 `already_registered`). Accepts `Idempotency-Key`. Requires the `rsvps:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) - `idempotency-key` (header, string): Send a unique value (a UUID works) to make retries safe. A replay within 24 hours returns the first response; the same key with a different body is a 409 `idempotency_conflict`. Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `name` | string | yes | | | `email` | string | yes | At most 320 characters. Spaces around it are removed. | | `guests` | integer | no | Extra guests, up to the event's `max_guests`. Defaults to 0. | | `answers` | AnswersInput | no | | | `status` | "going" \| "not_going" | no | Defaults to `going`. A full event with a waitlist answers `waitlisted`; without one, 409 `capacity_reached`. | Success: 201, Rsvp. ## POST /v1/guests/erase **Erase a 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. Requires the `rsvps:write` scope. Auth: secret key (Bearer). Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `email` | string | yes | At most 320 characters. Spaces around it are removed. | Success: 200, GuestErasure. ## GET /v1/guests/export **Export a guest's data** Everything held about one email address, for a data access request. Requires the `rsvps:read` scope. Auth: secret key (Bearer). Parameters: - `email` (query, required, string): The guest's email address. Success: 200, GuestExport. ## GET /v1/public/events/{id} **Get a 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`). Auth: none. Parameters: - `id` (path, required, string) Success: 200, PublicEvent. ## GET /v1/public/events/{id}/calendar.ics **Download the event as a calendar file** 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`). Auth: none. Parameters: - `id` (path, required, string) Success: 200. ## POST /v1/public/events/{id}/rsvps **RSVP as a guest** 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. Auth: none. Parameters: - `id` (path, required, string) - `idempotency-key` (header, string): Send a unique value (a UUID works) to make retries safe. A replay within 24 hours returns the first response; the same key with a different body is a 409 `idempotency_conflict`. Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `name` | string | yes | | | `email` | string | yes | At most 320 characters. Spaces around it are removed. | | `guests` | integer | no | | | `answers` | AnswersInput | no | | | `status` | "going" \| "not_going" | no | Defaults to `going`. | | `turnstile_token` | string | no | Token from Cloudflare Turnstile, using the event's `turnstile_site_key`. Required whenever that key is not null. | | `website` | string | no | Honeypot. Leave it out or empty; a value marks the request as a bot. | | `source` | "embed" \| "page" | no | Where the guest RSVPed: `embed` (the widget, the default) or `page` (a WhoComing hosted page). Shown to the organizer as the RSVP's `source`. | Success: 201, PublicRsvpCreated. ## GET /v1/public/orgs/{slug}/events **List an organization's upcoming 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`). Auth: none. Parameters: - `slug` (path, required, string) - `limit` (query, integer): Page size, 1 to 100. Defaults to 50. - `cursor` (query, string): The `next_cursor` from the previous page. Success: 200, PublicEventList. ## GET /v1/public/rsvps/{manage_token} **View your 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. Auth: none. Parameters: - `manage_token` (path, required, string): The token from the confirmation email or the create response. Success: 200, PublicRsvp. ## PATCH /v1/public/rsvps/{manage_token} **Change or cancel your 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. Auth: none. Parameters: - `manage_token` (path, required, string): The token from the confirmation email or the create response. Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `status` | "going" \| "not_going" \| "cancelled" | no | `cancelled` gives the seat back; the waitlist moves up. | | `guests` | integer | no | | | `answers` | AnswersInput | no | | | `name` | string | no | | Success: 200, PublicRsvp. ## GET /v1/rsvps/{id} **Get an RSVP** Read one RSVP. Requires the `rsvps:read` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Success: 200, Rsvp. ## PATCH /v1/rsvps/{id} **Update an RSVP** Change the fields you send. Requires the `rsvps:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `name` | string | no | | | `email` | string | no | At most 320 characters. Spaces around it are removed. | | `guests` | integer | no | | | `answers` | AnswersInput | no | | | `status` | "going" \| "not_going" \| "cancelled" | no | Set `cancelled` to cancel; a freed seat promotes the waitlist. | Success: 200, Rsvp. ## DELETE /v1/rsvps/{id} **Delete an RSVP** Remove the RSVP and its guest data for good. To keep a record, set `status` to `cancelled` instead. Requires the `rsvps:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Success: 200, Deleted. ## POST /v1/rsvps/{id}/check-in **Check in a guest** 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`. Requires the `rsvps:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Success: 200, Rsvp. ## POST /v1/sandbox **Create a 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`). Auth: none. Success: 201, Sandbox. ## GET /v1/series **List series** Recurring series in the key's mode, oldest first. List an occurrence's events with `GET /v1/events?series_id=`. Requires the `events:read` scope. Auth: secret key (Bearer). Parameters: - `limit` (query, integer): Page size, 1 to 100. Defaults to 50. - `cursor` (query, string): The `next_cursor` from the previous page. - `status` (query, "active" | "ended") Success: 200, SeriesList. ## POST /v1/series **Create a recurring 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`. Requires the `events:write` scope. Auth: secret key (Bearer). Parameters: - `idempotency-key` (header, string): Send a unique value (a UUID works) to make retries safe. A replay within 24 hours returns the first response; the same key with a different body is a 409 `idempotency_conflict`. Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `title` | string | yes | | | `recurrence` | Recurrence | yes | | | `timezone` | string | yes | IANA timezone name. | | `starts_on` | string | yes | First possible date. Occurrences start on or after it. | | `start_time` | string | yes | Wall-clock start time in the series timezone, 24-hour HH:MM. | | `duration_minutes` | integer | yes | | | `ends_on` | string \| null | no | Last possible date. Omit for no end. | | `template` | EventTemplateInput | no | | Success: 201, Series. ## GET /v1/series/{id} **Get a series** Read one series. Requires the `events:read` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Success: 200, Series. ## PATCH /v1/series/{id} **Update a 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. Requires the `events:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `title` | string | no | | | `recurrence` | Recurrence | no | | | `start_time` | string | no | Wall-clock start time in the series timezone, 24-hour HH:MM. | | `duration_minutes` | integer | no | | | `ends_on` | string \| null | no | | | `template` | EventTemplateInput | no | | Success: 200, Series. ## DELETE /v1/series/{id} **End a 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. Requires the `events:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Success: 200, Series. ## GET /v1/usage **Get usage** RSVPs counted this month and the plan's limits. Any valid key may call this. Auth: secret key (Bearer). Success: 200, Usage. ## GET /v1/webhook-deliveries **List webhook deliveries** The delivery log, newest first. Requires the `webhooks:write` scope. Auth: secret key (Bearer). Parameters: - `limit` (query, integer): Page size, 1 to 100. Defaults to 50. - `cursor` (query, string): The `next_cursor` from the previous page. - `endpoint_id` (query, string) - `status` (query, "pending" | "delivered" | "failed") Success: 200, WebhookDeliveryList. ## POST /v1/webhook-deliveries/{id}/retry **Redeliver a webhook** Queue the delivery to be sent again within a minute, with the same `webhook-id`. Requires the `webhooks:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Success: 202, WebhookDelivery. ## GET /v1/webhook-endpoints **List webhook endpoints** Endpoints in the key's mode. Secrets are never listed. Requires the `webhooks:write` scope. Auth: secret key (Bearer). Parameters: - `limit` (query, integer): Page size, 1 to 100. Defaults to 50. - `cursor` (query, string): The `next_cursor` from the previous page. Success: 200, WebhookEndpointList. ## POST /v1/webhook-endpoints **Create a 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`. Requires the `webhooks:write` scope. Auth: secret key (Bearer). Parameters: - `idempotency-key` (header, string): Send a unique value (a UUID works) to make retries safe. A replay within 24 hours returns the first response; the same key with a different body is a 409 `idempotency_conflict`. Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `url` | string | yes | | | `events` | "rsvp.created" \| "rsvp.updated" \| "rsvp.cancelled" \| "rsvp.promoted" \| "rsvp.checked_in" \| "event.created" \| "event.updated" \| "event.cancelled"[] | no | Defaults to every event type. | Success: 201, WebhookEndpointWithSecret. ## GET /v1/webhook-endpoints/{id} **Get a webhook endpoint** Read one endpoint. The secret is never shown again. Requires the `webhooks:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Success: 200, WebhookEndpoint. ## PATCH /v1/webhook-endpoints/{id} **Update a webhook endpoint** Change the URL or event types, or pause and resume. Requires the `webhooks:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Request body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `url` | string | no | | | `events` | "rsvp.created" \| "rsvp.updated" \| "rsvp.cancelled" \| "rsvp.promoted" \| "rsvp.checked_in" \| "event.created" \| "event.updated" \| "event.cancelled"[] | no | | | `disabled` | boolean | no | `true` to pause deliveries, `false` to resume (also resets the failure count). | Success: 200, WebhookEndpoint. ## DELETE /v1/webhook-endpoints/{id} **Delete a webhook endpoint** Stop deliveries and remove the endpoint. Requires the `webhooks:write` scope. Auth: secret key (Bearer). Parameters: - `id` (path, required, string) Success: 200, Deleted. ## Schemas ### CalendarLinks | Field | Type | Required | Notes | | --- | --- | --- | --- | | `ics_url` | string | yes | | | `google_url` | string | yes | | ### Counts | Field | Type | Required | Notes | | --- | --- | --- | --- | | `going` | integer | yes | Seats used: each going RSVP counts 1 plus its extra guests. | | `waitlisted` | integer | yes | | | `spots_left` | integer \| null | yes | `null` when the event has no capacity limit. | ### CreateEventRequest | Field | Type | Required | Notes | | --- | --- | --- | --- | | `title` | string | yes | | | `starts_at` | string | yes | ISO 8601. The offset is optional: without one, the time is read in the event's timezone. | | `ends_at` | string \| null | no | ISO 8601. The offset is optional: without one, the time is read in the event's timezone. | | `timezone` | string | yes | IANA timezone name. | | `slug` | string | no | Generated from the title when omitted. | | `status` | "draft" \| "published" | no | Defaults to `published`, so the event can take RSVPs right away. | | `description` | string \| null | no | | | `location_name` | string \| null | no | | | `location_address` | string \| null | no | | | `online_url` | string \| null | no | Link for an online event. `https://` only. | | `capacity` | integer \| null | no | Seats. `null` means no limit. | | `max_guests` | integer | no | Extra guests (plus-ones) each RSVP may bring. | | `waitlist_enabled` | boolean | no | | | `visibility` | "public" \| "unlisted" \| "private" | no | `public` events are listed and indexed. `unlisted` events work by link and embed but are not listed. `private` events are only visible through this API and the dashboard. | | `price_note` | string \| null | no | | | `cover_image_url` | string \| null | no | Image shown on the hosted page and in search results. `https://` only. | | `fields` | EventFieldInput[] | no | Custom questions, in display order. At most 100, or fewer on your plan. Each `key` must be unique. | ### CreatePublicRsvpRequest | Field | Type | Required | Notes | | --- | --- | --- | --- | | `name` | string | yes | | | `email` | string | yes | At most 320 characters. Spaces around it are removed. | | `guests` | integer | no | | | `answers` | AnswersInput | no | | | `status` | "going" \| "not_going" | no | Defaults to `going`. | | `turnstile_token` | string | no | Token from Cloudflare Turnstile, using the event's `turnstile_site_key`. Required whenever that key is not null. | | `website` | string | no | Honeypot. Leave it out or empty; a value marks the request as a bot. | | `source` | "embed" \| "page" | no | Where the guest RSVPed: `embed` (the widget, the default) or `page` (a WhoComing hosted page). Shown to the organizer as the RSVP's `source`. | ### CreateRsvpRequest `answers` are checked against the event's `fields`: each value must match its question's type (text, one of the options, a number, true or false), and a key the event has no question for is refused. Unlike the public RSVP form, a required question may be left out, so you can import guests who never saw the form. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `name` | string | yes | | | `email` | string | yes | At most 320 characters. Spaces around it are removed. | | `guests` | integer | no | Extra guests, up to the event's `max_guests`. Defaults to 0. | | `answers` | AnswersInput | no | | | `status` | "going" \| "not_going" | no | Defaults to `going`. A full event with a waitlist answers `waitlisted`; without one, 409 `capacity_reached`. | ### CreateSeriesRequest | Field | Type | Required | Notes | | --- | --- | --- | --- | | `title` | string | yes | | | `recurrence` | Recurrence | yes | | | `timezone` | string | yes | IANA timezone name. | | `starts_on` | string | yes | First possible date. Occurrences start on or after it. | | `start_time` | string | yes | Wall-clock start time in the series timezone, 24-hour HH:MM. | | `duration_minutes` | integer | yes | | | `ends_on` | string \| null | no | Last possible date. Omit for no end. | | `template` | EventTemplateInput | no | | ### CreateWebhookEndpointRequest | Field | Type | Required | Notes | | --- | --- | --- | --- | | `url` | string | yes | | | `events` | "rsvp.created" \| "rsvp.updated" \| "rsvp.cancelled" \| "rsvp.promoted" \| "rsvp.checked_in" \| "event.created" \| "event.updated" \| "event.cancelled"[] | no | Defaults to every event type. | ### Deleted Returned by DELETE requests. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `deleted` | true | yes | | ### EraseGuestRequest | Field | Type | Required | Notes | | --- | --- | --- | --- | | `email` | string | yes | At most 320 characters. Spaces around it are removed. | ### Event | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `series_id` | string \| null | yes | Set when the event is an occurrence of a series. | | `slug` | string | yes | | | `title` | string | yes | | | `description` | string \| null | yes | | | `starts_at` | string | yes | ISO 8601 with a UTC offset. | | `ends_at` | string \| null | yes | ISO 8601 with a UTC offset. | | `timezone` | string | yes | | | `location_name` | string \| null | yes | | | `location_address` | string \| null | yes | | | `online_url` | string \| null | yes | | | `capacity` | integer \| null | yes | | | `max_guests` | integer | yes | | | `waitlist_enabled` | boolean | yes | | | `visibility` | "public" \| "unlisted" \| "private" | yes | `public` events are listed and indexed. `unlisted` events work by link and embed but are not listed. `private` events are only visible through this API and the dashboard. | | `status` | "draft" \| "published" \| "cancelled" | yes | | | `price_note` | string \| null | yes | | | `cover_image_url` | string \| null | yes | | | `fields` | EventField[] | yes | | | `counts` | Counts | yes | | | `url` | string | yes | Hosted event page. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `updated_at` | string | yes | ISO 8601 with a UTC offset. | ### EventCancelledWebhook The `event.cancelled` webhook body. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | Unique per delivery and the same on every retry. Also the `webhook-id` header. Use it to ignore duplicates. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `type` | "event.cancelled" | yes | | | `data` | EventWebhookData | yes | | ### EventCreatedWebhook The `event.created` webhook body. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | Unique per delivery and the same on every retry. Also the `webhook-id` header. Use it to ignore duplicates. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `type` | "event.created" | yes | | | `data` | EventWebhookData | yes | | ### EventField One custom question on the RSVP form. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `key` | string | yes | | | `label` | string | yes | | | `type` | "text" \| "textarea" \| "select" \| "checkbox" \| "number" | yes | | | `required` | boolean | yes | | | `options` | string[] | no | Choices for `select` fields. | ### EventFieldInput One custom question on the RSVP form. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `key` | string | yes | What the answer is stored under. Lowercase letters, digits and underscores, 1 to 64 characters, unique within the event. | | `label` | string | yes | | | `type` | "text" \| "textarea" \| "select" \| "checkbox" \| "number" | yes | | | `required` | boolean | no | | | `options` | string[] | no | Choices for `select` fields: 1 to 100, no repeats. | ### EventList | Field | Type | Required | Notes | | --- | --- | --- | --- | | `data` | Event[] | yes | | | `next_cursor` | string \| null | yes | Pass as `cursor` to get the next page. `null` on the last page. | ### EventTemplate Event settings copied onto every occurrence. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `description` | string \| null | no | | | `location_name` | string \| null | no | | | `location_address` | string \| null | no | | | `online_url` | string \| null | no | | | `capacity` | integer \| null | no | | | `max_guests` | integer | no | | | `waitlist_enabled` | boolean | no | | | `visibility` | "public" \| "unlisted" \| "private" | no | `public` events are listed and indexed. `unlisted` events work by link and embed but are not listed. `private` events are only visible through this API and the dashboard. | | `price_note` | string \| null | no | | | `cover_image_url` | string \| null | no | | | `fields` | EventField[] | no | | ### EventTemplateInput Event settings copied onto every occurrence. Same rules as on events. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `description` | string \| null | no | | | `location_name` | string \| null | no | | | `location_address` | string \| null | no | | | `online_url` | string \| null | no | Link for an online event. `https://` only. | | `capacity` | integer \| null | no | Seats. `null` means no limit. | | `max_guests` | integer | no | Extra guests (plus-ones) each RSVP may bring. | | `waitlist_enabled` | boolean | no | | | `visibility` | "public" \| "unlisted" \| "private" | no | `public` events are listed and indexed. `unlisted` events work by link and embed but are not listed. `private` events are only visible through this API and the dashboard. | | `price_note` | string \| null | no | | | `cover_image_url` | string \| null | no | Image shown on the hosted page and in search results. `https://` only. | | `fields` | EventFieldInput[] | no | Custom questions, in display order. At most 100, or fewer on your plan. Each `key` must be unique. | ### EventUpdatedWebhook The `event.updated` webhook body. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | Unique per delivery and the same on every retry. Also the `webhook-id` header. Use it to ignore duplicates. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `type` | "event.updated" | yes | | | `data` | EventWebhookData | yes | | ### EventWebhookData The event after the change. Sent with every `event.*` event type. Counts and the page URL are not included; read the event for them. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `series_id` | string \| null | yes | | | `slug` | string | yes | | | `title` | string | yes | | | `description` | string \| null | yes | | | `starts_at` | string | yes | ISO 8601 date and time with an offset. | | `ends_at` | string \| null | yes | ISO 8601 date and time with an offset. | | `timezone` | string | yes | | | `location_name` | string \| null | yes | | | `location_address` | string \| null | yes | | | `online_url` | string \| null | yes | | | `capacity` | integer \| null | yes | | | `max_guests` | integer | yes | | | `waitlist_enabled` | boolean | yes | | | `visibility` | "public" \| "unlisted" \| "private" | yes | `public` events are listed and indexed. `unlisted` events work by link and embed but are not listed. `private` events are only visible through this API and the dashboard. | | `status` | "draft" \| "published" \| "cancelled" | yes | | | `price_note` | string \| null | yes | | | `cover_image_url` | string \| null | yes | | | `fields` | EventField[] | yes | | | `created_at` | string | yes | ISO 8601 date and time with an offset. | | `updated_at` | string | yes | ISO 8601 date and time with an offset. | ### EveryTwoWeeksRecurrence Every other week on one weekday, counted from `starts_on`. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `frequency` | "every_two_weeks" | yes | | | `weekday` | Weekday | yes | | ### FieldError | Field | Type | Required | Notes | | --- | --- | --- | --- | | `field` | string | yes | Dotted path to the field. | | `message` | string | yes | | | `code` | string | yes | Stable reason to branch on, such as `required`, `invalid_type`, `invalid_format`, `invalid_value`, `too_small`, `too_big`, `unrecognized_keys`, `invalid`. New codes may be added. | ### GuestErasure Result of erasing a guest across the organization. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `email` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `rsvps_erased` | integer | yes | RSVPs deleted for this email address. | ### GuestExport Everything the organization holds about one guest. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `email` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `exported_at` | string | yes | ISO 8601 with a UTC offset. | | `rsvps` | Rsvp \| object[] | yes | Every RSVP for this email in the organization, with its event. | ### GuestExportEvent | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `title` | string | yes | | | `starts_at` | string | yes | ISO 8601 with a UTC offset. | | `timezone` | string | yes | | ### MonthlyRecurrence One weekday a month, such as the second Friday or the last Sunday. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `frequency` | "monthly" | yes | | | `weekday` | Weekday | yes | | | `week_of_month` | 1 \| 2 \| 3 \| 4 \| -1 | yes | Which one in the month: 1 to 4, or -1 for the last. | ### Problem RFC 9457 problem details, sent as application/problem+json. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `type` | string | yes | | | `title` | string | yes | | | `status` | integer | yes | | | `code` | string | yes | Stable error code to branch on, such as `event_not_found`, `capacity_reached`, `rate_limited` or `plan_limit`. New codes may be added. | | `detail` | string | yes | | | `request_id` | string | yes | Quote this when contacting support. Also sent as the X-Request-Id header. | | `errors` | FieldError[] | no | Present for field problems. | ### PublicBranding | Field | Type | Required | Notes | | --- | --- | --- | --- | | `show_badge` | boolean | yes | Show the "RSVP by WhoComing" link (Free and Starter). | ### PublicEvent What a guest may see about an event. Counts only, never guest names. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `title` | string | yes | | | `description` | string \| null | yes | | | `starts_at` | string | yes | ISO 8601 with a UTC offset. | | `ends_at` | string \| null | yes | ISO 8601 with a UTC offset. | | `timezone` | string | yes | | | `location_name` | string \| null | yes | | | `location_address` | string \| null | yes | | | `online_url` | string \| null | yes | | | `price_note` | string \| null | yes | | | `cover_image_url` | string \| null | yes | | | `status` | "draft" \| "published" \| "cancelled" | yes | | | `visibility` | "public" \| "unlisted" | yes | Private events are never served here (404 `event_not_found`). | | `state` | "open" \| "full_waitlist" \| "full" \| "ended" \| "cancelled" | yes | What the widget should show: `open`, `full_waitlist` (full, new RSVPs join the waitlist), `full`, `ended` or `cancelled`. New values may be added; treat an unknown one like `open` without the RSVP button. | | `capacity` | integer \| null | yes | | | `max_guests` | integer | yes | | | `waitlist_enabled` | boolean | yes | | | `counts` | Counts | yes | | | `fields` | EventField[] | yes | | | `url` | string | yes | | | `calendar` | CalendarLinks | yes | | | `organizer` | PublicOrganizer | yes | | | `branding` | PublicBranding | yes | | | `turnstile_site_key` | string \| null | yes | Null when no bot check is configured; the RSVP then needs no token. | ### PublicEventList | Field | Type | Required | Notes | | --- | --- | --- | --- | | `data` | PublicEvent[] | yes | | | `next_cursor` | string \| null | yes | | ### PublicOrganizer | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `name` | string | yes | | | `slug` | string | yes | | | `logo_url` | string \| null | yes | | | `accent_color` | string \| null | yes | | ### PublicRsvp A guest's own RSVP, reached through its manage token. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `status` | "going" \| "not_going" \| "waitlisted" \| "cancelled" | yes | `waitlisted` is set by WhoComing when the event is full; it cannot be requested directly. | | `name` | string \| null | yes | `null` when `locked` is true. | | `email` | string \| null | yes | `null` when `locked` is true. | | `guests` | integer | yes | | | `answers` | Answers | yes | | | `checked_in_at` | string \| null | yes | ISO 8601 with a UTC offset. | | `locked` | boolean | yes | | | `event` | PublicEvent | yes | | ### PublicRsvpCreated | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `status` | "going" \| "not_going" \| "waitlisted" \| "cancelled" | yes | `waitlisted` is set by WhoComing when the event is full; it cannot be requested directly. | | `guests` | integer | yes | | | `manage_token` | string | yes | Lets the guest view or change this RSVP. Shown once; also emailed. | | `manage_url` | string | yes | | | `calendar` | CalendarLinks | yes | | ### Rsvp | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `event_id` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `name` | string \| null | yes | `null` when `locked` is true, or after the retention period. | | `email` | string \| null | yes | `null` when `locked` is true, or after the retention period. | | `status` | "going" \| "not_going" \| "waitlisted" \| "cancelled" | yes | `waitlisted` is set by WhoComing when the event is full; it cannot be requested directly. | | `guests` | integer | yes | Extra guests (plus-ones). | | `answers` | Answers | yes | | | `source` | "embed" \| "page" \| "api" \| "dashboard" | yes | Where the RSVP came from. New values may be added. | | `locked` | boolean | yes | True when the RSVP arrived after a Free organization reached its monthly limit. Guest details are hidden until the organization upgrades or the next month starts. | | `checked_in_at` | string \| null | yes | ISO 8601 with a UTC offset. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `updated_at` | string | yes | ISO 8601 with a UTC offset. | ### RsvpCancelledWebhook The `rsvp.cancelled` webhook body. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | Unique per delivery and the same on every retry. Also the `webhook-id` header. Use it to ignore duplicates. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `type` | "rsvp.cancelled" | yes | | | `data` | RsvpWebhookData \| RsvpDeletedWebhookData | yes | | ### RsvpCheckedInWebhook The `rsvp.checked_in` webhook body. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | Unique per delivery and the same on every retry. Also the `webhook-id` header. Use it to ignore duplicates. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `type` | "rsvp.checked_in" | yes | | | `data` | RsvpWebhookData | yes | | ### RsvpCreatedWebhook The `rsvp.created` webhook body. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | Unique per delivery and the same on every retry. Also the `webhook-id` header. Use it to ignore duplicates. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `type` | "rsvp.created" | yes | | | `data` | RsvpWebhookData | yes | | ### RsvpDeletedWebhookData Sent as `rsvp.cancelled` when an RSVP that was not already cancelled is deleted. Identifiers only: the guest's details are gone. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `event_id` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `status` | "cancelled" | yes | | | `deleted` | true | yes | The RSVP was deleted (by the organizer or a data erasure request). | | `name` | null | no | | | `email` | null | no | | | `answers` | null | no | | | `guest_details_removed` | true | no | Present when the guest was erased or the retention period passed before this delivery was sent. `name`, `email` and `answers` are then null. | ### RsvpList | Field | Type | Required | Notes | | --- | --- | --- | --- | | `data` | Rsvp[] | yes | | | `next_cursor` | string \| null | yes | Pass as `cursor` to get the next page. `null` on the last page. | ### RsvpPromotedWebhook The `rsvp.promoted` webhook body. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | Unique per delivery and the same on every retry. Also the `webhook-id` header. Use it to ignore duplicates. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `type` | "rsvp.promoted" | yes | | | `data` | RsvpWebhookData | yes | | ### RsvpUpdatedWebhook The `rsvp.updated` webhook body. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | Unique per delivery and the same on every retry. Also the `webhook-id` header. Use it to ignore duplicates. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `type` | "rsvp.updated" | yes | | | `data` | RsvpWebhookData | yes | | ### RsvpWebhookData The RSVP after the change. Sent with every `rsvp.*` event type. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `event_id` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `status` | "going" \| "not_going" \| "waitlisted" \| "cancelled" | yes | `waitlisted` is set by WhoComing when the event is full; it cannot be requested directly. | | `name` | string \| null | yes | `null` when `locked` is true or the guest's details were removed. | | `email` | string \| null | yes | `null` when `locked` is true or the guest's details were removed. | | `guests` | integer | yes | | | `answers` | Answers | yes | | | `source` | "embed" \| "page" \| "api" \| "dashboard" | yes | Where the RSVP came from. New values may be added. | | `locked` | boolean | yes | True for an RSVP over a Free organization's monthly limit. Details are hidden. | | `checked_in_at` | string \| null | yes | ISO 8601 date and time with an offset. | | `created_at` | string | yes | ISO 8601 date and time with an offset. | | `updated_at` | string | yes | ISO 8601 date and time with an offset. | | `guest_details_removed` | true | no | Present when the guest was erased or the retention period passed before this delivery was sent. `name`, `email` and `answers` are then null. | ### Sandbox A throwaway organization in test mode with a key and a sample event. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `organization` | SandboxOrganization | yes | | | `api_key` | string | yes | A `wc_test_` secret key for the sandbox. Shown once. | | `expires_at` | string | yes | The sandbox and everything in it is deleted 24 hours after creation. | | `event` | Event | yes | | ### SandboxOrganization | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `name` | string | yes | | | `slug` | string | yes | | ### Series A recurring event. Occurrences are created as events about 90 days ahead. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `title` | string | yes | | | `recurrence` | Recurrence | yes | | | `rrule` | string | yes | The stored RRULE, for reference. Read-only. | | `timezone` | string | yes | | | `starts_on` | string | yes | | | `start_time` | string | yes | Wall-clock start time in the series timezone, 24-hour HH:MM. | | `duration_minutes` | integer | yes | | | `ends_on` | string \| null | yes | | | `template` | EventTemplate | yes | | | `status` | "active" \| "ended" | yes | | | `created_at` | string | yes | ISO 8601 with a UTC offset. | ### SeriesList | Field | Type | Required | Notes | | --- | --- | --- | --- | | `data` | Series[] | yes | | | `next_cursor` | string \| null | yes | Pass as `cursor` to get the next page. `null` on the last page. | ### UpdateEventRequest Only the fields you send are changed. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `title` | string | no | | | `starts_at` | string | no | ISO 8601. The offset is optional: without one, the time is read in the event's timezone. | | `ends_at` | string \| null | no | ISO 8601. The offset is optional: without one, the time is read in the event's timezone. | | `timezone` | string | no | IANA timezone name. | | `slug` | string | no | | | `status` | "draft" \| "published" \| "cancelled" | no | Set `cancelled` to cancel the event and notify its guests. | | `description` | string \| null | no | | | `location_name` | string \| null | no | | | `location_address` | string \| null | no | | | `online_url` | string \| null | no | Link for an online event. `https://` only. | | `capacity` | integer \| null | no | Seats. `null` means no limit. | | `max_guests` | integer | no | Extra guests (plus-ones) each RSVP may bring. | | `waitlist_enabled` | boolean | no | | | `visibility` | "public" \| "unlisted" \| "private" | no | `public` events are listed and indexed. `unlisted` events work by link and embed but are not listed. `private` events are only visible through this API and the dashboard. | | `price_note` | string \| null | no | | | `cover_image_url` | string \| null | no | Image shown on the hosted page and in search results. `https://` only. | | `fields` | EventFieldInput[] | no | Custom questions, in display order. At most 100, or fewer on your plan. Each `key` must be unique. | ### UpdatePublicRsvpRequest | Field | Type | Required | Notes | | --- | --- | --- | --- | | `status` | "going" \| "not_going" \| "cancelled" | no | `cancelled` gives the seat back; the waitlist moves up. | | `guests` | integer | no | | | `answers` | AnswersInput | no | | | `name` | string | no | | ### UpdateRsvpRequest Only the fields you send are changed. `answers` replaces the stored answers and is checked like on create: values must match their question's type, unknown keys are refused, and required questions may be left out. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `name` | string | no | | | `email` | string | no | At most 320 characters. Spaces around it are removed. | | `guests` | integer | no | | | `answers` | AnswersInput | no | | | `status` | "going" \| "not_going" \| "cancelled" | no | Set `cancelled` to cancel; a freed seat promotes the waitlist. | ### UpdateSeriesRequest Only the fields you send are changed. Changes apply to future occurrences. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `title` | string | no | | | `recurrence` | Recurrence | no | | | `start_time` | string | no | Wall-clock start time in the series timezone, 24-hour HH:MM. | | `duration_minutes` | integer | no | | | `ends_on` | string \| null | no | | | `template` | EventTemplateInput | no | | ### UpdateWebhookEndpointRequest | Field | Type | Required | Notes | | --- | --- | --- | --- | | `url` | string | no | | | `events` | "rsvp.created" \| "rsvp.updated" \| "rsvp.cancelled" \| "rsvp.promoted" \| "rsvp.checked_in" \| "event.created" \| "event.updated" \| "event.cancelled"[] | no | | | `disabled` | boolean | no | `true` to pause deliveries, `false` to resume (also resets the failure count). | ### Usage Current period usage and plan limits. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `mode` | "live" \| "test" | yes | Mode of the key that asked. Usage itself only counts live RSVPs. | | `plan` | "free" \| "starter" \| "pro" | yes | New plans may be added. | | `period_start` | string | yes | Start of the current calendar month in UTC. | | `period_end` | string | yes | Start of the next calendar month in UTC. | | `rsvps` | UsageRsvps | yes | | | `limits` | UsageLimits | yes | | ### UsageLimits | Field | Type | Required | Notes | | --- | --- | --- | --- | | `api_keys` | integer | yes | | | `webhook_endpoints` | integer | yes | | | `team_members` | integer | yes | | | `custom_fields_per_event` | integer \| null | yes | Custom fields per event. `null` means unlimited. | | `active_series` | integer \| null | yes | Active recurring series. `null` means unlimited. | | `rate_limit_per_minute` | integer | yes | | ### UsageRsvps | Field | Type | Required | Notes | | --- | --- | --- | --- | | `used` | integer | yes | | | `limit` | integer | yes | | | `remaining` | integer | yes | Never below 0. | | `locked` | integer | yes | RSVPs this period with hidden guest details (Free over its limit). | | `overage_blocks` | integer | yes | Blocks of 1,000 extra RSVPs billed at period end (Starter and Pro). | ### WebhookDelivery | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | Also the `webhook-id` header and envelope `id`. | | `endpoint_id` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `event_type` | "rsvp.created" \| "rsvp.updated" \| "rsvp.cancelled" \| "rsvp.promoted" \| "rsvp.checked_in" \| "event.created" \| "event.updated" \| "event.cancelled" | yes | New event types may be added. | | `status` | "pending" \| "delivered" \| "failed" \| "skipped" | yes | `pending` while retries remain, `delivered` after a 2xx, `failed` after 24 hours of retries. `skipped` when WhoComing decided not to send it. New values may be added. | | `attempts` | integer | yes | | | `next_attempt_at` | string \| null | yes | ISO 8601 with a UTC offset. | | `delivered_at` | string \| null | yes | ISO 8601 with a UTC offset. | | `last_status` | integer \| null | yes | HTTP status from the last attempt. | | `last_error` | string \| null | yes | | | `payload` | WebhookEnvelope | yes | | | `created_at` | string | yes | ISO 8601 with a UTC offset. | ### WebhookDeliveryList | Field | Type | Required | Notes | | --- | --- | --- | --- | | `data` | WebhookDelivery[] | yes | | | `next_cursor` | string \| null | yes | Pass as `cursor` to get the next page. `null` on the last page. | ### WebhookEndpoint | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `url` | string | yes | | | `events` | "rsvp.created" \| "rsvp.updated" \| "rsvp.cancelled" \| "rsvp.promoted" \| "rsvp.checked_in" \| "event.created" \| "event.updated" \| "event.cancelled"[] | yes | Event types sent to this endpoint. | | `disabled_at` | string \| null | yes | Set when the endpoint was disabled, by you or after ten failed deliveries in a row. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | ### WebhookEndpointList | Field | Type | Required | Notes | | --- | --- | --- | --- | | `data` | WebhookEndpoint[] | yes | | | `next_cursor` | string \| null | yes | Pass as `cursor` to get the next page. `null` on the last page. | ### WebhookEnvelope The envelope that was sent: `{ id, type, created_at, mode, data }`. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | string | yes | Unique per delivery and the same on every retry. Also the `webhook-id` header. Use it to ignore duplicates. | | `created_at` | string | yes | ISO 8601 with a UTC offset. | | `mode` | "live" \| "test" | yes | `live` or `test`. Always the mode of the API key that made the request. | | `type` | "rsvp.created" \| "rsvp.updated" \| "rsvp.cancelled" \| "rsvp.promoted" \| "rsvp.checked_in" \| "event.created" \| "event.updated" \| "event.cancelled" | yes | | | `data` | RsvpWebhookData \| RsvpDeletedWebhookData \| EventWebhookData | yes | | ### WeeklyRecurrence Every week on one weekday. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `frequency` | "weekly" | yes | | | `weekday` | Weekday | yes | |