Guides

How to Search for Reservations

Learn how to filter your reservations search to return a curated response.

Suggest Edits

Overview

This document explains adding filters to your reservation search queries to return a curated collection. It outlines the filter structure, its components, how you can stack them, and the importance of including pagination to pull the entire collection when there are more than 25 reservations.


Key Endpoints

MethodEndpoint URL
GET/reservations

Key Parameters

Query ParameterTypeDescription
filters[object]Array of filters to focus the query.
fieldsstringA selection of reservation fields separated by spaces. This permits you to specify only the fields you require in your response.
sortstringFor ordering the response results. To ensure your collection maintains continuity, sort by unique values such as _id, lastUpdatedAt or createdAt.
limitintegerlimit the number of reservation in the response. By default Guesty returns up to 25 reservations, but you can increase this to a maximum of 100.
skipintegerThe number of reservations to skip. Include this to paginate through results greater than 100.

The Anatomy of a Filtered Query

There are four primary parts to your query:

  1. The base endpoint (see the overview above)
  2. Fields
  3. Filters
  4. Pagination

We will focus on parts 2 to 4.


Fields

The server returns several fields by default when fields aren't specified. Only some of them persist when fields are specified. The table below describes the default reservation field and indicates which persists in filtered queries.


Body ParameterTypeDescriptionDefaultPersistent
_idstringGuesty reservation ID.yesyes
integrationobjectContains identifying details about the channel integration (_id and platform).yesyes
integration._idstringThe Guesty integration ID.yesyes
integration.platformstringThe name of the channel.yesYes
limitations[object]Contains any restrictions in effect on the listing.yesyes
accountIdstringYour Guesty account ID.yesyes
guestIdstringThe Guesty primary ID of the guest.yesyes
listingIdstringThe Guesty listing ID the reservation is booked at.yesyes
listingobjectContains the listing _id and title. When a field is specified in the query, it only contains the _id.yesyes
listing._idstringThe Guesty listing ID.yesyes
listing.titlestringThe listing title.yes
checkInstringThe reservation check-in date in ISO date time UTC. YYYY-MM-DDTHh:mm:ss.sssZyes
checkOutstringThe reservation check-out time in ISO date-time format UTC. YYYY-MM-DDTHh:mm:ss.sssZyes
guestobjectThe guest object.yesyes
guest._idstringThe Guesty guest ID.yesyes
guest.fullNamestringThe full name of the guestyes

Default Response


{
            "_id": "66f1c4a1246e7d9f0f8da88a",
            "integration": {
                "_id": "660d12b08048010013b6a2ef",
                "platform": "manual",
                "limitations": {
                    "availableStatuses": []
                }
            },
            "creationInfo": null,
            "confirmationCode": "GY-h5SdcsBL",
            "accountId": "66053c21dd2adbdfb3b383b7",
            "guestId": "66f1c4a06100f639de7adab8",
            "listingId": "66054019764cbb000f37c450",
            "listing": {
                "_id": "66054019764cbb000f37c450",
                "title": "Standalone French Villa at the Winery"
            },
            "checkIn": "2024-12-17T13:00:00.000Z",
            "checkOut": "2024-12-27T08:00:00.000Z",
            "guest": {
                "_id": "66f1c4a06100f639de7adab8",
                "fullName": "testFirst testLast"
            }
        },

Filtered Response


{
            "_id": "66f1c4a1246e7d9f0f8da88a",
            "integration": {
                "_id": "660d12b08048010013b6a2ef",
                "platform": "manual",
                "limitations": {
                    "availableStatuses": []
                }
            },
            "accountId": "66053c21dd2adbdfb3b383b7",
            "guestId": "66f1c4a06100f639de7adab8",
            "listingId": "66054019764cbb000f37c450",
            "listing": {
                "_id": "66054019764cbb000f37c450"
            },
            "guest": {
                "_id": "66f1c4a06100f639de7adab8"
            }
        },

It is a best practice to specify only the reservation fields you require to meet your objective. If you're happy with the default response payload fields, that is fine; whatever achieves your goal. The best way to discover and define the fields you want is to fetch a single reservation, note the required fields, and query them in your search. For example, to include the localized check-in and check-out dates, send:


GET https://open-api.guesty.com/v1/reservations?fields=checkInDateLocalized checkOutDateLocalized


Useful Time-based Fields

The following table contains date fields that you may find helpful in your searches. Ensure you include them as a field when filtering your query by them.


Query ParameterTypeDescription
checkInDateLocalizedstringA YYYY-MM-DD date string that returns the check-in date following the listing's timezone.
checkOutDateLocalizedstringA YYYY-MM-DD date string that returns the check-out date following the listing's timezone.
plannedArrivalstringThe check-in time for the booking when it differs from the listing's default.
plannedDeparturestringThe check-out time for the booking when it differs from the listing's default.
createdAtstringThe date on which the listing was created in Guesty. It must be in ISO 8601 date format. E.g.,2023-07-26T16:23:38.453Z.
confirmedAtstringThe date-time the booking was confirmed in Guesty. It must be in ISO 8601 date format. E.g., 2023-02-28T13:06:47.611Z.
lastUpdatedAtstringThe date-time of the most recent update to the reservation. It must be in ISO 8601 date format. E.g., 2024-12-19T17:04:01.790Z.

Filters

A valid filter primarily consists of an operator, field, and value. It is written between a pair of curly braces, creating an object inside an array. For example:


[{"operator": "$eq", "field": "source", "value": "Website bookings"}]


Filters can also be stacked within the array. Make sure to separate each filter object from the subsequent one by a comma:


[{"operator": "$eq", "field": "source", "value": "Website bookings"},{"operator": "$eq", "field": "listingId", "value": "1234"}]

Supported Operators

This table provides you with the logical operators you can use in formulating your filters


OperatorDefinition
$eqUse this filter to return reservations whose selected field value equals the query value.
$neUse this filter to return reservations whose selected field value doesn't equal the query value.
$notUse this filter to return reservations, excluding those whose selected field value equals the query value.
$containsReturns the reservations where the value of a field equals any value in the specified array.
$notcontainsSelects the documents where the specified field value is not in the specified collection or the specified field does not exist.
$gtSelects those reservations where the specified field's value is greater than (>) the specified value.
$ltSelects the reservations where the value of the field is less than (i.e. <) the specified value.
$betweenUsed with date fields to select reservations that fall within a date range. It is often paired with a context. See the following sections for examples.

Pagination

Guesty returns 25 reservations in the response by default and supports a maximum of 100 per query. When the result indicates more than 100 reservations, you must implement pagination and sort the response according to a unique identifier to ensure you capture all unique reservations in the collection. For example:


GET https://open-api.guesty.com/v1/reservations?fields=checkInDateLocalized checkOutDateLocalized&skip=100&limit=100&sort=_id


Pagination and Sort Query Parameters


Query ParameterTypeDescription
skipintegerDefine the number of reservations to skip.
limitintegerGuesty returns up to 25 reservations per response by default. You can maximize the number returned by setting this to 100 per request.
sortstringDefine the field to order the results by and whether you want them in ascending or descending order. To ensure unique results us a field like _id or lastUpdatedAt, etc.

📘

Sort Order

You can use a subtraction sign (-) before the field you are sorting with to return results in descending order.For example: /reservations?sort=-checkInDateLocalized


Common Searches

Here are some examples representing the most common searches employed by Guesty customers.


Retrieve Reservation by Confirmation Code

When searching by multiple confirmation codes, use the $in operator.

Filter: [{"operator": "$in", "field": "confirmationCode", "value": ["GY-4QLqteQL", "GY-DYaaeq2w"]}]


curl --globoff 'https://open-api.guesty.com/v1/reservations?filters=[{%22operator%22%3A%20%22%24in%22%2C%20%22field%22%3A%20%22confirmationCode%22%2C%20%22value%22%3A%20[%22GY-4QLqteQL%22%2C%20%22GY-DYaaeq2w%22]}]' \
--header 'Authorization: Bearer {token}'

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {token}");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/reservations?filters=[{\"operator\": \"$in\", \"field\": \"confirmationCode\", \"value\": [\"GY-4QLqteQL\", \"GY-DYaaeq2w\"]}]", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'GET',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/reservations?filters=%5B%7B%22operator%22:%20%22$in%22,%20%22field%22:%20%22confirmationCode%22,%20%22value%22:%20%5B%22GY-4QLqteQL%22,%20%22GY-DYaaeq2w%22%5D%7D%5D',
  'headers': {
    'Authorization': 'Bearer {token}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations?filters=[{%22operator%22%3A%20%22%24in%22%2C%20%22field%22%3A%20%22confirmationCode%22%2C%20%22value%22%3A%20[%22GY-4QLqteQL%22%2C%20%22GY-DYaaeq2w%22]}]',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'Authorization': 'Bearer {token}'
}
conn.request("GET", "/v1/reservations?filters=%5B%7B%22operator%22:%20%22$in%22,%20%22field%22:%20%22confirmationCode%22,%20%22value%22:%20%5B%22GY-4QLqteQL%22,%20%22GY-DYaaeq2w%22%5D%7D%5D", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Retrieve Reservations by Listing ID

Make sure you use the Guesty listing ID as the value.


curl --globoff 'https://open-api.guesty.com/v1/reservations?filters=[{"field":"listingId","operator":"$in","value":["listingId_1","listingId_2"]}]&sort=_id&skip=0&limit=100'

Retrieve Reservations by Last Updated within a Date Range

This query will return reservations last updated within your specified date range.

Filter: [{"operator": "$between", "field": "lastUpdatedAt", "from": "2024-07-25T00:00:00.000Z", "to": "2024-07-25T23:59:59.999Z"}]


curl --globoff 'https://open-api.guesty.com/v1/reservations?fields=_id%20createdAt%20lastUpdatedAt&filters=[{%22operator%22%3A%20%22%24between%22%2C%20%22field%22%3A%20%22lastUpdatedAt%22%2C%20%22from%22%3A%20%222024-07-25T00%3A00%3A00.000Z%22%2C%20%22to%22%3A%20%222024-07-25T23%3A59%3A59.999Z%22}]&limit=100&sort=_id' \
--header 'Authorization: Bearer {token}' 

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {token}");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/reservations?fields=_id%20createdAt%20lastUpdatedAt&filters=[{\"operator\":\"$between\",\"field\":\"lastUpdatedAt\",\"from\":\"2024-07-25T00:00:00.000Z\",\"to\":\"2024-07-25T00:59:59.999Z\"}]&sort=_id&skip=300&limit=100", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'GET',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/reservations?fields=_id%2520createdAt%2520lastUpdatedAt&filters=%5B%7B%22operator%22:%22$between%22,%22field%22:%22lastUpdatedAt%22,%22from%22:%222024-07-25T00:00:00.000Z%22,%22to%22:%222024-07-25T00:59:59.999Z%22%7D%5D&sort=_id&skip=300&limit=100',
  'headers': {
    'Authorization': 'Bearer {token}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations?fields=_id%20createdAt%20lastUpdatedAt&filters=[{%22operator%22%3A%22%24between%22%2C%22field%22%3A%22lastUpdatedAt%22%2C%22from%22%3A%222024-07-25T00%3A00%3A00.000Z%22%2C%22to%22%3A%222024-07-25T00%3A59%3A59.999Z%22}]&sort=_id&skip=300&limit=100',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'Authorization': 'Bearer {token}'
}
conn.request("GET", "/v1/reservations?fields=_id%2520createdAt%2520lastUpdatedAt&filters=%5B%7B%22operator%22:%22$between%22,%22field%22:%22lastUpdatedAt%22,%22from%22:%222024-07-25T00:00:00.000Z%22,%22to%22:%222024-07-25T00:59:59.999Z%22%7D%5D&sort=_id&skip=300&limit=100", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))


Retrieve Reservations from Inactive Listings

This query is unique because you use a filter query to tell Guesty not to filter the response. This means you must retrieve the complete collection. Specifying the fields to return is supported.


curl --globoff 'https://open-api.guesty.com/v1/reservations?filters=[]&skip=0&limit=100&sort=_id' \
--header 'Authorization: Bearer {token}' 

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {token}");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/reservations?filters=[]&skip=0&limit=100&sort=_id", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'GET',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/reservations?filters=%5B%5D&skip=0&limit=100&sort=_id',
  'headers': {
    'Authorization': 'Bearer {token}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations?filters=[]&skip=0&limit=100&sort=_id',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'Authorization': 'Bearer {token}',
}
conn.request("GET", "/v1/reservations?filters=%5B%5D&skip=0&limit=100&sort=_id", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Reservation Payments

Confirmed and Paid

Filter: [{"operator": "$eq", "field": "balanceDue", "value": 0}, {"operator": "$eq", "field": "status", "value": "confirmed"}]


curl --globoff 'https://open-api.guesty.com/v1/reservations?fields=_id%20confirmationCode%20status%20checkInDateLocalized%20checkOutDateLocalized%20listing%20guest%20money.hostPayout%20money.totalPaid%20money.totalRefunded%20money.balanceDue%20money.payments&filters=[{%22operator%22%3A%20%22%24eq%22%2C%20%22field%22%3A%20%22balanceDue%22%2C%20%22value%22%3A%200}%2C%20{%22operator%22%3A%20%22%24eq%22%2C%20%22field%22%3A%20%22status%22%2C%20%22value%22%3A%20%22confirmed%22}]&sort=_id&skip=0&limit=100' \
--header 'Authorization: Bearer {token}'

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {token}");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/reservations?fields=_id confirmationCode status checkInDateLocalized checkOutDateLocalized listing guest money.hostPayout money.totalPaid money.totalRefunded money.balanceDue money.payments&filters=[{\"operator\": \"$eq\", \"field\": \"balanceDue\", \"value\": 0}, {\"operator\": \"$eq\", \"field\": \"status\", \"value\": \"confirmed\"}]&sort=_id&skip=0&limit=100", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'GET',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/reservations?fields=_id%20confirmationCode%20status%20checkInDateLocalized%20checkOutDateLocalized%20listing%20guest%20money.hostPayout%20money.totalPaid%20money.totalRefunded%20money.balanceDue%20money.payments&filters=%5B%7B%22operator%22:%20%22$eq%22,%20%22field%22:%20%22balanceDue%22,%20%22value%22:%200%7D,%20%7B%22operator%22:%20%22$eq%22,%20%22field%22:%20%22status%22,%20%22value%22:%20%22confirmed%22%7D%5D&sort=_id&skip=0&limit=100',
  'headers': {
    'Authorization': 'Bearer {token}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations?fields=_id%20confirmationCode%20status%20checkInDateLocalized%20checkOutDateLocalized%20listing%20guest%20money.hostPayout%20money.totalPaid%20money.totalRefunded%20money.balanceDue%20money.payments&filters=[{%22operator%22%3A%20%22%24eq%22%2C%20%22field%22%3A%20%22balanceDue%22%2C%20%22value%22%3A%200}%2C%20{%22operator%22%3A%20%22%24eq%22%2C%20%22field%22%3A%20%22status%22%2C%20%22value%22%3A%20%22confirmed%22}]&sort=_id&skip=0&limit=100',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'Authorization': 'Bearer {token}'
}
conn.request("GET", "/v1/reservations?fields=_id%20confirmationCode%20status%20checkInDateLocalized%20checkOutDateLocalized%20listing%20guest%20money.hostPayout%20money.totalPaid%20money.totalRefunded%20money.balanceDue%20money.payments&filters=%5B%7B%22operator%22:%20%22$eq%22,%20%22field%22:%20%22balanceDue%22,%20%22value%22:%200%7D,%20%7B%22operator%22:%20%22$eq%22,%20%22field%22:%20%22status%22,%20%22value%22:%20%22confirmed%22%7D%5D&sort=_id&skip=0&limit=100", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Confirmed with Balance Due

Filter: [{"operator": "$ne", "field": "balanceDue", "value": 0}, {"operator": "$eq", "field": "status", "value": "confirmed"}]


curl --globoff 'https://open-api.guesty.com/v1/reservations?fields=_id%20confirmationCode%20status%20checkInDateLocalized%20checkOutDateLocalized%20listing%20guest%20money.hostPayout%20money.totalPaid%20money.totalRefunded%20money.balanceDue%20money.payments&filters=[{%22operator%22%3A%20%22%24ne%22%2C%20%22field%22%3A%20%22balanceDue%22%2C%20%22value%22%3A%200}%2C%20{%22operator%22%3A%20%22%24eq%22%2C%20%22field%22%3A%20%22status%22%2C%20%22value%22%3A%20%22confirmed%22}]&sort=_id&skip=0&limit=100' \
--header 'Authorization: Bearer {token}'

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {token}");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/reservations?fields=_id confirmationCode status checkInDateLocalized checkOutDateLocalized listing guest money.hostPayout money.totalPaid money.totalRefunded money.balanceDue money.payments&filters=[{\"operator\": \"$ne\", \"field\": \"balanceDue\", \"value\": 0}, {\"operator\": \"$eq\", \"field\": \"status\", \"value\": \"confirmed\"}]&sort=_id&skip=0&limit=100", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'GET',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/reservations?fields=_id%20confirmationCode%20status%20checkInDateLocalized%20checkOutDateLocalized%20listing%20guest%20money.hostPayout%20money.totalPaid%20money.totalRefunded%20money.balanceDue%20money.payments&filters=%5B%7B%22operator%22:%20%22$ne%22,%20%22field%22:%20%22balanceDue%22,%20%22value%22:%200%7D,%20%7B%22operator%22:%20%22$eq%22,%20%22field%22:%20%22status%22,%20%22value%22:%20%22confirmed%22%7D%5D&sort=_id&skip=0&limit=100',
  'headers': {
    'Authorization': 'Bearer {token}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations?fields=_id%20confirmationCode%20status%20checkInDateLocalized%20checkOutDateLocalized%20listing%20guest%20money.hostPayout%20money.totalPaid%20money.totalRefunded%20money.balanceDue%20money.payments&filters=[{%22operator%22%3A%20%22%24ne%22%2C%20%22field%22%3A%20%22balanceDue%22%2C%20%22value%22%3A%200}%2C%20{%22operator%22%3A%20%22%24eq%22%2C%20%22field%22%3A%20%22status%22%2C%20%22value%22%3A%20%22confirmed%22}]&sort=_id&skip=0&limit=100',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'Authorization': 'Bearer {token}'
}
conn.request("GET", "/v1/reservations?fields=_id%20confirmationCode%20status%20checkInDateLocalized%20checkOutDateLocalized%20listing%20guest%20money.hostPayout%20money.totalPaid%20money.totalRefunded%20money.balanceDue%20money.payments&filters=%5B%7B%22operator%22:%20%22$ne%22,%20%22field%22:%20%22balanceDue%22,%20%22value%22:%200%7D,%20%7B%22operator%22:%20%22$eq%22,%20%22field%22:%20%22status%22,%20%22value%22:%20%22confirmed%22%7D%5D&sort=_id&skip=0&limit=100", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Search by Check-Out Date and Reservation Status

This example will return the same number of reservations checking out (assuming the current date) as shown in the checkout stats on your dashboard's home page. It counts confirmed and reserved bookings.

Filter: [{"field":"checkOutDateLocalized","operator":"$eq","value":"YYYY-MM-DD"}, {"operator": "$in", "field": "status", "value": ["confirmed","reserved"]}]


curl --globoff 'https://open-api.guesty.com/v1/reservations?fields=lastUpdatedAt%20status%20source%20number%20of%20guests%20guest%20checkIn%20checkInDateLocalized%20checkOut%20checkOutDateLocalized%20money.hostPayout%20createdAt&filters=[{%22field%22%3A%22checkOutDateLocalized%22%2C%22operator%22%3A%22%24eq%22%2C%22value%22%3A%22YYYY-MM-DD%22}%2C%20{%22operator%22%3A%20%22%24in%22%2C%20%22field%22%3A%20%22status%22%2C%20%22value%22%3A%20[%22confirmed%22%2C%22reserved%22]}]&sort=_id&limit=100&skip=0' \
--header 'Authorization: Bearer {token}'

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {token}");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/reservations?fields=lastUpdatedAt status source number of guests guest checkIn checkInDateLocalized checkOut checkOutDateLocalized money.hostPayout createdAt&filters=[{\"field\":\"checkOutDateLocalized\",\"operator\":\"$eq\",\"value\":\"YYYY-MM-DD\"}, {\"operator\": \"$in\", \"field\": \"status\", \"value\": [\"confirmed\",\"reserved\"]}]&sort=_id&limit=100&skip=0", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'GET',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/reservations?fields=lastUpdatedAt%20status%20source%20number%20of%20guests%20guest%20checkIn%20checkInDateLocalized%20checkOut%20checkOutDateLocalized%20money.hostPayout%20createdAt&filters=%5B%7B%22field%22:%22checkOutDateLocalized%22,%22operator%22:%22$eq%22,%22value%22:%22YYYY-MM-DD%22%7D,%20%7B%22operator%22:%20%22$in%22,%20%22field%22:%20%22status%22,%20%22value%22:%20%5B%22confirmed%22,%22reserved%22%5D%7D%5D&sort=_id&limit=100&skip=0',
  'headers': {
    'Authorization': 'Bearer {token}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations?fields=lastUpdatedAt%20status%20source%20number%20of%20guests%20guest%20checkIn%20checkInDateLocalized%20checkOut%20checkOutDateLocalized%20money.hostPayout%20createdAt&filters=[{%22field%22%3A%22checkOutDateLocalized%22%2C%22operator%22%3A%22%24eq%22%2C%22value%22%3A%22YYYY-MM-DD%22}%2C%20{%22operator%22%3A%20%22%24in%22%2C%20%22field%22%3A%20%22status%22%2C%20%22value%22%3A%20[%22confirmed%22%2C%22reserved%22]}]&sort=_id&limit=100&skip=0',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'Authorization': 'Bearer {token}'
}
conn.request("GET", "/v1/reservations?fields=lastUpdatedAt%20status%20source%20number%20of%20guests%20guest%20checkIn%20checkInDateLocalized%20checkOut%20checkOutDateLocalized%20money.hostPayout%20createdAt&filters=%5B%7B%22field%22:%22checkOutDateLocalized%22,%22operator%22:%22$eq%22,%22value%22:%22YYYY-MM-DD%22%7D,%20%7B%22operator%22:%20%22$in%22,%20%22field%22:%20%22status%22,%20%22value%22:%20%5B%22confirmed%22,%22reserved%22%5D%7D%5D&sort=_id&limit=100&skip=0", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Exclude Imported Reservations from Search

Filter: [{"operator": "$eq", "field": "importedAt", "value": null}]


curl --globoff 'https://open-api.guesty.com/v1/reservations?fields=_id%20confirmationCode%20checkInDateLocalized%20checkOutDateLocalized%20integration.platform%20source%20listing%20guest%20importedAt%20&filters=[{%22operator%22%3A%20%22%24eq%22%2C%20%22field%22%3A%20%22importedAt%22%2C%20%22value%22%3A%20null}]&sort=_id&skip=0&limit=100' \
--header 'Authorization: Bearer {token}'

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {token}");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/reservations?fields=_id confirmationCode checkInDateLocalized checkOutDateLocalized integration.platform source listing guest importedAt &filters=[{\"operator\": \"$eq\", \"field\": \"importedAt\", \"value\": null}]&sort=_id&skip=0&limit=100", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'GET',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/reservations?fields=_id%20confirmationCode%20checkInDateLocalized%20checkOutDateLocalized%20integration.platform%20source%20listing%20guest%20importedAt%20&filters=%5B%7B%22operator%22:%20%22$eq%22,%20%22field%22:%20%22importedAt%22,%20%22value%22:%20null%7D%5D&sort=_id&skip=0&limit=100',
  'headers': {
    'Authorization': 'Bearer {token}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations?fields=_id%20confirmationCode%20checkInDateLocalized%20checkOutDateLocalized%20integration.platform%20source%20listing%20guest%20importedAt%20&filters=[{%22operator%22%3A%20%22%24eq%22%2C%20%22field%22%3A%20%22importedAt%22%2C%20%22value%22%3A%20null}]&sort=_id&skip=0&limit=100',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'Authorization': 'Bearer {token}'
}
conn.request("GET", "/v1/reservations?fields=_id%20confirmationCode%20checkInDateLocalized%20checkOutDateLocalized%20integration.platform%20source%20listing%20guest%20importedAt%20&filters=%5B%7B%22operator%22:%20%22$eq%22,%20%22field%22:%20%22importedAt%22,%20%22value%22:%20null%7D%5D&sort=_id&skip=0&limit=100", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Search for Imported OTA Reservations

Imported OTA reservations will contain an importedAt field with the date and time the booking was imported into Guesty.

Filter: [{"operator": "$ne", "field": "importedAt", "value": null}]


curl --globoff 'https://open-api.guesty.com/v1/reservations?fields=_id%20confirmationCode%20checkInDateLocalized%20checkOutDateLocalized%20integration.platform%20source%20listing%20guest%20importedAt%20&filters=[{%22operator%22%3A%20%22%24ne%22%2C%20%22field%22%3A%20%22importedAt%22%2C%20%22value%22%3A%20null}]&sort=_id&skip=0&limit=100' \
--header 'Authorization: Bearer {token}'

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {token}");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/reservations?fields=_id confirmationCode checkInDateLocalized checkOutDateLocalized integration.platform source listing guest importedAt &filters=[{\"operator\": \"$ne\", \"field\": \"importedAt\", \"value\": null}]&sort=_id&skip=0&limit=100", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'GET',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/reservations?fields=_id%20confirmationCode%20checkInDateLocalized%20checkOutDateLocalized%20integration.platform%20source%20listing%20guest%20importedAt%20&filters=%5B%7B%22operator%22:%20%22$ne%22,%20%22field%22:%20%22importedAt%22,%20%22value%22:%20null%7D%5D&sort=_id&skip=0&limit=100',
  'headers': {
    'Authorization': 'Bearer {token}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations?fields=_id%20confirmationCode%20checkInDateLocalized%20checkOutDateLocalized%20integration.platform%20source%20listing%20guest%20importedAt%20&filters=[{%22operator%22%3A%20%22%24ne%22%2C%20%22field%22%3A%20%22importedAt%22%2C%20%22value%22%3A%20null}]&sort=_id&skip=0&limit=100',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'Authorization': 'Bearer {token}'
}
conn.request("GET", "/v1/reservations?fields=_id%20confirmationCode%20checkInDateLocalized%20checkOutDateLocalized%20integration.platform%20source%20listing%20guest%20importedAt%20&filters=%5B%7B%22operator%22:%20%22$ne%22,%20%22field%22:%20%22importedAt%22,%20%22value%22:%20null%7D%5D&sort=_id&skip=0&limit=100", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Search by viewId

You can use the viewId of custom reservation reports configured with the Create a view endpoint or from within your Guesty dashboard to retrieve the reservations and fields as preconfigured.


curl 'https://open-api.guesty.com/v1/reservations?viewId=5fa02fa358d2db673e17de4e&sort=_id&skip=0&limit=100' \
--header 'Authorization: Bearer {token}'

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {token}");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/reservations?viewId=5fa02fa358d2db673e17de4e&sort=_id&skip=0&limit=100", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'GET',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/reservations?viewId=5fa02fa358d2db673e17de4e&sort=_id&skip=0&limit=100',
  'headers': {
    'Authorization': 'Bearer {token}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations?viewId=5fa02fa358d2db673e17de4e&sort=_id&skip=0&limit=100',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'Authorization': 'Bearer {token}'
}
conn.request("GET", "/v1/reservations?viewId=5fa02fa358d2db673e17de4e&sort=_id&skip=0&limit=100", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

FAQs

Why can't I retrieve reservations x & y? I'm including inactive listings in my request.

The reservation either isn't assigned to a listing, or the listing to which it is assigned no longer exists. Assign these reservations to a listing, and you will be able to retrieve them.


Reservation z is missing from the response. I know it exists and is assigned to an active listing. I also see it in the UI. Why?

Add a sort query parameter to your request and sort according to a unique field, such as `_id`, `createdAt`, or `lastUpdatedAt`. If you're querying more than 25 reservations, add pagination to ensure you search the entire collection.


Why are there reservations without payments?

It could be due to one or a combination of the following reasons:

  1. No or an invalid payment method was provided at reservation creation.
  2. No autopayment rules were configured, and the payments weren't processed.
  3. Payment was collected outside of Guesty and not recorded in Guesty.
  4. The reservations were imported/uploaded without payment data.
  5. The payment method was valid, but there was an issue with the card when attempting to collect payment.
  6. If the reservation is from an OTA that manages the payments (channel collect), it could be that they haven't sent the update, or your listing is no longer connected with that OTA and cannot receive any further updates from them.

Updated 1 day ago