Quick start guide

Overview

The Booking Engine API allows external platforms to:

• Search available properties

• Retrieve pricing and calendar data

• Create bookings

Key components

• Base URL: https://booking-api.guesty.com/v1

• Format: JSON over HTTPS

• Authentication: OAuth2 access token (included in header)

Prerequisites

• A Guesty account with Booking Engine enabled (see Step 1 in the next section below)
• An API key (provided in the Guesty dashboard - see Step 2 in the next section below)
• Familiarity with HTTP requests and JSON responses
• A tool for testing requests (Postman, curl, or browser)

Activating the Booking Engine

Step 1: Create a booking Engine API instance

To begin using the Booking Engine API, you need to create an API instance and retrieve your credentials (Client ID and Client Secret). Take care to ensure that you select the booking option (Only request to book, Only instant booking, or Both request to book and instant book) that aligns with your intended booking flow. For example, if you select Only Inquiries, you will only be able to create booking requests ("status": "reserved").

📖 For detailed instructions, refer to this Guesty Help Center article.

Step 2: Get your access token

Note: Guesty enforces the following access token limitations:

• Tokens expire after 24 hours.
• Each application requires its own token.
• You can create up to 5 applications per Guesty account.
• The token can be renewed up to 3 times within a 24-hour period.

To avoid interruptions, store and reuse tokens until they expire.

To interact with the Booking Engine API, you'll need to authenticate using OAuth2 to obtain an access token. Here's how to request a token using your client credentials:

Request

curl --location --request POST 'https://booking.guesty.com/oauth2/token' \
--header 'accept: application/json' \
--header 'cache-control: no-cache,no-cache' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=booking_engine:api' \
--data-urlencode 'client_secret={application client SECRET}' \
--data-urlencode 'client_id={application client ID}'

const axios = require('axios');

async function getAccessToken() {
  const params = new URLSearchParams();
  params.append('grant_type', 'client_credentials');
  params.append('scope', 'booking_engine:api');
  params.append('client_id', 'YOUR_CLIENT_ID');
  params.append('client_secret', 'YOUR_CLIENT_SECRET');

  const response = await axios.post('https://booking.guesty.com/oauth2/token', params, {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    }
  });

  console.log(response.data.access_token);
}

import requests

payload = {
    'grant_type': 'client_credentials',
    'scope': 'booking_engine:api',
    'client_id': 'YOUR_CLIENT_ID',
    'client_secret': 'YOUR_CLIENT_SECRET'
}

response = requests.post('https://booking.guesty.com/oauth2/token', data=payload)
print(response.json()['access_token'])

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://booking.guesty.com/oauth2/token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'accept: application/json',
    'cache-control: no-cache,no-cache',
    'content-type: application/x-www-form-urlencoded'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'grant_type' => 'client_credentials',
    'scope' => 'booking_engine:api',
    'client_id' => 'YOUR_CLIENT_ID',
    'client_secret' => 'YOUR_CLIENT_SECRET'
]));

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

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

Response

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

Use the access_token in the Authorization header of all subsequent API requests:

--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Step 3: Test your access token with a listings search

Request:

curl --location GET 'https://booking-api.guesty.com/v1/search
accept: application/json' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Optional query parameters include:

• checkIn, checkOut (YYYY-MM-DD)
• guests, adults, children
• location

Example:

curl --location --request GET 'https://booking-api.guesty.com/v1/search?checkIn=2025-07-01&checkOut=2025-07-05&adults=2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Step 4: Activate the booking flow

Before using the Booking Engine (BE) API reservation endpoints, ensure it is properly activated by following these steps:

1. Activate the manual source: Create a direct booking from your Guesty dashboard to activate the manual booking source in your account.
2. Activate the Booking Engine API source: Create your first reservation using the BE API Reservation quote endpoints. This step is essential to initialize the Booking Engine API source, which enables it as an automation option for additional fees, taxes, payment automations, and automated messages.

If you encounter any issues, feel free to contact us for assistance.

Rate limits

Guesty enforces the following rate limits on the Booking Engine API:

• 5 requests per second
• 275 requests per minute
• 16,500 requests per hour

Guesty uses a gradual refill method to restore your request capacity over time, rather than resetting it all at once. This means you should avoid burst traffic and allow time for capacity to replenish between requests.

Best practices

• Always include the Authorization header
• Validate inputs before sending requests
• Handle 4xx and 5xx responses gracefully
• Display accurate availability and pricing by using real-time API data

⚠️

Note:

Guesty recommends using the Reservation Quote Flow for all booking operations. The older Reservations V1 endpoint is being deprecated and should not be used in new implementations.

Resources

• Booking Engine API Documentation
• Listings Search Endpoint
• Create Booking Endpoint
• Response Codes
• Errors
• Definitions
• Enums

Troubleshooting authentication issues

If you encounter authentication issues with the Booking Engine API, here are some common causes and tips:

Common issues

Getting help

If issues persist, contact Guesty support.

Next steps

• Explore the Booking Engine API Documentation
• Review available filters and sort options for search
• Read through the Booking Engine API Guides for implementation tips
• Implement error-handling and availability fallback logic