# On-Air API The Roam HQ On-Air API lets you create and manage events, guest lists, RSVPs, and attendance programmatically. Build custom registration flows, sync with external event platforms, or automate your community event operations. **OpenAPI Spec:** [onair.json](https://developer.ro.am/onair.json) ## Concepts ### Events An **event** represents a scheduled gathering — virtual or in-person — hosted through Roam. Each event has a title, start/end time, time zone, and an automatically generated **event page** where guests can view details and RSVP. Events have a **slug** (e.g. `product-launch`) that determines the event page URL. Slugs are unique within your organization and are generated automatically if not provided. **Event settings:** | Setting | Description | |---------|-------------| | `autoAdmit` | When `true` (default), guests who RSVP'd "going" are automatically admitted to the Roam room. When `false`, a host must manually approve each guest. | | `disableRSVP` | When `true`, the event page is view-only — guests cannot RSVP. Useful for when events have reached your determined capacity. | | `enableSEO` | When `true`, the event page is indexed by search engines. Set to `false` for private or internal events. | **Event lifecycle:** Events are active from creation until canceled. There is no explicit "ended" state — whether an event has concluded is determined by comparing the current time against its `end` timestamp. ### Guests A **guest** is a person on an event's invite list. Guests are identified by email and have an **RSVP status**: | Status | Meaning | |--------|---------| | `invited` | Added to the guest list but hasn't responded | | `going` | Confirmed attending | | `maybe` | Tentatively attending | | `notGoing` | Declined | Guests with status `going` or `maybe` receive calendar invites and reminder notifications. Use [`/onair.guest.add`](/docs/onair-api/onair-guest-add) to add guests in bulk and [`/onair.guest.update`](/docs/onair-api/onair-guest-update) to change their RSVP status. ### Hosts On-Air separates two host concepts: - **Calendar host** (`calendarHostEmail`): the person who owns the calendar event. They manage invites and reminders. Set when creating the event and changeable via [`/onair.event.update`](/docs/onair-api/onair-event-update). The calendar host email is not included in the event response. - **Display hosts** (`hosts[]`): the people shown on the event page. Each has a name and optional avatar image. Display hosts are independent of the calendar host — they can be anyone. Display hosts are set when creating or updating the event via the `hosts` field. They are returned in the event response from [`/onair.event.info`](/docs/onair-api/onair-event-info). The host order is set by the event organizer. ### Attendance The **attendance report** ([`/onair.attendance.list`](/docs/onair-api/onair-attendance-list)) combines RSVP data with actual join data. Each row includes: - **RSVP fields:** email, name, phone, RSVP status, custom form responses - **Join fields:** `joinStart` (when they joined), `joinDurationMinutes` (how long they stayed) Guests who RSVP'd are listed first, followed by any attendees who joined the event without an RSVP. A person "attended" if they have a `joinStart` timestamp. Custom form responses (`customResponses`) contain answers to event-specific registration fields (e.g. dietary restrictions, company name, session preferences) as key-value pairs. ## Endpoints ### Events | Endpoint | Method | Description | |----------|--------|-------------| | [`/onair.event.info`](/docs/onair-api/onair-event-info) | GET | Get details for an event | | [`/onair.event.list`](/docs/onair-api/onair-event-list) | GET | List events (most recent first) | | [`/onair.event.create`](/docs/onair-api/onair-event-create) | POST | Create a new event | | [`/onair.event.update`](/docs/onair-api/onair-event-update) | POST | Update an event | | [`/onair.event.cancel`](/docs/onair-api/onair-event-cancel) | POST | Cancel an event | ### Guests | Endpoint | Method | Description | |----------|--------|-------------| | [`/onair.guest.info`](/docs/onair-api/onair-guest-info) | GET | Get details for a guest | | [`/onair.guest.list`](/docs/onair-api/onair-guest-list) | GET | List guests for an event (newest first) | | [`/onair.guest.add`](/docs/onair-api/onair-guest-add) | POST | Add guests to an event | | [`/onair.guest.update`](/docs/onair-api/onair-guest-update) | POST | Update a guest's RSVP status | | [`/onair.guest.remove`](/docs/onair-api/onair-guest-remove) | POST | Remove a guest from an event | ### Attendance | Endpoint | Method | Description | |----------|--------|-------------| | [`/onair.attendance.list`](/docs/onair-api/onair-attendance-list) | GET | Get attendance report for an event | ## Common Use Cases ### Sync with External Event Platforms Replace or complement platforms like Luma by managing events through the API. Create events, import guest lists, and track RSVPs in your own system. ### Custom Registration Flows Build branded registration pages that add guests via [`/onair.guest.add`](/docs/onair-api/onair-guest-add) and receive real-time RSVP updates through `onair.guest.rsvp` webhooks. ### Attendance Reporting Pull attendance data with [`/onair.attendance.list`](/docs/onair-api/onair-attendance-list) to track who joined, how long they stayed, and correlate with RSVP status. ## Webhooks On-Air events are available as real-time webhooks. Subscribe via the [Webhooks API](/docs/webhooks/webhook-subscribe): | Event | Description | |-------|-------------| | `onair.event.created` | Event is created | | `onair.event.updated` | Event is updated | | `onair.event.canceled` | Event is canceled | | `onair.guest.rsvp` | Guest RSVP status changed | | `onair.guest.added` | Guest(s) added to an event | ## Authentication All requests require a Bearer token. Create an API Key or OAuth app in **Roam Administration > Developer**. ``` Authorization: Bearer YOUR_API_KEY ``` ## Base URL ``` https://api.ro.am/v1 ``` ## Pagination List endpoints use cursor-based pagination. Pass the `nextCursor` value from a response as the `cursor` parameter on the next request to fetch the next page. When there are no more results, `nextCursor` is absent from the response. --- Have questions? Contact us via [Roam Support Chat](https://ro.am/support/contact-us) or email [developer@ro.am](mailto:developer@ro.am). ## Base URL ``` https://api.ro.am/v1 ``` ## Authentication ``` Authorization: Bearer YOUR_API_KEY ``` ## All Endpoints | Method | Endpoint | Description | |--------|----------|-------------| | GET | [`/onair.event.info`](/docs/onair-api/onair-event-info) | Get event info | | GET | [`/onair.event.list`](/docs/onair-api/onair-event-list) | List events | | POST | [`/onair.event.create`](/docs/onair-api/onair-event-create) | Create an event | | POST | [`/onair.event.update`](/docs/onair-api/onair-event-update) | Update an event | | POST | [`/onair.event.cancel`](/docs/onair-api/onair-event-cancel) | Cancel an event | | GET | [`/onair.guest.info`](/docs/onair-api/onair-guest-info) | Get guest info | | GET | [`/onair.guest.list`](/docs/onair-api/onair-guest-list) | List guests | | POST | [`/onair.guest.add`](/docs/onair-api/onair-guest-add) | Add guests | | POST | [`/onair.guest.update`](/docs/onair-api/onair-guest-update) | Update guest RSVP | | POST | [`/onair.guest.remove`](/docs/onair-api/onair-guest-remove) | Remove a guest | | GET | [`/onair.attendance.list`](/docs/onair-api/onair-attendance-list) | List attendance | ## Contact - Email: developer@ro.am - Website: https://developer.ro.am --- *Machine-readable API documentation.* *Full documentation: https://developer.ro.am/docs/onair-api*