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.
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. Every field has a size or range limit, and online_url and cover_image_url must be https:// links.
Time
timezoneis an IANA name such asAmerica/Detroit. The widget and hosted page show times in the event's zone.- You may send
starts_atandends_atwithout an offset (2027-01-08T18:30:00); they are then read in the event'stimezone. 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_atis optional. Without it, the event counts as ended oncestarts_athas 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.
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.<key>. Text answers are trimmed, and empty ones are left out. One difference:
- Guests (the widget, hosted pages and the manage link) must answer every
requiredquestion. - 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:
{ "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.