Skip to main content
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.

​
Authentication

This endpoint requires authentication. See Authentication for detailed information about required headers and how to obtain your API keys.

​
Query Parameters

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.

​
Date & Session Filtering

​
startDate
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”).
​
endDate
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”).
​
sessionId
string
Filter guests by a specific session ID. Use this to get guests for a single session.
​
sessionIds
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”).
​
sessionIdsExclude
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”).

​
Guest Filtering

​
role
'patient' | 'companion' | 'guest'
Filter guests by their role
​
status
'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

​
Pagination

​
start
number
default:"1"
The starting page number for pagination. Used to control which page of results to return.
​
length
number
default:"50"
The number of results to return per page. Maximum value is typically 100.

​
Field Projection

​
project
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 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

​
Example Requests

Filter by date range: 
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: 
GET /guests?sessionId=sess_123456&role=patient&start=1&length=25&project=firstName,lastName,email,startDate,endDate
Filter by multiple sessions: 
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: 
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. 
{
	"data": [
		{
			"firstName": "John",
			"lastName": "Doe",
			"email": "[email protected]",
			"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
}
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”)
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
Pagination: Use the start and length parameters to paginate through results. The response includes a total field indicating the total number of records available.

​
Error Responses

​
400
Bad Request
Invalid query parameters or date format
​
401
Unauthorized
Missing or invalid authentication headers
​
403
Forbidden
Insufficient permissions to access data