# List lobby bookings

`GET /lobbyBooking.list`

## Description

Lists bookings for a specific lobby configuration, filtered by date range (after/before).

The ordering of results depends on the filter specified:

- When no parameters are provided, the most recent bookings are returned,
  sorted in reverse chronological order. This is equivalent to specifying `before`
  as NOW and leaving `after` unspecified.

- If `after` is specified, the results are sorted in forward chronological order.

Either dates or datetimes may be specified. Dates are interpreted in UTC.

**Access:** Organization only.

**Required scope:** `lobby:read`

---

**OpenAPI Spec:** [chat.json](https://developer.ro.am/chat.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `lobbyId` | query | string | Yes | The lobby configuration ID to list bookings for. |
| `after` | query | string | No | The datetime to begin listing bookings (YYYY-MM-DD or RFC-3339). Defaults to "no filter".  |
| `before` | query | string | No | The datetime until which to list bookings (YYYY-MM-DD or RFC-3339). Defaults to "now".  |
| `limit` | query | integer | No | The number of bookings to return per response. Default is 10. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |

## Responses

### 200 - OK

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `bookings` | LobbyBooking[] | No |  |
| `nextCursor` | string | No | Returned if there is a subsequent page of bookings. |

**LobbyBooking** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | Unique booking identifier |
| `start` | string | Yes | Start time in RFC3339 |
| `end` | string | Yes | End time in RFC3339 |
| `status` | string | Yes | Current status of the booking |
| `timeZone` | string | No | IANA time zone of the booking times |
| `notes` | string | No | Optional notes provided by the booker |
| `created` | string | No | Creation time |
| `hosts` | LobbyBookingHost[] | No |  |
| `invitees` | LobbyBookingInvitee[] | No |  |
| `responses` | LobbyBookingResponse[] | No | The guest's answers to the lobby's custom questions, including hidden fields populated from URL query parameters on the lobby link. One entry per answered question; empty or absent when the guest answ |
| `meetingLink` | string | No | Meeting link URL, used to join the meeting |

**LobbyBookingHost** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | No | Display name of the host |
| `email` | string | Yes | Email address of the host |
| `isOrganizer` | boolean | Yes | Whether this host is the organizer |

**LobbyBookingInvitee** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | No | Display name of the invitee |
| `email` | string | Yes | Email address of the invitee |
| `status` | string | Yes | Invitee's RSVP or booking status |
| `isBooker` | boolean | No | Whether this invitee created the booking |

**LobbyBookingResponse** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `fieldId` | string | Yes | ID of the custom field (question) this answer belongs to. |
| `key` | string | No | The field's stable key, if the lobby owner assigned one, as captured when the booking was made. For hidden fields this is the URL query parameter name used to populate the value.  |
| `question` | string | No | The question's display name. Omitted if the field definition can no longer be found on the lobby configuration.  |
| `type` | "short_text" | "text" | "email" | "phone_number" | "radio" | "checkbox" | "dropdown" | "hidden" | No | The custom field type. Omitted when `question` is omitted. |
| `value` | object | No | The human-readable answer. For option fields (radio, checkbox, dropdown) this is the selected option label(s), not internal option IDs. Checkbox answers are arrays of strings; all other answers are st |


#### Example Response

```json
{
  "bookings": [
    {
      "id": "018f3f37-eca3-7d07-8a12-9e65a8a0c1b9",
      "start": "2025-08-03T14:10:54Z",
      "end": "2025-08-03T14:40:54Z",
      "status": "active",
      "timeZone": "America/Los_Angeles",
      "notes": "Intro call",
      "created": "2025-08-01T10:00:00Z",
      "hosts": [
        {
          "name": "Alex Doe",
          "email": "alex@example.com",
          "isOrganizer": true
        }
      ],
      "invitees": [
        {
          "name": "Sam Smith",
          "email": "sam@example.com",
          "status": "invited",
          "isBooker": true
        }
      ],
      "responses": [
        {
          "fieldId": "018f3f36-1111-7aaa-8000-9e65a8a0c1b9",
          "key": "utm_source",
          "question": "UTM Source",
          "type": "hidden",
          "value": "partner"
        },
        {
          "fieldId": "018f3f36-2222-7bbb-8000-9e65a8a0c1b9",
          "question": "What would you like to discuss?",
          "type": "text",
          "value": "Pricing for 50 seats"
        },
        {
          "fieldId": "018f3f36-3333-7ccc-8000-9e65a8a0c1b9",
          "question": "Products of interest",
          "type": "checkbox",
          "value": [
            "Widgets",
            "Gadgets"
          ]
        }
      ]
    }
  ],
  "nextCursor": "018f3f39-2b5c-7b3d-9f96-8b2f1c0e1234"
}
```

### 400 - Bad request.

### 401 - Presented invalid authentication credentials.

### 404 - Lobby not found.

### 405 - An unsupported method was requested.

### 500 - An internal error occured.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/chat-api/lobby-booking-list*