Guesty Open API

https://open-api-docs.guesty.com
Admin
Comprehensive REST API documentation for Guesty, a property management platform that enables...
Tokens:476,021
Snippets:3,806
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Make first API call: GET listings (Response)

Source: https://open-api-docs.guesty.com/docs

Example JSON response showing a list of listings with id, title, and status fields.

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

--------------------------------

### Pagination example

Source: https://open-api-docs.guesty.com/docs/how-to-search-for-reservations

A GET request to the reservations endpoint with fields, skip, limit, and sort parameters to paginate results.

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

--------------------------------

### GET request with fields parameter

Source: https://open-api-docs.guesty.com/docs/searching-for-available-listings-and-all-listings

Example GET request to the listings endpoint using the `fields` parameter with a list of fields. This request retrieves up to 10 listings with the specified fields.

```HTTP
GET https://open-api.guesty.com/v1/listings?limit=10&fields=id title description address.full address.city address.country pictures amenities accommodates bedrooms bathrooms
```

--------------------------------

### Legacy reservation response example

Source: https://open-api-docs.guesty.com/docs/virtual-credit-card-vcc-payments

Example response from the legacy GET /reservations endpoint. Contains guest._id, guestId, and reservation _id to cache for identifying the payment method type.

```json
{
  "_id": "reservationIdString",
  "integration": {
    "platform": "expedia",
    "_id": "integrationIdString",
    "limitations": {
      "availableStatuses": []
    }
  },
  "confirmationCode": "EXP-string",
  "status": "confirmed",
  "source": "Expedia",
  "listingId": "listingIdString",
  "confirmedAt": "2026-06-22T07:16:17.804Z",
  "guest": {
    "_id": "guestIdString",
    "firstName": "Given name",
    "lastName": "Surname",
    "fullName": "Full name",
    "email": "Primary email"
  },
  "money": {
    "currency": "USD",
    "payments": [
      {
        "paymentMethodId": "paymentMethodIdString"
      }
    ]
  },
  "checkInDateLocalized": "2026-06-22",
  "checkOutDateLocalized": "2026-06-29",
  "accountId": "accountIdString",
  "guestId": "guestIdString",
  "createdAt": "2026-06-22T07:16:18.334Z",
  "stay": [],
  "listing": {
    "_id": "listingIdString",
    "type": "MTL_CHILD",
    "address": {
      "full": "6 Ave, New York, NY 10038, United States"
    },
    "nickname": "Listing nickname",
    "title": "Listing title",
    "timezone": "America/New_York"
  }
}
```

--------------------------------

### Search with fields Parameter

Source: https://open-api-docs.guesty.com/docs/how-to-search-for-reservations

Example GET request to include localized check-in and check-out dates in the search results.

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

--------------------------------

### GET /v1/guest-folio/invoice-items example request

Source: https://open-api-docs.guesty.com/reference/getguestfolioinvoiceitems

Example request that fetches the line item type, total price, and per-night breakdown for two reservations. Uses the fields query parameter with dot-notation for nested fields. The response always returns HTTP 200; unavailable reservation IDs are listed in notFound.

```http
GET /v1/guest-folio/invoice-items?reservationIds=64a1f2c3e4b0a1b2c3d4e5f6,64a1f2c3e4b0a1b2c3d4e5f7&fields=normalType,totalPrice,nightsBreakdown.date,nightsBreakdown.basePrice
```

--------------------------------

### Retrieve guest payment methods with GET /v1/guests/{id}/payment-methods

Source: https://open-api-docs.guesty.com/docs/posting-a-guest-payment

Retrieves the payment methods for a guest using the GET /v1/guests/{id}/payment-methods endpoint. The `id` path parameter is the reservation ID, and the guest ID is the example. Optionally add the `reservationId` query parameter to specify the reservation.

```curl
curl 'https://open-api.guesty.com/v1/guests/64da2084867c12ee0c2ca47f/payment-methods' \
--header 'content-type: application/json'
```

```javascript
var myHeaders = new Headers();
myHeaders.append("content-type", "application/json");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'manual'
};

fetch("https://open-api.guesty.com/v1/guests/64da2084867c12ee0c2ca47f/payment-methods", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/guests/64da2084867c12ee0c2ca47f/payment-methods',
  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(
    'content-type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

```

```python
import http.client
import json

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'content-type': 'application/json'
}
conn.request("GET", "/v1/guests/64da2084867c12ee0c2ca47f/payment-methods", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```

--------------------------------

### Multi-unit creation request body example

Source: https://open-api-docs.guesty.com/docs/create-a-property

Example JSON structure for the multi-unit management settings (mtl) and sub-unit creation parameters.

```json
{
  "mtl":{
    "aas":"bc",
    "aao":"f",
    "bc":14,
    "hdb4":14,
    "lmcn":true
  },
  "numberOfChildrenToCreate":5,
  "manageSubunitPictures":true
}
```

--------------------------------

### GET /v1/listings

Source: https://open-api-docs.guesty.com/reference/authentication-2

Example of making an authenticated GET request to the listings endpoint using a Bearer access token.

```APIDOC
## GET /v1/listings

### Description
Retrieve listings from the Guesty Open API using an access token in the Authorization header.

### Method
GET

### Endpoint
https://open-api.guesty.com/v1/listings

### Headers
- **accept** (string) - Required - Set to `application/json`
- **Authorization** (string) - Required - Bearer token, e.g., `Bearer <accessToken>`

### Request Example
```
curl --location --request GET 'https://open-api.guesty.com/v1/listings' \
--header 'accept: application/json' \
--header 'Authorization: Bearer <accessToken>'
```

### Response
#### Success Response (200)
- Response body not specified in the source.

#### Error Response (403)
- **message** (string) - Error message when token is expired or invalid.

#### Error Response Example
```
{
  "message": "You don't have permission to access, please contact Guesty support."
}
```
```

--------------------------------

### v3 reservation response example

Source: https://open-api-docs.guesty.com/docs/virtual-credit-card-vcc-payments

Example response from the GET /reservations-v3 endpoint. Contains bookerId and reservation _id to cache for identifying the payment method type.

```json
[
  {
    "_id": "reservationIdString",
    "createdAt": "2026-06-22T07:16:18.334Z",
    "bookingDate": "2026-06-22T07:16:18.334Z",
    "status": "confirmed",
    "confirmationCode": "EXP-string",
    "accountId": "accountIdString",
    "checkInDateLocalized": "2026-06-22",
    "checkOutDateLocalized": "2026-06-29",
    "conversationId": "conversationIdString",
    "source": "Expedia",
    "platform": "expedia",
    "bookerId": "aka the guest ID string",
    "integrationId": "integrationIdString",
    "guestsCount": 2,
    "numberOfGuests": {},
    "legacySystem": true,
    "systemSource": "LEGACY",
    "unitTypeId": "multi-unit ID/single listing ID",
    "unitId": "sub-unit ID/single listing ID",
    "eta": "2026-06-22T16:00:00.000Z",
    "etd": "2026-06-29T11:00:00.000Z",
    "stay": [
      {
        "checkInDateLocalized": "2026-06-22",
        "checkOutDateLocalized": "2026-06-29",
        "guestsCount": 2,
        "numberOfGuests": {
          "numberOfAdults": 2,
          "numberOfInfants": 0,
          "numberOfChildren": 0,
          "numberOfPets": 0
        },
        "unitTypeId": "multi-unit ID/single listing ID",
        "unitId": "sub-unit ID/single listing ID",
        "eta": "2026-06-22T16:00:00.000Z",
        "etd": "2026-06-29T11:00:00.000Z",
        "earlyCheckIn": {
          "blockDay": false
        },
        "lateCheckOut": {
          "blockDay": false
        }
      }
    ],
    "customFields": [],
    "confirmedAt": "2026-06-22T07:16:17.804Z",
    "alteredAt": "2026-06-22T07:16:54.110Z",
    "guestStay": {},
    "manuallyCreated": false,
    "conversationExternalId": "Expedia conversation ID",
    "channelMetadata": {},
    "ratePlans": [],
    "isUsingVCC": true,
    "money": {}
  }
]
```

--------------------------------

### Example reservation response (JSON)

Source: https://open-api-docs.guesty.com/docs/create-a-reservation

Sample JSON response returned by the Create Reservation endpoint. Shows the integration object with limitations, platform 'manual', and per-platform ignored listings/reservations settings.

```json
{
    "integration": {
        "limitations": {
            "availableStatuses": []
        },
        "bookingCom": {
            "invalidCreditCards": [],
            "reports": []
        },
        "_id": "5b9a25fd3bfa6d01b15a0b14",
        "platform": "manual",
        "object": {
            "airbnb": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                },
                "importCalendars": true
            },
            "rentalsUnited": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                },
                "cleaningFeeIncludedInNightlyPrice": {
                    "agoda": true,
                    "bookingCom": false,
                    "canadaStays": true,
                    "despegar": true,
                    "expedia": true,
                    "homeAway": true,
                    "hostelworld": true
                }
            },
            "bookingCom": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                }
            },
            "homeAway": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                }
            },
            "homeaway2": {
                "ignored": {
                    "listings": []
                }
            },
            "agoda": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                }
            },
            "tripAdvisor": {
```

--------------------------------

### Access token management - Python example

Source: https://open-api-docs.guesty.com/recipes

Python code example for the access token management recipe. The exact code is not fully displayed on the page.

```python
xxxxxxxxxx

```

--------------------------------

### Access token management - Node.js example

Source: https://open-api-docs.guesty.com/recipes

Node.js script demonstrating how to request an access token using client credentials, cache it locally, reuse it in API requests, and refresh it 5 minutes before expiry. Requires Node.js and your Guesty API Client ID and Client Secret.

```javascript
xxxxxxxxxx

```

```javascript
  .catch(err => console.error('Request failed:', err.message));

```

```javascript
/**

```

```javascript
* Guesty Open API Token Management Example

```

```javascript
*

```

```javascript
* This Node.js script demonstrates how to:

```

```javascript
* - Request an access token using client credentials

```

```javascript
* - Cache the token locally to avoid unnecessary renewals

```

```javascript
* - Reuse the token in subsequent API requests

```

```javascript
* - Refresh the token 5 minutes before it expires

```

```javascript
*

```

```javascript
* Prerequisites:

```

```javascript
* - Node.js installed

```

```javascript
* - Your Guesty API Client ID and Client Secret

```

```javascript
*/

```

```javascript
const axios = require('axios');

```

```javascript
const fs = require('fs');

```

```javascript
const path = require('path');

```

```javascript


```

```javascript
// === Configuration ===

```

```javascript
const TOKEN_FILE = path.join(__dirname, 'guesty-token.json'); // Where the token will be cached

```

```javascript
const CLIENT_ID = 'YOUR_CLIENT_ID';       // Replace with your Guesty application client ID

```

```javascript
const CLIENT_SECRET = 'YOUR_CLIENT_SECRET'; // Replace with your Guesty application client secret

```

```javascript
const TOKEN_URL = 'https://open-api.guesty.com/oauth2/token';  // Token request endpoint

```

```javascript


```

```javascript
/**

```

```javascript
* Checks if a valid token is cached. If so, returns it.

```

--------------------------------

### New webhook payload example

Source: https://open-api-docs.guesty.com/docs/calendar-webhook-migration

Example of the new `calendar.updated.v2` webhook payload. It contains listing ID, account ID, currency, and a date range with start and end dates.

```json
{
  "listingId": "string",
  "accountId": "string",
  "currency": "string",
  "dateRange": {
    "start": "YYYY-MM-DD",
    "end": "YYYY-MM-DD"
  }
}
```

--------------------------------

### Recipe Title - Output

Source: https://open-api-docs.guesty.com/recipes

Example output showing a successful response with JSON object {"success":true}.

```json
{"success":true}

```

--------------------------------

### cURL request to get all journal entries

Source: https://open-api-docs.guesty.com/reference/journalentriescontroller_getall

Example cURL request to the Get all journal entries endpoint. Uses the transactionDate query parameter with an @in_future operator and accepts JSON response.

```shell
curl --request GET \
     --url 'https://open-api.guesty.com/v1/accounting-api/journal-entries/all?transactionDate=operator=%40in_future' \
     --header 'accept: application/json'
```

--------------------------------

### Response for listing a property

Source: https://open-api-docs.guesty.com/docs/list-and-unlist-properties

Example JSON response after successfully listing a property.

```json
{
    "isListed": true,
    "accountId": "string",
    "_id": "66054019764cbb000f37c450"
}
```

--------------------------------

### Example response: guest payment methods list

Source: https://open-api-docs.guesty.com/docs/posting-a-guest-payment

Example response from the guest payment methods request. The `method` field can be `STRIPE` (Stripe processor) or `AMARYLLIS` (for GuestyPay, Merchant Warrior, or Hyp). The `payload` object varies depending on the card and payment processor.

```json
[
    {
        "_id": "64da2367d8d9771c02befbb2",
        "accountId": "5213a2d206112710005d96ff",
        "paymentProviderId": "623833c1486b1c0033604efc",
        "method": "STRIPE",
        "payload": {
          // Varies depending on the card and payment processor
        },
        "saveForFutureUse": true,
        "createdAt": "2023-08-14T12:52:05.012Z",
        "last4": "4242",
        "brand": "visa",
        "status": "ACTIVE",
        "type": "PHYSICAL",
        "updatedAt": "2023-08-14T12:51:51.082Z",
        "__v": 0,
        "guestId": "64da2084867c12ee0c2ca47f"
    }
]
```

--------------------------------

### Get reservation by ID with cURL, JavaScript, Node, PHP, Python

Source: https://open-api-docs.guesty.com/docs/reservations-v3-booking-flow

Retrieves full reservation details by ID using the GET /v1/reservations-v3 endpoint. The examples are shown in cURL, JavaScript, Node.js, PHP, and Python. Use the `reservationId` returned from the creation request.

```bash
curl --globoff 'https://open-api.guesty.com/v1/reservations-v3?reservationIds[]=667bc9e0319654c49fde9aff' \
--header 'accept: application/json' \
--header 'authorization: Bearer {accessToken}'
```

```javascript
const myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("authorization", "Bearer {accessToken}");

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

fetch("https://open-api.guesty.com/v1/reservations-v3?reservationIds[]=667bc9e0319654c49fde9aff", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
```

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

var options = {
  'method': 'GET',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/reservations-v3?reservationIds%5B%5D=667bc9e0319654c49fde9aff',
  'headers': {
    'accept': 'application/json',
    'authorization': 'Bearer {accessToken}'
  },
  '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
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/reservations-v3?reservationIds[]=667bc9e0319654c49fde9aff',
  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(
    'accept: application/json',
    'authorization: Bearer {accessToken}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

```

```python
import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'accept': 'application/json',
  'authorization': 'Bearer {accessToken}'
}
conn.request("GET", "/v1/reservations-v3?reservationIds%5B%5D=667bc9e0319654c49fde9aff", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```

--------------------------------

### Flexible Task Payload Example (task.created webhook)

Source: https://open-api-docs.guesty.com/docs/webhooks-tasks

Example JSON payload for a flexible task, where startTime is null and canStartAfter/mustFinishBefore are set. The payload includes the task object, the creator, and the event name.

```json
{
    "task": {
        "assigneeGroup": [],
        "checklistFinished": [],
        "checklist": [
            "<ITEM 1>",
            "<ITEM 2>",
            "<ETC>"
        ],
        "tags": [],
        "status": "pending",
        "editedFields": [],
        "_id": "630f3484653ed00034a606db",
        "accountId": "62a8a2be2e53190032102a6e",
        "createdBy": "630be5decca8c10032ee203d",
        "plannedDuration": 2,
        "description": "<TASK DETAILS>",
        "assigneeId": "63066dbe1688e9003780b538",
        "supervisorId": "62a8a2be2e53190032102a77",
        "attachments": [
            {
                "_id": "630f3484653ed00034a606dc",
                "mimetype": "image/png",
                "size": 938707,
                "client": "cbt",
                "title": "top-secret-2054429_1920",
                "url": "http://res.cloudinary.com/guesty/raw/upload/v1661940849/production/62a8a2be2e53190032102a6e/totrxvefzhicwubudrst.png"
            }
        ],
        "priority": 3,
        "title": "Resupply Bathroom Toiletries",
        "startTime": null,
        "canStartAfter": "2022-09-13T10:00:00.000Z",
        "mustFinishBefore": "2022-09-14T14:00:00.000Z",
        "listingId": "62e17bddae108b003b1f87d7",
        "checklistAggregated": [],
        "afterEffects": [],
        "comments": [],
        "log": [],
        "createdAt": "2022-08-31T10:14:28.810Z",
        "updatedAt": "2022-08-31T10:14:28.810Z",
        "enumeratedStatus": 6,
        "dateForSort": "2022-09-14T14:00:00.000Z",
        "assigneeFullName": "Belle Perry",
        "__v": 0
    },
    "by": "Moshe",
    "event": "task.created"
}
```

--------------------------------

### Make first API call: GET listings (Request)

Source: https://open-api-docs.guesty.com/docs

HTTP request to fetch a list of listings. Requires Authorization header with 'Bearer' prefix before the access token.

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

--------------------------------

### Response - JSON

Source: https://open-api-docs.guesty.com/docs/refunding-a-guest-payment

Example JSON response from the GET request, showing the reservation's payment details including the payment ID (_id) and status.

```json
{
    "_id": "64da254383ad1500284bd0c0",
    "integration": {
        "_id": "62a72ab7c147f0003487b854",
        "platform": "manual",
        "limitations": {
            "availableStatuses": []
        }
    },
    "listingId": "64da223eb3de7a002a462fcc",
    "guestId": "64da2084867c12ee0c2ca47f",
    "accountId": "5213a2d206112710005d96ff",
    "money": {
        "currency": "USD",
        "payments": [
            {
                "paymentMethodStatus": "ACTIVE",
                "isAuthorizationHold": false,
                "status": "PENDING",
                "_id": "64da25d683ad1500284bd0ef",
                "chargebacksData": {
                    "chargebacks": []
                },
                "amount": 1200,
                "shouldBePaidAt": "2023-09-01T12:00:00.000Z",
                "note": "Second installment",
                "paymentMethodId": "64da2367d8d9771c02befbb2",
                "guestId": "64da2084867c12ee0c2ca47f",
                "currency": "USD",
                "attempts": [],
                "refunds": [],
                "authorizationHoldCaptures": [],
                "createdAt": "2023-08-14T13:02:14.058Z",
                "receiptTargets": []
            },
            {
                "paymentMethodStatus": "ACTIVE",
                "isAuthorizationHold": false,
                "status": "SUCCEEDED",
                "_id": "64da267c83ad1500284bd104",
                "chargebacksData": {
                    "chargebacks": []
                },
                "amount": 500,
                "note": "Deposit",
                "paymentMethodId": "64da2367d8d9771c02befbb2",
                "guestId": "64da2084867c12ee0c2ca47f",
                "currency": "USD",
                "attempts": [
                    {
                        "_id": "64da267d83ad1500284bd109",
                        "status": "SUCCEEDED",
                        "payload": {
                            "id": "pi_3Nf0S8GfrrmRCKB11SVF4dCI",
                            "object": "payment_intent",
                            "amount": 50000,
                            "amount_capturable": 0,
                            "amount_received": 50000,
                            "application": "ca_7S8pfqtl3Am55FsbIOZcBbZivQqEDeUd",
                            "application_fee_amount": 200,
                            "automatic_payment_methods": null,
                            "canceled_at": null,
                            "cancellation_reason": null,
                            "capture_method": "automatic",
                            "charges": {
                                "object": "list",
                                "data": [
                                    {
                                        "id": "ch_3Nf0S8GfrrmRCKB1160cJBx4",
                                        "object": "charge",
                                        "amount": 50000,
                                        "amount_captured": 50000,
                                        "amount_refunded": 0,
                                        "application": "ca_7S8pfqtl3Am55FsbIOZcBbZivQqEDeUd",
                                        "application_fee": "fee_1Nf0S9GfrrmRCKB1dolQDBpR"
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        ]
    }
}
```

--------------------------------

### Example reservation object

Source: https://open-api-docs.guesty.com/docs/extend-or-shorten-a-reservation

A sample reservation object showing the structure returned by the API, including integration details, guest information, and current stay dates.

```JSON
{
    "_id": "64c9213ba097ec00417a9911",
    "integration": {
        "_id": "5b9a25fd3bfa6d01b15a0b14",
        "platform": "manual",
        "limitations": {
            "availableStatuses": [
                "checked_in",
                "checked_out",
                "canceled"
            ]
        }
    },
    "listingId": "62ec6975134d780032b62221",
    "checkInDateLocalized": "2023-09-12",
    "checkOutDateLocalized": "2023-09-20",
    "status": "confirmed",
    "guest": {
        "_id": "64c9213aa097ec00417a9910",
        "fullName": "Ernest Hemingway"
    },
    "accountId": "5b852676354b34003f0a55eb",
    "guestId": "64c9213aa097ec00417a9910",
    "source": "Manual",
    "confirmationCode": "r2Bk86Yj4",
    "listing": {
        "_id": "62ec6975134d780032b62221",
        "nickname": "Test_Listing_Shan"
    }
}
```

--------------------------------

### cURL GET recognized journal entries with transactionDate

Source: https://open-api-docs.guesty.com/reference/journalentriescontroller_getrecognized

Uses cURL to send a GET request to the journal entries endpoint with a transactionDate query parameter. The example demonstrates a request with operator '@in_future', but note that the source indicates the query param format must be URL-encoded as explained above. The response is expected in JSON.

```shell
curl --request GET \
     --url 'https://open-api.guesty.com/v1/accounting-api/journal-entries?transactionDate=operator=%40in_future' \
     --header 'accept: application/json'
```

--------------------------------

### Create Guest Profile with cURL, JavaScript, PHP, and Python

Source: https://open-api-docs.guesty.com/docs/create-guest-and-payment-method

Create a new guest profile by POSTing to the Guesty Open API endpoint /v1/guests-crud. The example sends a JSON body with guest details such as firstName, lastName, email, phone, and optional fields like pronouns and preferredLanguage. The response includes a guest _id that is used later to assign the guest to a reservation.

```bash
curl 'https://open-api.guesty.com/v1/guests-crud' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data-raw '
{
  "firstName": "Irving",
  "lastName": "Washington",
  "hometown": "New York",
  "email": "ichabod@hotmail.com",
  "phone": "+12128765234",
  "nationality": "us",
  "pronouns": "he/him/his",
  "gender": "male",
  "preferredLanguage": "en"
}
'

```

```javascript
var settings = {
  "url": "https://open-api.guesty.com/v1/guests-crud",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "accept": "application/json",
    "content-type": "application/json"
  },
  "data": JSON.stringify({
    "firstName": "Irving",
    "lastName": "Washington",
    "hometown": "New York",
    "email": "ichabod@hotmail.com",
    "phone": "+12128765234",
    "nationality": "us",
    "pronouns": "he/him/his",
    "gender": "male",
    "preferredLanguage": "en"
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/guests-crud',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'
{
  "firstName": "Irving",
  "lastName": "Washington",
  "hometown": "New York",
  "email": "ichabod@hotmail.com",
  "phone": "+12128765234",
  "nationality": "us",
  "pronouns": "he/him/his",
  "gender": "male",
  "preferredLanguage": "en"
}
',
  CURLOPT_HTTPHEADER => array(
    'accept: application/json',
    'content-type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


```

```python
import http.client
import json

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = json.dumps({
  "firstName": "Irving",
  "lastName": "Washington",
  "hometown": "New York",
  "email": "ichabod@hotmail.com",
  "phone": "+12128765234",
  "nationality": "us",
  "pronouns": "he/him/his",
  "gender": "male",
  "preferredLanguage": "en"
})
headers = {
  'accept': 'application/json',
  'content-type': 'application/json'
}
conn.request("POST", "/v1/guests-crud", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

```

--------------------------------

### cURL request to get expenses with filtering

Source: https://open-api-docs.guesty.com/reference/expenses-only-available-for-accounting-add-on-users

Example cURL command to retrieve expenses with default pagination (limit=50, skip=0). Requires an authentication token in the 'accept: application/json' header.

```shell
curl --request GET \
     --url 'https://open-api.guesty.com/v1/expenses-api/expenses?limit=50&skip=0' \
     --header 'accept: application/json'
```

--------------------------------

### GET /v1/availability-pricing/api/calendar/listings

Source: https://open-api-docs.guesty.com/reference/get_availability-pricing-api-calendar-listings

Retrieves calendar availability and pricing for multiple listings according to a date range. Requires listing IDs, start date, and end date as query parameters.

```APIDOC
## GET /v1/availability-pricing/api/calendar/listings

### Description
Retrieves calendar availability and pricing for multiple listings according to a date range.

### Method
GET

### Endpoint
https://open-api.guesty.com/v1/availability-pricing/api/calendar/listings

### Parameters
#### Query Parameters
- **listingIds** (string) - Required - Listing IDs (comma separated)
- **startDate** (date) - Required - First day to be returned (format: YYYY-MM-DD)
- **endDate** (date) - Required - Last day to be returned (format: YYYY-MM-DD)
- **includeAllotment** (boolean) - Optional - Return day objects including allotment
- **ignoreInactiveChildAllotment** (boolean) - Optional - Specify ignoreInactiveChildAllotment=true to exclude inactive sub-units from the allotment calculation. Default value is false.
- **ignoreUnlistedChildAllotment** (boolean) - Optional - Specify ignoreUnlistedChildAllotment=true to exclude unlisted sub-units from the allotment calculation. Default value is false.

### Request Example
```
curl --request GET \
     --url https://open-api.guesty.com/v1/availability-pricing/api/calendar/listings \
     --header 'accept: application/json'
```

### Response
#### Success Response (200)
Calendar with available/unavailable dates

#### Error Responses
- **404** - Listing Not Found
- **422** - Validation Error
- **500** - Unhandled exception. Something went wrong on server.

```

--------------------------------

### cURL Request to Get Owners

Source: https://open-api-docs.guesty.com/reference/ownersopenapicontroller_getall

Example cURL command to fetch a list of owners. Uses query parameters skip=0, limit=10, sort=_id, and pagination=false. Requires an 'accept: application/json' header.

```shell
curl --request GET \
     --url 'https://open-api.guesty.com/v1/owners?skip=0&limit=10&sort=_id&pagination=false' \
     --header 'accept: application/json'
```

--------------------------------

### Create reservation response - JSON response

Source: https://open-api-docs.guesty.com/docs/create-a-reservation

Example response from the POST /v1/reservations request. Shows integration settings, pricing factors, and flags. The response is truncated in the source.

```json
{
    "integration": {
        "limitations": {
            "availableStatuses": []
        },
        "bookingCom": {
            "invalidCreditCards": [],
            "reports": []
        },
        "_id": "5b9a25fd3bfa6d01b15a0b14",
        "platform": "manual",
        "object": {
            "airbnb": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                },
                "importCalendars": true
            },
            "rentalsUnited": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                },
                "cleaningFeeIncludedInNightlyPrice": {
                    "agoda": true,
                    "bookingCom": false,
                    "canadaStays": true,
                    "despegar": true,
                    "expedia": true,
                    "homeAway": true,
                    "hostelworld": true
                }
            },
            "bookingCom": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                }
            },
            "homeAway": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                }
            },
            "homeaway2": {
                "ignored": {
                    "listings": []
                }
            },
            "agoda": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                }
            },
            "tripAdvisor": {
                "ignored": {
                    "listings": [],
                    "reservations": []
                }
            },
            "_id": "5b9a25fd3bfa6d01b15a0b14",
            "platform": "manual",
            "incomingEmail": "demobnb_oe6yqvg@user.guesty.com",
            "nickname": "demobnb_oe6yqvg",
            "createAt": "2018-09-13T08:55:25.034Z",
            "active": true,
            "createdAt": "2018-09-13T08:55:25.000Z"
        }
    },
    "review": {
        "shouldReview": true
    },
    "atTimeOfConfirmation": {
        "snapshotCreated": false,
        "monthlyPriceFactor": 1,
        "weeklyPriceFactor": 1,
        "taxes": []
    },
    "earlyCheckIn": {
        "blockDay": false
    },
    "lateCheckOut": {
        "blockDay": false
    },
    "flag": false,
    "accountingEnabled": true,
    "isBMApplied": false
```

--------------------------------

### GET /v1/guest-folio/overview

Source: https://open-api-docs.guesty.com/reference/guest-folio

Retrieves a financial overview for one or more reservations from the guest folio. Requires at least one field to be specified via the `fields` query parameter. Supports partial success and a maximum of 200 reservation IDs per request.

```APIDOC
## [GET] /v1/guest-folio/overview

### Description
Retrieves a financial overview for one or more reservations from the guest folio. You must specify at least one field to return via the `fields` query parameter. `reservationId` is always included in every result, even if not listed in `fields`.

### Method
GET

### Endpoint
https://open-api.guesty.com/v1/guest-folio/overview

### Parameters
#### Query Parameters
- **reservationIds** (array of strings) - Required - Comma-separated reservation IDs. Maximum 200 per request. Length between 1 and 200.
- **fields** (array of strings) - Required - Comma-separated field names to include in the response. Must specify at least one. `reservationId` is always returned. Unrecognized values result in HTTP 400. Nested array fields (e.g. `bundledFees`, `perStayTotals`) must be requested using their leaf paths (e.g. `bundledFees.title`, `perStayTotals.hostPayout`) — the parent name alone is not a valid selection. For a description of each field, see the **Response Body** section on this page.

### Request Example
```
GET /v1/guest-folio/overview?reservationIds=64a1f2c3e4b0a1b2c3d4e5f6,64a1f2c3e4b0a1b2c3d4e5f7&fields=hostPayout,totalTaxes,currency
```

### Response
#### Success Response (200)
- **results** (array) - Found records for the requested reservation IDs.
- **notFound** (array) - Reservation IDs that were not found.
- **currency** (string) - The currency of the monetary values, unless the field name explicitly indicates another currency (e.g. `hostPayoutUsd`).

#### Response Example
(No explicit response example provided in the source.)

### Error Handling
- **400** - Returned if an unrecognized field name is provided in the `fields` parameter.
- **200** - Returned even if some reservation IDs are not found; missing IDs are listed in `notFound`.

### Notes
- **Bulk limit**: A maximum of 200 reservation IDs can be submitted per request. For larger datasets, paginate by calling this endpoint in batches of up to 200. Parallel requests are supported and recommended when retrieving many reservations.
- **Partial success**: If some reservation IDs are not found, the response still returns HTTP 200. Found records appear in `results`; missing IDs are listed in `notFound`.
```

--------------------------------

### cURL request to retrieve calendars for multiple listings

Source: https://open-api-docs.guesty.com/reference/get_availability-pricing-api-calendar-listings

Use this cURL command to call the GET endpoint with the required query parameters. The example shows the request with the accept header set to application/json.

```shell
curl --request GET \
     --url https://open-api.guesty.com/v1/availability-pricing/api/calendar/listings \
     --header 'accept: application/json'
```

--------------------------------

### Local stdio MCP configuration with OAuth2 client credentials

Source: https://open-api-docs.guesty.com/docs/guesty-mcp-server-beta

Alternative configuration for local stdio using OAuth2 client credentials. The token exchange happens at server startup. Requires CLIENT_ID and CLIENT_SECRET environment variables.

```json
{
  "mcpServers": {
    "guesty": {
      "command": "npx",
      "args": ["-y", "@guestyorg/sdk", "mcp"],
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

--------------------------------

### cURL request to retrieve reviews

Source: https://open-api-docs.guesty.com/reference/reviewcontroller_getreviews

Use this cURL command to call the GET /v1/reviews endpoint. The example includes the includeCustomChannels query parameter set to false and the accept header for JSON. The response is not shown in the source.

```shell
curl --request GET \
     --url 'https://open-api.guesty.com/v1/reviews?includeCustomChannels=false' \
     --header 'accept: application/json'
```

--------------------------------

### List a multi-unit property with subunits using Python

Source: https://open-api-docs.guesty.com/docs/list-and-unlist-properties

Use this Python http.client example to list a property and its subunits by including updateSubUnits=true in the request path. Requires a valid Bearer token.

```python
import http.client
import json

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = json.dumps({
  "isListed": True
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {token}'
}
conn.request("PUT", "/v1/listings/66054aa58ea6df0012a20b5e?updateSubUnits=true", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```

--------------------------------

### cURL Request to Get Transactions

Source: https://open-api-docs.guesty.com/reference/payment-transactions

Example cURL command to retrieve transactions from Guesty Pay providers. The request uses the endpoint /v1/payment-transactions/reports with query parameters skip=0 and take=25, and includes the accept: application/json header.

```shell
curl --request GET \
     --url 'https://open-api.guesty.com/v1/payment-transactions/reports?skip=0&take=25' \
     --header 'accept: application/json'
```
Tokens:
Raw