Authentication

The StaySuite API uses OAuth 2.0 bearer tokens for authentication. All API requests must include a valid access token in the Authorization header.

POST /api/auth/token

Exchange credentials for an access token

Request Body
Parameter Type Required Description
client_id string Required Your application's client ID
client_secret string Required Your application's client secret
grant_type string Required OAuth grant type (client_credentials, authorization_code, refresh_token)
scope string Optional Space-separated list of scopes (e.g., "read write")
Example Request
curl -X POST https://api.staysuite.com/api/auth/token \ -H "Content-Type: application/json" \ -d '{ "client_id": "your_client_id", "client_secret": "your_client_secret", "grant_type": "client_credentials", "scope": "read write" }'
Response
{ "access_token": "", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "", "scope": "read write" }
{ "error": "invalid_client", "error_description": "Client authentication failed" }
POST /api/auth/refresh

Refresh an access token using a refresh token

Request Body
Parameter Type Required Description
refresh_token string Required The refresh token obtained from initial authentication
POST /api/auth/revoke

Revoke an access token or refresh token

🔐 Two-Factor Authentication (2FA)

When 2FA is enabled, include the TOTP code in the X-TOTP-Code header:

X-TOTP-Code: 123456

Users API

Manage user accounts, profiles, and permissions within your organization.

GET /api/users Auth Required Paginated

List all users in your organization

Query Parameters
Parameter Type Required Description
page integer Optional Page number (default: 1)
limit integer Optional Items per page (default: 20, max: 100)
role string Optional Filter by role (admin, manager, user, viewer)
status string Optional Filter by status (active, inactive, suspended)
search string Optional Search by name or email
Response Schema
{ "success": true, "data": [ { "id": "user_123", "email": "[email protected]", "name": "John Doe", "role": "manager", "status": "active", "created_at": "2025-01-01T00:00:00Z", "updated_at": "2025-01-15T10:30:00Z", "profile": { "avatar_url": "https://cdn.staysuite.com/avatars/user_123.jpg", "phone": "+1-555-0100", "timezone": "America/New_York", "language": "en" }, "permissions": [ "properties.read", "properties.write", "bookings.read", "bookings.write" ], "two_factor_enabled": true, "last_login": "2025-01-17T09:00:00Z" } ], "pagination": { "page": 1, "limit": 20, "total_items": 45, "total_pages": 3 } }
GET /api/users/{id} Auth Required

Get a specific user by ID

POST /api/users Auth Required

Create a new user account

Request Body
Parameter Type Required Description
email string Required User's email address
name string Required User's full name
password string Required Password (min 8 characters)
role string Required User role (admin, manager, user, viewer)
send_invite boolean Optional Send welcome email (default: true)
PUT /api/users/{id} Auth Required

Update user information

DELETE /api/users/{id} Auth Required

Delete a user account

Properties API

Comprehensive property management for vacation rentals (VR) and long-term rentals (LTR).

GET /api/properties Auth Required Paginated

List all properties with advanced filtering

Query Parameters
Parameter Type Required Description
type string Optional Filter by type (vacation_rental, long_term_rental)
status string Optional Filter by status (active, inactive, maintenance)
location string Optional Filter by city or region
min_price number Optional Minimum nightly/monthly rate
max_price number Optional Maximum nightly/monthly rate
bedrooms integer Optional Number of bedrooms
amenities string Optional Comma-separated amenities (pool,wifi,parking)
available_from date Optional Available from date (YYYY-MM-DD)
available_to date Optional Available to date (YYYY-MM-DD)
Response Schema
{ "success": true, "data": [ { "id": "prop_123", "name": "Ocean View Villa", "type": "vacation_rental", "status": "active", "address": { "street": "123 Beach Road", "city": "Miami Beach", "state": "FL", "zip": "33139", "country": "US", "coordinates": { "lat": 25.7617, "lng": -80.1918 } }, "details": { "bedrooms": 3, "bathrooms": 2.5, "max_guests": 6, "square_feet": 1800, "year_built": 2018, "property_type": "villa" }, "amenities": [ "pool", "wifi", "air_conditioning", "beach_access", "parking", "kitchen", "washer_dryer" ], "pricing": { "base_price": 250.00, "currency": "USD", "pricing_model": "per_night", "cleaning_fee": 150.00, "security_deposit": 500.00, "extra_guest_fee": 25.00, "weekend_rate": 300.00, "monthly_discount": 0.15, "weekly_discount": 0.10 }, "availability": { "minimum_stay": 2, "maximum_stay": 30, "advance_booking": 365, "instant_booking": true, "check_in_time": "15:00", "check_out_time": "11:00" }, "images": [ { "url": "https://cdn.staysuite.com/properties/prop_123/main.jpg", "caption": "Front view", "order": 1 } ], "rules": { "smoking": false, "pets": true, "events": false, "quiet_hours": "22:00-08:00", "max_pets": 2, "pet_fee": 50.00 }, "channels": [ { "platform": "airbnb", "listing_id": "airbnb_456", "sync_enabled": true }, { "platform": "vrbo", "listing_id": "vrbo_789", "sync_enabled": true } ], "stats": { "occupancy_rate": 0.78, "average_rating": 4.8, "total_reviews": 124, "revenue_ytd": 45000.00, "bookings_ytd": 156 }, "created_at": "2024-01-15T10:00:00Z", "updated_at": "2025-01-17T08:30:00Z" } ], "pagination": { "page": 1, "limit": 20, "total_items": 85, "total_pages": 5 } }
GET /api/properties/{id} Auth Required

Get detailed information about a specific property

POST /api/properties Auth Required

Create a new property listing

PUT /api/properties/{id} Auth Required

Update property details

DELETE /api/properties/{id} Auth Required

Remove a property from the system

GET /api/properties/{id}/availability Auth Required

Get property availability calendar

PATCH /api/properties/{id}/availability Auth Required

Update property availability

POST /api/properties/{id}/images Auth Required

Upload property images

Bookings API

Complete booking management system with real-time availability checking and modification capabilities.

GET /api/bookings Auth Required Paginated

List all bookings with comprehensive filtering

Query Parameters
Parameter Type Required Description
property_id string Optional Filter by property ID
guest_id string Optional Filter by guest ID
status string Optional Filter by status (pending, confirmed, cancelled, completed)
check_in_from date Optional Check-in date from (YYYY-MM-DD)
check_in_to date Optional Check-in date to (YYYY-MM-DD)
channel string Optional Booking source (direct, airbnb, booking, vrbo)
Response Schema
{ "success": true, "data": [ { "id": "book_789", "confirmation_code": "STY-2025-0789", "property": { "id": "prop_123", "name": "Ocean View Villa", "type": "vacation_rental" }, "guest": { "id": "guest_456", "name": "Jane Smith", "email": "[email protected]", "phone": "+1-555-0200" }, "dates": { "check_in": "2025-02-15", "check_out": "2025-02-20", "nights": 5, "check_in_time": "15:00", "check_out_time": "11:00" }, "guests": { "adults": 4, "children": 2, "infants": 0, "pets": 1 }, "pricing": { "nightly_rate": 250.00, "subtotal": 1250.00, "cleaning_fee": 150.00, "pet_fee": 50.00, "service_fee": 125.00, "taxes": 157.50, "total": 1732.50, "currency": "USD", "payment_schedule": [ { "amount": 866.25, "due_date": "2025-01-15", "status": "paid" }, { "amount": 866.25, "due_date": "2025-02-01", "status": "pending" } ] }, "status": "confirmed", "channel": "direct", "channel_reference": null, "special_requests": "Late check-in requested (8 PM)", "internal_notes": "VIP guest - returning customer", "agreements": { "rental_agreement": true, "house_rules": true, "damage_waiver": false }, "access_code": "4567", "created_at": "2025-01-10T14:30:00Z", "updated_at": "2025-01-10T14:35:00Z", "cancelled_at": null, "cancellation_policy": "moderate", "commission": { "amount": 0.00, "percentage": 0.00 } } ], "pagination": { "page": 1, "limit": 20, "total_items": 234, "total_pages": 12 } }
GET /api/bookings/{id} Auth Required

Get detailed booking information

POST /api/bookings Auth Required

Create a new booking

Request Body
Parameter Type Required Description
property_id string Required Property ID to book
guest_id string Required Guest ID (or create new guest)
check_in date Required Check-in date (YYYY-MM-DD)
check_out date Required Check-out date (YYYY-MM-DD)
adults integer Required Number of adult guests
children integer Optional Number of children
channel string Optional Booking channel source
PATCH /api/bookings/{id} Auth Required

Modify booking dates or details

POST /api/bookings/{id}/cancel Auth Required

Cancel a booking

POST /api/bookings/{id}/confirm Auth Required

Confirm a pending booking

POST /api/bookings/{id}/check-in Auth Required

Mark guest as checked in

POST /api/bookings/{id}/check-out Auth Required

Mark guest as checked out

Guests API

Manage guest profiles, preferences, communication history, and loyalty programs.

GET /api/guests Auth Required Paginated

List all guests with search and filtering

Response Schema
{ "success": true, "data": [ { "id": "guest_456", "name": "Jane Smith", "email": "[email protected]", "phone": "+1-555-0200", "profile": { "date_of_birth": "1985-06-15", "nationality": "US", "language": "en", "id_type": "passport", "id_number": "***4567", "id_expiry": "2030-05-20" }, "address": { "street": "456 Oak Avenue", "city": "New York", "state": "NY", "zip": "10001", "country": "US" }, "preferences": { "room_type": "ocean_view", "bed_type": "king", "pillow_type": "firm", "dietary": ["vegetarian"], "allergies": ["peanuts"], "special_requests": "High floor preferred" }, "loyalty": { "tier": "gold", "points": 12500, "lifetime_value": 25000.00, "member_since": "2022-03-15" }, "stats": { "total_bookings": 8, "total_nights": 42, "average_stay": 5.25, "total_spent": 8750.00, "last_stay": "2024-12-20" }, "tags": ["vip", "repeat_guest", "early_booker"], "notes": [ { "text": "Prefers email communication", "created_by": "user_123", "created_at": "2024-08-10T10:00:00Z" } ], "blacklisted": false, "created_at": "2022-03-15T14:00:00Z", "updated_at": "2025-01-10T09:30:00Z" } ] }
POST /api/guests/{id}/messages Auth Required

Send a message to a guest

GET /api/guests/{id}/bookings Auth Required

Get all bookings for a specific guest

POST /api/guests/{id}/documents Auth Required

Upload guest verification documents

Payments API

Process payments, refunds, and manage financial transactions.

GET /api/payments Auth Required Paginated

List all payment transactions

POST /api/payments/charge Auth Required

Process a payment charge

Request Body
Parameter Type Required Description
booking_id string Required Associated booking ID
amount number Required Amount to charge
currency string Required Currency code (USD, EUR, etc.)
payment_method string Required Payment method (card, bank_transfer, paypal)
payment_token string Required Payment token or method ID
Response
{ "success": true, "data": { "id": "pay_abc123", "booking_id": "book_789", "amount": 866.25, "currency": "USD", "status": "succeeded", "payment_method": "card", "card": { "brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2026 }, "receipt_url": "https://pay.stripe.com/receipts/...", "created_at": "2025-01-17T10:30:00Z" } }
POST /api/payments/{id}/refund Auth Required

Issue a refund for a payment

GET /api/payments/methods Auth Required

List saved payment methods for a guest

Accounting API

Comprehensive financial management including ledgers, invoices, and reporting.

GET /api/accounting/transactions Auth Required Paginated

List all accounting transactions

POST /api/accounting/journal-entries Auth Required

Create a journal entry

GET /api/accounting/invoices Auth Required Paginated

List all invoices

POST /api/accounting/invoices Auth Required

Create a new invoice

GET /api/accounting/reports/pnl Auth Required

Generate Profit & Loss report

GET /api/accounting/reports/balance-sheet Auth Required

Generate Balance Sheet report

GET /api/accounting/tax-documents Auth Required

Generate tax documents (1099-K, Schedule E)

Housekeeping API

Manage cleaning schedules, tasks, and team assignments.

GET /api/housekeeping/tasks Auth Required Paginated

List all housekeeping tasks

Response Schema
{ "success": true, "data": [ { "id": "task_123", "property_id": "prop_123", "property_name": "Ocean View Villa", "type": "checkout_cleaning", "status": "in_progress", "priority": "high", "scheduled_date": "2025-01-17", "scheduled_time": "10:00", "estimated_duration": 120, "assigned_to": { "id": "cleaner_456", "name": "Maria's Cleaning Team", "phone": "+1-555-0300" }, "checklist": [ { "item": "Kitchen cleaning", "completed": true }, { "item": "Bathroom sanitization", "completed": true }, { "item": "Bedroom linens", "completed": false } ], "supplies_needed": [ "Fresh linens set", "Cleaning supplies", "Welcome amenities" ], "notes": "Guest arriving at 3 PM - priority cleaning", "completion_time": null, "quality_score": null, "photos": [] } ] }
POST /api/housekeeping/tasks Auth Required

Create a new housekeeping task

PATCH /api/housekeeping/tasks/{id}/complete Auth Required

Mark a task as completed

GET /api/housekeeping/schedule Auth Required

Get housekeeping calendar schedule

Maintenance API

Track and manage property maintenance, repairs, and preventive tasks.

GET /api/maintenance/requests Auth Required Paginated

List all maintenance requests

POST /api/maintenance/requests Auth Required

Create a maintenance request

Request Body
Parameter Type Required Description
property_id string Required Property requiring maintenance
category string Required Category (plumbing, electrical, hvac, appliance, other)
priority string Required Priority level (emergency, high, medium, low)
description string Required Detailed description of the issue
photos array Optional Array of photo URLs
GET /api/maintenance/preventive Auth Required

Get preventive maintenance schedule

GET /api/maintenance/vendors Auth Required

List approved maintenance vendors

Channel Management API

Manage distribution channels and synchronize listings across platforms.

GET /api/channels Auth Required

List all connected channels

POST /api/channels/connect Auth Required

Connect a new distribution channel

POST /api/channels/{channel}/sync Auth Required

Sync property data with a channel

POST /api/channels/{channel}/import Auth Required

Import bookings from a channel

Analytics API

Access comprehensive analytics and reporting for business intelligence.

GET /api/analytics/dashboard Auth Required

Get dashboard metrics and KPIs

Response Schema
{ "success": true, "data": { "period": { "start": "2025-01-01", "end": "2025-01-31" }, "revenue": { "total": 125000.00, "growth": 0.15, "adr": 275.00, "revpar": 215.00 }, "occupancy": { "rate": 0.78, "nights_booked": 483, "nights_available": 620 }, "bookings": { "total": 87, "new": 65, "repeat": 22, "average_los": 5.5 }, "channels": { "direct": 0.35, "airbnb": 0.40, "booking": 0.15, "vrbo": 0.10 }, "top_properties": [ { "id": "prop_123", "name": "Ocean View Villa", "revenue": 18500.00, "occupancy": 0.85 } ] } }
GET /api/analytics/revenue Auth Required

Get detailed revenue analytics

GET /api/analytics/occupancy Auth Required

Get occupancy trends and forecasts

GET /api/analytics/market Auth Required

Get market comparison data

Webhooks API

Configure and manage webhook subscriptions for real-time event notifications.

GET /api/webhooks Auth Required

List all webhook subscriptions

POST /api/webhooks Auth Required

Create a webhook subscription

Request Body
Parameter Type Required Description
url string Required Webhook endpoint URL (HTTPS required)
events array Required Array of event types to subscribe to
secret string Optional Secret for signature verification
active boolean Optional Whether webhook is active (default: true)
📡 Available Webhook Events
  • booking.* - All booking events
  • property.* - Property updates
  • payment.* - Payment transactions
  • guest.* - Guest profile changes
  • review.* - New reviews
  • maintenance.* - Maintenance requests
  • housekeeping.* - Cleaning task updates

Workflows API

Automate business processes with customizable workflows and triggers.

GET /api/workflows Auth Required

List all automation workflows

POST /api/workflows Auth Required

Create a new automation workflow

POST /api/workflows/{id}/trigger Auth Required

Manually trigger a workflow

GET /api/workflows/{id}/history Auth Required

Get workflow execution history

Documents API

Manage contracts, agreements, and document generation.

POST /api/documents/generate Auth Required

Generate a document from template

Request Body
Parameter Type Required Description
template string Required Template type (rental_agreement, invoice, receipt)
booking_id string Required Associated booking ID
format string Optional Output format (pdf, html) - default: pdf
GET /api/documents/{id} Auth Required

Download a generated document

POST /api/documents/{id}/send Auth Required

Send document via email

Data Schemas

Detailed schema definitions for all API resources.

Common Schemas

Address Schema

street string
Street address
city string
City name
state string
State or province code
zip string
Postal/ZIP code
country string
ISO country code
coordinates object
GPS coordinates (lat, lng)

Money Schema

amount number
Monetary amount
currency string
ISO 4217 currency code

Pagination Schema

page integer
Current page number
limit integer
Items per page
total_items integer
Total number of items
total_pages integer
Total number of pages
has_next boolean
Whether there is a next page
has_prev boolean
Whether there is a previous page

Error Codes Reference

Complete list of error codes and their meanings.

Error Code HTTP Status Description
AUTHENTICATION_ERROR 401 Invalid or expired authentication credentials
PERMISSION_DENIED 403 User doesn't have permission to perform this action
RESOURCE_NOT_FOUND 404 The requested resource doesn't exist
VALIDATION_ERROR 422 Request validation failed
DUPLICATE_RESOURCE 409 Resource already exists
BOOKING_CONFLICT 409 Dates are not available for booking
RATE_LIMIT_EXCEEDED 429 Too many requests - rate limit exceeded
PAYMENT_FAILED 402 Payment processing failed
INVALID_STATE 400 Operation not allowed in current state
EXTERNAL_SERVICE_ERROR 502 External service (Stripe, etc.) error
INTERNAL_ERROR 500 Internal server error occurred
SERVICE_UNAVAILABLE 503 Service temporarily unavailable

Error Response Format

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": [ { "field": "check_in", "message": "Check-in date must be in the future", "value": "2024-12-01" }, { "field": "guests", "message": "Number of guests exceeds property maximum", "value": 8, "max": 6 } ], "request_id": "req_abc123xyz", "documentation_url": "https://docs.staysuite.com/errors/validation_error" }, "meta": { "timestamp": "2025-01-17T10:30:00Z" } }

Download Complete API Reference

Get the full StaySuite API Reference documentation as a PDF for offline access