---
updatedAt: 2026-10-04T10:06:11.000Z
agentTools:
projectIndex: https://booking-api-docs.guesty.com/llms.txt
---
# Quick Start Guide
Guesty's Booking Engine API enables developers to integrate real-time availability, pricing, and booking functionality into external websites and applications. This guide helps you understand the basics and get up and running quickly.
## 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/api`
* **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.
* You can renew the token up to 5 times within a 24-hour period.
To avoid interruptions, store and reuse tokens until they expire.
To maintain uninterrupted access and avoid exceeding token issuance limits, consider the following token management strategy:
- Store the token securely using environment-specific strategies:
- For backend services, use in-memory caching or encrypted secure files.
- If writing to disk, encrypt the file using a secure method and restrict file permissions.
- Avoid committing tokens to source control.
- Never store tokens in frontend or client-side code.
- Track its expiration time using the `expires_in` field from the token response (usually 86400 seconds).
- Reuse the stored token for all API requests until it is close to expiring.
- Automatically request a new token only when the current one is about to expire (e.g., within the last 5 minutes).
- Avoid requesting a new token on every API call to prevent hitting the renewal limit of 3 tokens per 24 hours per application.
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
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}'
```
```node Node.js (axios)
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);
}
```
```python Python (requests)
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 PHP cURL
'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
```json
{
"access_token": "YOUR_ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 86400
}
```
Use the `access_token` in the `Authorization` header of all subsequent API requests:
```curl
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
```
### Step 3: Test your access token with a listings search
**Request**:
```curl
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
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.
- Distribute traffic evenly across time to avoid bursts.
- Implement exponential backoff with jitter and a maximum cap when you receive HTTP 429 (Too Many Requests) responses.
- Monitor API response headers for rate limit usage if exposed.
## 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
Double-check credentials for typos and correct copying.
Ensure you include Content-Type: application/x-www-form-urlencoded and use accept: application/json.
Tokens expire after 24 hours. Cache and reuse the token as described.
Tokens can only be renewed 3 times in 24 hours. Avoid excessive regeneration.
Include the header Authorization: Bearer YOUR\_ACCESS\_TOKEN in all requests.
### 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