StaySuite API Quick Start Guide

Welcome to StaySuite API

The StaySuite API provides programmatic access to our comprehensive property management platform. Whether you're managing vacation rentals, long-term properties, or building custom integrations, our RESTful API offers the flexibility and power you need.

🔐 Secure Authentication

JWT-based auth with 2FA support and role-based access control

🏠 Property Management

Complete CRUD operations for VR and LTR properties

📅 Booking System

Real-time availability, pricing, and reservation management

💳 Payment Processing

Integrated payment handling with Stripe and PayPal

Getting Started in 5 Minutes

1Get Your API Credentials

Log in to your StaySuite dashboard and navigate to Settings > API Keys to generate your credentials.

2Set Up Authentication

Use your client ID and secret to obtain an access token via our OAuth 2.0 endpoint.

3Make Your First API Call

Test your connection by fetching your user profile or property list.

Authentication

OAuth 2.0 Flow

StaySuite uses OAuth 2.0 for secure API authentication. Follow these steps to authenticate:

1. Request an Access Token

POST/api/auth/token

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials",
  "scope": "read write"
}

2. Receive Token Response

{
  "access_token": "",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "",
  "scope": "read write"
}

3. Include Token in Requests

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

⚠️ Security Best Practices

Never expose your client secret in client-side code
Use environment variables to store credentials
Implement token refresh before expiration
Enable 2FA for production environments

Quick Examples

Fetch All Properties

// Using fetch API
const getProperties = async () => {
  const response = await fetch('https://api.staysuite.com/api/properties', {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  console.log('Properties:', data);
};

// Using axios
const axios = require('axios');

const properties = await axios.get('https://api.staysuite.com/api/properties', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

Create a New Booking

const createBooking = async (bookingData) => {
  const response = await fetch('https://api.staysuite.com/api/bookings', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      property_id: 'prop_123',
      guest_id: 'guest_456',
      check_in: '2025-02-01',
      check_out: '2025-02-07',
      total_amount: 1500.00,
      status: 'confirmed'
    })
  });

  const booking = await response.json();
  console.log('Booking created:', booking);
};

Update Property Availability

const updateAvailability = async (propertyId, dates) => {
  const response = await fetch(`https://api.staysuite.com/api/properties/${propertyId}/availability`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      blocked_dates: dates,
      reason: 'maintenance'
    })
  });

  return await response.json();
};

Fetch All Properties

import requests

# Get properties
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.staysuite.com/api/properties', headers=headers)
properties = response.json()

for property in properties['data']:
    print(f"Property: {property['name']} - {property['type']}")

Create a New Booking

import requests
from datetime import datetime

booking_data = {
    'property_id': 'prop_123',
    'guest_id': 'guest_456',
    'check_in': '2025-02-01',
    'check_out': '2025-02-07',
    'total_amount': 1500.00,
    'status': 'confirmed'
}

response = requests.post(
    'https://api.staysuite.com/api/bookings',
    json=booking_data,
    headers=headers
)

if response.status_code == 201:
    booking = response.json()
    print(f"Booking created: {booking['id']}")

Fetch All Properties

# Get all properties
curl -X GET https://api.staysuite.com/api/properties \
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Create a New Booking

# Create a booking
curl -X POST https://api.staysuite.com/api/bookings \
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "property_id": "prop_123",
    "guest_id": "guest_456",
    "check_in": "2025-02-01",
    "check_out": "2025-02-07",
    "total_amount": 1500.00,
    "status": "confirmed"
  }'

Fetch All Properties

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.staysuite.com/api/properties",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $access_token,
        "Content-Type: application/json"
    ],
]);

$response = curl_exec($curl);
$properties = json_decode($response, true);

foreach ($properties['data'] as $property) {
    echo "Property: " . $property['name'] . "\n";
}

curl_close($curl);
?>

Core Resources

Properties

Manage both vacation rental (VR) and long-term rental (LTR) properties.

GET/api/properties

List all properties with pagination and filtering

POST/api/properties

Create a new property listing

PUT/api/properties/{id}

Update property details

DELETE/api/properties/{id}

Remove a property from the system

Bookings

Handle reservations, availability, and booking modifications.

GET/api/bookings

Retrieve bookings with filters for date range, property, or status

POST/api/bookings

Create a new reservation

PATCH/api/bookings/{id}/status

Update booking status (confirm, cancel, modify)

Guests

Manage guest profiles, preferences, and communication.

GET/api/guests

List all guests with search capabilities

POST/api/guests/{id}/messages

Send automated or manual messages to guests

Request & Response Format

Standard Request Headers

Header	Value	Required	Description
Authorization	Bearer {token}	Yes	Your API access token
Content-Type	application/json	Yes	Request body format
X-Tenant-ID	{tenant_id}	For multi-tenant	Specify tenant context
X-Request-ID	{uuid}	No	Track requests for debugging

Successful Response (200 OK)

{
  "success": true,
  "data": {
    "id": "prop_123",
    "name": "Ocean View Villa",
    "type": "vacation_rental",
    "bedrooms": 3,
    "bathrooms": 2,
    "max_guests": 6,
    "base_price": 250.00
  },
  "meta": {
    "timestamp": "2025-01-17T10:30:00Z",
    "version": "1.0"
  }
}

Error Response (400 Bad Request)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "check_in",
        "message": "Check-in date must be in the future"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-17T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Pagination & Filtering

Pagination Parameters

All list endpoints support pagination to handle large datasets efficiently.

Parameter	Type	Default	Description
page	integer	1	Page number to retrieve
limit	integer	20	Items per page (max: 100)
sort	string	created_at	Field to sort by
order	string	desc	Sort order (asc/desc)

Example: Paginated Request

GET /api/properties?page=2&limit=50&sort=base_price&order=asc

Paginated Response

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total_items": 245,
    "total_pages": 5,
    "has_next": true,
    "has_prev": true
  },
  "links": {
    "self": "/api/properties?page=2&limit=50",
    "first": "/api/properties?page=1&limit=50",
    "prev": "/api/properties?page=1&limit=50",
    "next": "/api/properties?page=3&limit=50",
    "last": "/api/properties?page=5&limit=50"
  }
}

Filtering

Use query parameters to filter results based on specific criteria.

// Filter properties by type and amenities
GET /api/properties?type=vacation_rental&amenities=pool,wifi&min_price=100&max_price=500

// Filter bookings by date range
GET /api/bookings?check_in_after=2025-02-01&check_in_before=2025-02-28&status=confirmed

// Search guests by name or email
GET /api/guests?search=john&include=bookings,reviews

Webhooks

StaySuite supports webhooks for real-time event notifications. Configure webhook endpoints in your dashboard to receive instant updates.

Available Events

booking.created

New reservation received

booking.updated

Booking modified or status changed

booking.cancelled

Reservation cancelled

payment.received

Payment successfully processed

property.updated

Property details or availability changed

review.submitted

New guest review received

Webhook Payload Example

{
  "event": "booking.created",
  "timestamp": "2025-01-17T10:30:00Z",
  "data": {
    "booking_id": "book_789",
    "property_id": "prop_123",
    "guest_id": "guest_456",
    "check_in": "2025-02-15",
    "check_out": "2025-02-20",
    "total_amount": 1250.00,
    "status": "pending"
  },
  "signature": "sha256=7d38cdd689..."
}

Verifying Webhook Signatures

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return `sha256=${hash}` === signature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-staysuite-signature'];

  if (verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
    // Process the webhook
    handleWebhookEvent(req.body);
    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

Rate Limiting

To ensure fair usage and system stability, the StaySuite API implements rate limiting.

Rate Limit Headers

Header	Description	Example
X-RateLimit-Limit	Maximum requests per hour	1000
X-RateLimit-Remaining	Requests remaining in current window	950
X-RateLimit-Reset	Unix timestamp when limit resets	1705491600
Retry-After	Seconds to wait before retrying (429 only)	3600

Rate Limit Tiers

📊 API Rate Limits by Plan

Starter: 1,000 requests/hour
Professional: 5,000 requests/hour
Business: 10,000 requests/hour
Enterprise: Custom limits available

Handling Rate Limit Errors

// Exponential backoff retry strategy
async function makeAPIRequest(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      return response;
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

Error Handling

HTTP Status Codes

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Request successful, no content to return
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Access denied to resource
404	Not Found	Resource not found
409	Conflict	Resource conflict (e.g., duplicate booking)
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred
503	Service Unavailable	Service temporarily unavailable

Error Codes

// Common error codes and their meanings
{
  "VALIDATION_ERROR": "Request validation failed",
  "AUTHENTICATION_ERROR": "Authentication failed or expired",
  "PERMISSION_DENIED": "Insufficient permissions",
  "RESOURCE_NOT_FOUND": "Requested resource does not exist",
  "DUPLICATE_RESOURCE": "Resource already exists",
  "RATE_LIMIT_EXCEEDED": "Too many requests",
  "PAYMENT_FAILED": "Payment processing failed",
  "BOOKING_CONFLICT": "Dates unavailable for booking",
  "INVALID_STATE": "Operation not allowed in current state",
  "EXTERNAL_SERVICE_ERROR": "Third-party service error"
}

SDKs & Libraries

Speed up your integration with our official SDKs and community-maintained libraries.

Official SDKs

JavaScript/TypeScript

npm install @staysuite/sdk

Python

pip install staysuite

PHP

composer require staysuite/sdk

Ruby

gem install staysuite

SDK Usage Example

// JavaScript SDK
import { StaySuite } from '@staysuite/sdk';

const client = new StaySuite({
  apiKey: process.env.STAYSUITE_API_KEY,
  environment: 'production'
});

// Async/await syntax
const properties = await client.properties.list({
  type: 'vacation_rental',
  limit: 50
});

// Promise syntax
client.bookings.create({
  property_id: 'prop_123',
  check_in: '2025-03-01',
  check_out: '2025-03-07'
}).then(booking => {
  console.log('Booking created:', booking.id);
}).catch(error => {
  console.error('Error:', error.message);
});

Testing & Development

Sandbox Environment

Test your integration without affecting production data using our sandbox environment.

🧪 Sandbox Access

Base URL: https://sandbox.api.staysuite.com

Test Credentials: Available in your dashboard under Development > Sandbox

All sandbox data resets daily at midnight UTC

Test Credit Cards

Card Number	Type	Result
4242 4242 4242 4242	Visa	Success
4000 0000 0000 0002	Visa	Declined
4000 0000 0000 9995	Visa	Insufficient funds
5555 5555 5555 4444	Mastercard	Success

Postman Collection

Import our Postman collection for quick API testing:

https://www.getpostman.com/collections/staysuite-api-v1

API Explorer

Test API endpoints directly in your browser using our interactive API Explorer:

🚀 Try It Now

Visit developer.staysuite.com/explorer to test endpoints with your sandbox credentials.

Best Practices

Security

✅ Always use HTTPS for API requests
✅ Store API keys securely (environment variables, key management services)
✅ Implement proper error handling and logging
✅ Validate webhook signatures before processing
✅ Use least-privilege principle for API key permissions
✅ Rotate API keys regularly
✅ Implement request signing for sensitive operations

Performance

🚀 Use pagination for large data sets
🚀 Implement caching where appropriate
🚀 Batch requests when possible
🚀 Use webhooks instead of polling
🚀 Compress request/response payloads with gzip
🚀 Include only necessary fields with sparse fieldsets
🚀 Implement exponential backoff for retries

Data Management

📊 Use idempotency keys for critical operations
📊 Implement proper data validation before API calls
📊 Handle timezone conversions consistently
📊 Store references to API resources, not full objects
📊 Use ETags for conditional requests
📊 Implement proper data synchronization strategies

Common Integration Patterns

Channel Manager Integration

// Sync availability across multiple channels
async function syncAvailability(propertyId) {
  // Get current availability from StaySuite
  const availability = await client.properties.getAvailability(propertyId);

  // Update external channels
  const channels = ['airbnb', 'booking', 'vrbo'];

  for (const channel of channels) {
    await updateChannelAvailability(channel, {
      propertyId,
      calendar: availability.calendar,
      rates: availability.rates
    });
  }

  // Set up webhook for real-time updates
  await client.webhooks.subscribe({
    url: 'https://your-app.com/webhooks/availability',
    events: ['availability.updated'],
    property_id: propertyId
  });
}

Dynamic Pricing Integration

// Implement dynamic pricing based on demand
async function updateDynamicPricing(propertyId) {
  // Get historical booking data
  const bookingData = await client.analytics.getBookingTrends({
    property_id: propertyId,
    period: 'last_90_days'
  });

  // Get competitor rates
  const marketData = await client.market.getCompetitorRates({
    location: property.location,
    property_type: property.type
  });

  // Calculate optimal pricing
  const pricing = calculateOptimalPricing({
    basePrice: property.base_price,
    demand: bookingData.occupancy_rate,
    seasonality: bookingData.seasonal_factors,
    competition: marketData.average_rate
  });

  // Update rates in StaySuite
  await client.properties.updateRates(propertyId, {
    rates: pricing.rates,
    minimum_stay: pricing.minimum_stay,
    effective_date: '2025-02-01'
  });
}

Guest Communication Automation

// Automate guest communication workflow
async function setupGuestAutomation(bookingId) {
  const booking = await client.bookings.get(bookingId);

  // Schedule pre-arrival message
  await client.messages.schedule({
    recipient: booking.guest_id,
    template: 'pre_arrival_instructions',
    send_at: new Date(booking.check_in).setDate(-1),
    variables: {
      guest_name: booking.guest.name,
      property_name: booking.property.name,
      check_in_time: booking.check_in_time,
      door_code: booking.access_code
    }
  });

  // Schedule check-in day message
  await client.messages.schedule({
    recipient: booking.guest_id,
    template: 'welcome_message',
    send_at: booking.check_in,
    variables: {
      wifi_password: booking.property.wifi_password,
      emergency_contact: booking.property.emergency_contact
    }
  });

  // Schedule post-checkout review request
  await client.messages.schedule({
    recipient: booking.guest_id,
    template: 'review_request',
    send_at: new Date(booking.check_out).setDate(1)
  });
}

Support & Resources

📚 API Reference

Complete endpoint documentation with request/response examples

View API Reference →

💬 Developer Community

Join our Slack community for discussions and support

Join Slack →

🎓 Video Tutorials

Step-by-step video guides for common integrations

Watch Tutorials →

🔧 System Status

Real-time API status and incident reports

Check Status →

💡 Need Help?

Email: [email protected]

Documentation: docs.staysuite.com

Support Hours: Monday-Friday, 9 AM - 6 PM EST

Emergency: For critical production issues, use priority support in your dashboard

Next Steps

1Explore the API Reference

Deep dive into all available endpoints, parameters, and response formats in our comprehensive API Reference.

2Join the Developer Community

Connect with other developers, share integrations, and get help from the StaySuite team.

3Build Your Integration

Start building with our SDKs and test thoroughly in the sandbox environment before going live.

4Get Certified

Complete our developer certification to get listed in our integration marketplace and access premium support.