Guests API
Manage guest profiles within an organization — create, list, retrieve, update, and delete.
Authentication
All endpoints require a valid Bearer token in the Authorization header.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /api/guests/:orgId/create | Create a new guest |
GET | /api/guests/:orgId/list | List all guests |
GET | /api/guests/:orgId/overview | Get guest statistics |
GET | /api/guests/:orgId/for-booking | Get guests formatted for booking |
GET | /api/guests/:orgId/:guestId | Get guest by ID |
PUT | /api/guests/:orgId/:guestId/update | Update guest details |
DELETE | /api/guests/:orgId/:guestId/delete | Delete a guest |
Path Parameters
| Parameter | Type | Description |
|---|---|---|
orgId | string | Organization ID |
guestId | string | Guest document ID |
Create Guest
POST /api/guests/:orgId/createRequest Body
json
{
"name": "Priya Sharma",
"email": "priya.sharma@example.com",
"phone": "+91-9876543210",
"address": {
"street": "42 MG Road",
"city": "Bangalore",
"state": "Karnataka",
"postalCode": "560001",
"country": "India"
},
"idProof": {
"type": "passport",
"number": "J8765432"
},
"dateOfBirth": "1990-05-15",
"nationality": "Indian",
"company": "TechCorp Pvt Ltd",
"gstNumber": "29ABCDE1234F1Z5",
"notes": "Prefers high-floor rooms"
}Success Response 201
json
{
"success": true,
"message": "Guest created successfully",
"data": {
"_id": "64f1b2c3d4e5f6a7b8c9d0e3",
"name": "Priya Sharma",
"email": "priya.sharma@example.com",
"phone": "+91-9876543210",
"address": {
"street": "42 MG Road",
"city": "Bangalore",
"state": "Karnataka",
"postalCode": "560001",
"country": "India"
},
"idProof": {
"type": "passport",
"number": "J8765432"
},
"dateOfBirth": "1990-05-15",
"nationality": "Indian",
"company": "TechCorp Pvt Ltd",
"gstNumber": "29ABCDE1234F1Z5",
"notes": "Prefers high-floor rooms",
"orgId": "64f1b2c3d4e5f6a7b8c9d0e0",
"createdAt": "2026-02-20T10:00:00.000Z",
"updatedAt": "2026-02-20T10:00:00.000Z"
}
}Error Response 400
json
{
"success": false,
"message": "Validation error",
"errors": [
"name is required",
"phone or email is required"
]
}Error Response 409
json
{
"success": false,
"message": "Guest with this email already exists"
}List Guests
GET /api/guests/:orgId/listQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number |
limit | number | 10 | Results per page |
search | string | — | Search by name, email, or phone |
sort | string | name | Sort field (name, createdAt) |
order | string | asc | Sort order (asc or desc) |
Success Response 200
json
{
"success": true,
"data": [
{
"_id": "64f1b2c3d4e5f6a7b8c9d0e3",
"name": "Priya Sharma",
"email": "priya.sharma@example.com",
"phone": "+91-9876543210",
"company": "TechCorp Pvt Ltd",
"totalBookings": 5,
"lastStay": "2026-02-10T00:00:00.000Z",
"createdAt": "2026-01-05T10:00:00.000Z"
}
],
"pagination": {
"total": 120,
"page": 1,
"limit": 10,
"totalPages": 12
}
}Guest Overview
GET /api/guests/:orgId/overviewReturns aggregate statistics about the guest database.
Success Response 200
json
{
"success": true,
"data": {
"totalGuests": 120,
"newGuestsThisMonth": 18,
"returningGuests": 45,
"topNationalities": [
{ "nationality": "Indian", "count": 75 },
{ "nationality": "American", "count": 15 },
{ "nationality": "British", "count": 10 }
],
"topCompanies": [
{ "company": "TechCorp Pvt Ltd", "count": 8 },
{ "company": "InnoSoft", "count": 5 }
]
}
}Get Guests for Booking
GET /api/guests/:orgId/for-bookingReturns a lightweight list of guests optimised for populating booking form dropdowns.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
search | string | — | Filter by name, email, or phone |
limit | number | 20 | Maximum results to return |
Success Response 200
json
{
"success": true,
"data": [
{
"_id": "64f1b2c3d4e5f6a7b8c9d0e3",
"name": "Priya Sharma",
"email": "priya.sharma@example.com",
"phone": "+91-9876543210"
},
{
"_id": "64f1b2c3d4e5f6a7b8c9d0e8",
"name": "James Wilson",
"email": "james.wilson@example.com",
"phone": "+1-555-0123"
}
]
}Get Guest by ID
GET /api/guests/:orgId/:guestIdSuccess Response 200
json
{
"success": true,
"data": {
"_id": "64f1b2c3d4e5f6a7b8c9d0e3",
"name": "Priya Sharma",
"email": "priya.sharma@example.com",
"phone": "+91-9876543210",
"address": {
"street": "42 MG Road",
"city": "Bangalore",
"state": "Karnataka",
"postalCode": "560001",
"country": "India"
},
"idProof": {
"type": "passport",
"number": "J8765432"
},
"dateOfBirth": "1990-05-15",
"nationality": "Indian",
"company": "TechCorp Pvt Ltd",
"gstNumber": "29ABCDE1234F1Z5",
"notes": "Prefers high-floor rooms",
"bookingHistory": [
{
"_id": "64f1b2c3d4e5f6a7b8c9d0f1",
"bookingCode": "BK-2026-042",
"checkIn": "2026-02-05",
"checkOut": "2026-02-10",
"roomNumber": "301"
}
],
"createdAt": "2026-01-05T10:00:00.000Z",
"updatedAt": "2026-02-10T14:25:00.000Z"
}
}Error Response 404
json
{
"success": false,
"message": "Guest not found"
}Update Guest
PUT /api/guests/:orgId/:guestId/updateRequest Body
json
{
"phone": "+91-9876500000",
"address": {
"street": "100 Indiranagar",
"city": "Bangalore",
"state": "Karnataka",
"postalCode": "560038",
"country": "India"
},
"notes": "Prefers high-floor rooms, vegetarian meals"
}Success Response 200
json
{
"success": true,
"message": "Guest updated successfully",
"data": {
"_id": "64f1b2c3d4e5f6a7b8c9d0e3",
"name": "Priya Sharma",
"phone": "+91-9876500000",
"address": {
"street": "100 Indiranagar",
"city": "Bangalore",
"state": "Karnataka",
"postalCode": "560038",
"country": "India"
},
"notes": "Prefers high-floor rooms, vegetarian meals",
"updatedAt": "2026-02-21T09:00:00.000Z"
}
}Error Response 404
json
{
"success": false,
"message": "Guest not found"
}Delete Guest
DELETE /api/guests/:orgId/:guestId/deleteSuccess Response 200
json
{
"success": true,
"message": "Guest deleted successfully"
}Error Response 404
json
{
"success": false,
"message": "Guest not found"
}Error Response 409
json
{
"success": false,
"message": "Cannot delete guest with active bookings"
}