Skip to Content

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

  • 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

statusMeaning
draftNot taking RSVPs from guests. The API and dashboard can still add guests.
publishedLive. The default when you create an event through the API.
cancelledSet 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

visibilityWidget and linkListed on your calendarIndexed by search engines
publicYesYesYes
unlistedYesNoNo
privateNoNoNo

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):

typeAnswer in answers
text, textareaString
selectString, one of options
numberNumber
checkboxBoolean

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 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:

{ "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.

On this page