> ## Documentation Index
> Fetch the complete documentation index at: https://help.teamm.work/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /guests

> Get a filtered list of guests with advanced query options.

<Note>
  This endpoint returns data in a **humanized format**, meaning all
  information is ready to be displayed in the language you requested. Use the
  optional `X-LOCALE` header for localization.
</Note>

## Authentication

This endpoint requires authentication. See [Authentication](/api-reference/authentication) for detailed information about required headers and how to obtain your API keys.

## Query Parameters

<Note>
  **Required Parameters:** You must provide either (`startDate` AND `endDate`)
  OR (`sessionId` OR `sessionIds`) to filter the results. **Optional
  Filters:** `sessionIdsExclude` can be used with `startDate` and `endDate` to
  exclude specific sessions from the date range.
</Note>

### Date & Session Filtering

<ParamField path="startDate" type="string">
  Filter guests by start date (from this date). Required when not using
  sessionId/sessionIds. Must be in ISO string format (e.g.,
  "2025-01-01T00:00:00.000Z" or "2025-01-01").
</ParamField>

<ParamField path="endDate" type="string">
  Filter guests by end date (to this date). Required when not using
  sessionId/sessionIds. Must be in ISO string format (e.g.,
  "2025-01-31T23:59:59.999Z" or "2025-01-31").
</ParamField>

<ParamField path="sessionId" type="string">
  Filter guests by a specific session ID. Use this to get guests for a single
  session.
</ParamField>

<ParamField path="sessionIds" type="array">
  Filter guests by multiple session IDs. Use this to get guests for multiple
  sessions. Provide as comma-separated values (e.g., "sess1,sess2,sess3").
</ParamField>

<ParamField path="sessionIdsExclude" type="array">
  Exclude guests from specific session IDs. Can be used in combination with
  startDate and endDate parameters to filter out specific sessions from a date
  range. Provide as comma-separated values (e.g., "sess1,sess2,sess3").
</ParamField>

### Guest Filtering

<ParamField path="role" type="'patient' | 'companion' | 'guest'">
  Filter guests by their role
</ParamField>

<ParamField path="status" type="'registered' | 'waitingList' | 'review' | 'confirmed' | 'arrived' | 'paid' | 'cancelled' | 'voided' | 'registeredOnline' | 'offer' | 'departed'">
  Filter guests by their booking status: - `registered` - Guest is registered

  * `waitingList` - Guest is on waiting list - `review` - Booking is under
    review - `confirmed` - Booking is confirmed - `arrived` - Guest has arrived
  * `paid` - Payment completed - `cancelled` - Booking cancelled - `voided` -
    Booking voided - `registeredOnline` - Registered through online system -
    `offer` - Like a draft booking, which can turn into a booking if the
    customer accepts the offer - `departed` - Guest has departed
</ParamField>

### Pagination

<ParamField path="start" type="number" default="1">
  The starting page number for pagination. Used to control which page of
  results to return.
</ParamField>

<ParamField path="length" type="number" default="50">
  The number of results to return per page. Maximum value is typically 100.
</ParamField>

### Field Projection

<ParamField path="project" type="array">
  Specify which fields to include in the response. You can project customer fields, booking fields, and custom meta fields.

  **📋 Complete Fields Reference**: See the [Guest API Fields Reference](/api-reference/guest-fields) for a comprehensive list of all available fields with descriptions and usage examples.

  **Quick Examples:**

  * Basic info: `firstName,lastName,email,phone`
  * Booking details: `startDate,endDate,status,role`
  * Financial data: `financial.total,financial.deposit.amount`
  * Medical info: `doctorName,therapistName,medicalData.notes`
  * Meal planning: `skippingMeals`
  * Custom fields: `meta.food-allergies,meta.special-needs`
</ParamField>

## Example Requests

**Filter by date range:**

```bash theme={null}
GET /guests?startDate=2025-01-01&endDate=2025-01-31&role=patient&status=confirmed&start=1&length=25&project=firstName,lastName,email,startDate,endDate,meta.food-allergies
```

**Filter by specific session:**

```bash theme={null}
GET /guests?sessionId=sess_123456&role=patient&start=1&length=25&project=firstName,lastName,email,startDate,endDate
```

**Filter by multiple sessions:**

```bash theme={null}
GET /guests?sessionIds=sess_123456,sess_789012,sess_345678&status=confirmed&start=1&length=25&project=firstName,lastName,email
```

**Filter by date range excluding specific sessions:**

```bash theme={null}
GET /guests?startDate=2025-01-01&endDate=2025-01-31&sessionIdsExclude=sess_999888,sess_777666&role=patient&start=1&length=25&project=firstName,lastName,email
```

## Response

The response returns data in a **humanized format**, meaning all information is localized and ready to be displayed to end users in the requested language.

```json theme={null}
{
	"data": [
		{
			"firstName": "John",
			"lastName": "Doe",
			"email": "john.doe@example.com",
			"startDate": "06/15/2024",
			"endDate": "06/22/2024",
			"status": "Confirmed",
			"role": "Patient",
			"skippingMeals": {
				"breakfast": ["2025-09-20", "2025-09-25"], // skips breakfast on these dates
				"lunch": [], // eats all lunches
				"dinner": ["2025-09-22"] // skips dinner on this date
			},
			"ids": {
				"role": "patient",
				"status": "confirmed",
				"sessionId": "sess_123456",
				"sessionIds": ["sess_123456", "sess_654321"] // if multiple sessions
				"startDate": "2025-06-15T16:00:00.000Z", // if included in project
				"endDate": "2025-06-22T18:00:00.000Z" // if included in project
			}
			// Additional fields based on project parameter
		}
	],
	"total": 125
}
```

<Note>
  **Date Formatting by Locale:** - **Romanian (ro) & Norwegian (no):**
  DD.MM.YYYY format (e.g., "15.01.2025") - **English and others:** MM/DD/YYYY
  format (e.g., "01/15/2025")
</Note>

<Note>
  **Humanized vs Technical Data:** - **Main fields** (like `status`, `role`,
  dates) are returned in human-readable, localized format - **`ids` field**
  contains the technical/raw values needed for API operations and integrations
</Note>

<Note>
  **Pagination:** Use the `start` and `length` parameters to paginate through
  results. The response includes a `total` field indicating the total number
  of records available.
</Note>

## Error Responses

<ResponseField name="400" type="Bad Request">
  Invalid query parameters or date format
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Missing or invalid authentication headers
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Insufficient permissions to access data
</ResponseField>