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
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 to add guests in bulk and /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. 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. The host order is set by the event organizer.
Attendance
The attendance report (/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 | GET | Get details for an event |
/onair.event.list | GET | List events (most recent first) |
/onair.event.create | POST | Create a new event |
/onair.event.update | POST | Update an event |
/onair.event.cancel | POST | Cancel an event |
Guests
| Endpoint | Method | Description |
|---|---|---|
/onair.guest.info | GET | Get details for a guest |
/onair.guest.list | GET | List guests for an event (newest first) |
/onair.guest.add | POST | Add guests to an event |
/onair.guest.update | POST | Update a guest's RSVP status |
/onair.guest.remove | POST | Remove a guest from an event |
Attendance
| Endpoint | Method | Description |
|---|---|---|
/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 and receive real-time RSVP updates through onair.guest.rsvp webhooks.
Attendance Reporting
Pull attendance data with /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 Events API:
| 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 or email developer@ro.am.
Authentication
- HTTP: Bearer Auth
Pass your API Key or OAuth access token as a Bearer token.
Example: Authorization: Bearer <token>
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Terms of Service
https://ro.am/terms🗃️ Events
5 items
🗃️ Guests
5 items
🗃️ Attendance
1 item