Quick start guide

❗️

Partners & Channels (OTAs)

If you are a Guesty Marketplace or Channel (OTA) Partner, please refrain from using the Open API and contact [email protected].

Overview

The Open API exposes a RESTful interface to access and manage your Guesty account data. This includes listings, reservations, guests, and more.

• Base URL: https://open-api.guesty.com/v1
• Format: JSON over HTTPS
• Authentication: Bearer token (OAuth2)

Prerequisites

• A Guesty account with API access enabled
• Admin permissions on your Guesty account
• Basic knowledge of HTTP and JSON
• A tool for making HTTP requests (e.g., Postman, curl, or custom code)

Step 1: Obtain API Credentials

To get started, you'll need a Client ID and Client Secret:

1. Log in to your Guesty dashboard.
2. Navigate to Integrations > API & Webhooks.
3. Create a new API application.
4. Copy your Client ID and Client Secret.

Step 2: Authenticate and Get an Access Token

Note: Guesty allows up to five access tokens per API key within a 24-hour period. Each token remains valid for 24 hours. To avoid disruptions, you should store and reuse the issued token until it expires or is invalidated. Refresh the token only when the previous one has expired or is invalidated.

Recommended Strategy:

• Store the token securely in memory, a database, or a cache.
• Track the token's expiration timestamp.
• Automatically request a new token when it's close to expiry (e.g., within 5 minutes).
• Avoid requesting a new token on every API call to stay within the usage limit.

Token storage example

let tokenCache = {
  token: null,
  expiresAt: null
};

async function getToken() {
  const now = Date.now();
  if (tokenCache.token && tokenCache.expiresAt > now) {
    return tokenCache.token;
  }

  const response = await fetch('https://open-api.guesty.com/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: 'YOUR_CLIENT_ID',
      clientSecret: 'YOUR_CLIENT_SECRET'
    })
  });

  const data = await response.json();
  tokenCache.token = data.access_token;
  tokenCache.expiresAt = now + 24 * 60 * 60 * 1000; // 24 hours
  return tokenCache.token;
}

import time
import requests

token_cache = {
    'token': None,
    'expires_at': 0
}

def get_token():
    now = time.time()
    if token_cache['token'] and token_cache['expires_at'] > now:
        return token_cache['token']

    response = requests.post('https://open-api.guesty.com/oauth2/token', json={
        'clientId': 'YOUR_CLIENT_ID',
        'clientSecret': 'YOUR_CLIENT_SECRET'
    })
    data = response.json()
    token_cache['token'] = data['access_token']
    token_cache['expires_at'] = now + 86400  # 24 hours in seconds
    return token_cache['token']

class TokenCache {
    private static $token = null;
    private static $expiresAt = 0;

    public static function getToken() {
        if (self::$token && self::$expiresAt > time()) {
            return self::$token;
        }

        $payload = json_encode([
            'clientId' => 'YOUR_CLIENT_ID',
            'clientSecret' => 'YOUR_CLIENT_SECRET'
        ]);

        $ch = curl_init('https://open-api.guesty.com/oauth2/token');
        curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json']);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        self::$token = $data['access_token'];
        self::$expiresAt = time() + 86400; // 24 hours
        return self::$token;
    }
}

Use your credentials to obtain a Bearer token:

HTTP Request:

POST https://open-api.guesty.com/oauth2/token
Content-Type: application/json

{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET"
}

Sample Response:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the access_token in the Authorization header of all subsequent requests.

Request token example

const axios = require('axios');

async function getToken() {
  const response = await axios.post('https://open-api.guesty.com/oauth2/token', {
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET'
  });
  console.log(response.data.access_token);
}

getToken();

import requests

response = requests.post(
    'https://open-api.guesty.com/oauth2/token',
    json={
        'clientId': 'YOUR_CLIENT_ID',
        'clientSecret': 'YOUR_CLIENT_SECRET'
    }
)

print(response.json()['access_token'])

curl -X POST https://open-api.guesty.com/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET"}'

<?php
$payload = json_encode([
    'clientId' => 'YOUR_CLIENT_ID',
    'clientSecret' => 'YOUR_CLIENT_SECRET'
]);

$ch = curl_init('https://open-api.guesty.com/oauth2/token');
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['access_token'];

Step 3: Make Your First API Call

🚧

Permission Error

If you receive the "You don't have permission to access, please contact Guesty support" error message when performing a request, make sure that the authorization header parameter includes "Bearer" before the access token (e.g., "Bearer {token}"). If the problem continues, please reach out to support.

As a simple test, fetch a list of your listings:

Request:

GET https://open-api.guesty.com/v1/listings
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

{
  "results": [
    {
      "id": "1234567890",
      "title": "Modern Loft in Downtown",
      "status": "active"
    },
    ...
  ]
}

Best Practices

• Use pagination: Many endpoints return paginated results. Use limit and skip or cursor query parameters.
• Rate limits: Respect rate limits to avoid throttling.
• Error handling: Handle HTTP status codes and API-specific errors gracefully.

Traffic Management Strategies

To prevent hitting API rate limits, consider implementing the following strategies:

• Exponential backoff: If you receive a 429 (Too Many Requests) response, wait a short time before retrying and progressively increase the wait time on subsequent retries.
• Request batching: Where possible, use endpoints that allow bulk operations instead of many individual requests.
• Prioritize data access: Only request necessary data and use filters to reduce payload size and frequency.
• Caching: Cache results of common requests locally to reduce redundant API calls.
• Rate limit monitoring: Implement logic to detect when you are approaching rate limits based on response headers or behavior and adjust request rates dynamically.

Postman Integration

Guesty provides a ready-to-use Postman collection to simplify exploring the API:

1. Visit the Postman collection
   1. 
2. Fork it to your workspace
3. Set your environment variables (Client ID, Secret, Token)
4. Test endpoints with a click

Explore Key API Areas

Guesty's Open API spans many resources. Here are some useful endpoints:

• Listings: /v1/listings
• Reservations: /v1/reservations
• Guests: /v1/guests
• Tasks: /v1/tasks
• Webhooks: /v1/webhooks

You can find detailed parameters, filters, and responses in the API Reference.

Troubleshooting Authentication Issues

If you encounter issues while authenticating with the Guesty Open API, consider the following common problems and resolutions:

Next Steps

• Read the Authentication guide
• Learn about Webhooks for real-time updates
• Check out other best practices guides
• Explore the API
• Subscribe to the changelogs RSS feed

For further support, contact Guesty or visit the documentation portal.