### Retrieve Listings with Query Parameters (PHP) Source: https://booking-api-docs.guesty.com/reference This PHP example uses cURL to send a GET request to the Guesty API. It constructs the URL with the specified query parameters (bedrooms, bathrooms, limit) and includes the 'accept' header to ensure a JSON response. ```php ``` -------------------------------- ### GET /v1/search Source: https://booking-api-docs.guesty.com/docs/quick-start Search for available listings based on various criteria. Requires an 'Authorization' header with a Bearer token. ```APIDOC ## GET /v1/search ### Description Search for available listings based on provided criteria. This endpoint requires an `Authorization` header with a valid Bearer token. ### Method GET ### Endpoint `https://booking-api.guesty.com/v1/search` ### Parameters #### Query Parameters - **checkIn** (string) - Optional - The check-in date in `YYYY-MM-DD` format. - **checkOut** (string) - Optional - The check-out date in `YYYY-MM-DD` format. - **guests** (integer) - Optional - The total number of guests. - **adults** (integer) - Optional - The number of adult guests. - **children** (integer) - Optional - The number of children guests. - **location** (string) - Optional - The desired location for the search. ### Request Example ```curl curl --location 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}' ``` ### Response *(Success response structure not detailed in provided text, but would typically include a list of matching listings.)* #### Success Response (200) *(Details not provided in the source text.)* #### Response Example *(Response example not provided in the source text.)* ``` -------------------------------- ### GET /listings/{listingId} Source: https://booking-api-docs.guesty.com/reference/getapplicationlisting Retrieves detailed information about a specific listing, including its amenities, pricing, and descriptions. ```APIDOC ## GET /listings/{listingId} ### Description Retrieves detailed information about a specific listing, including its amenities, pricing, and descriptions. ### Method GET ### Endpoint /listings/{listingId} ### Parameters #### Path Parameters - **listingId** (string) - Required - The unique identifier of the listing. #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) - **amenities** (array) - A list of amenities available at the property. - **bathrooms** (integer) - The number of bathrooms. - **bedrooms** (integer) - The number of bedrooms. - **beds** (integer) - The number of beds. - **bedType** (string) - The type of beds available. - **defaultCheckInTime** (string) - The default check-in time. - **defaultCheckOutTime** (string) - The default check-out time. - **pictures** (array) - An array of picture objects, each with different size variants and captions. - **prices** (object) - An object containing pricing details like base price, currency, and various fees. - **publicDescription** (object) - An object containing public descriptions and guest control settings. #### Response Example ```json { "amenities": [ "Wide hallway clearance", "Window guards", "Wireless Internet" ], "bathrooms": 2, "bedrooms": 3, "beds": 4, "bedType": "Queen", "defaultCheckInTime": "15:00", "defaultCheckOutTime": "11:00", "pictures": [ { "original": "http://example.com/original.jpg", "large": "http://example.com/large.jpg", "regular": "http://example.com/regular.jpg", "thumbnail": "http://example.com/thumbnail.jpg", "caption": "Living room" } ], "prices": { "basePrice": 150, "currency": "USD", "monthlyPriceFactor": 0.7, "weeklyPriceFactor": 0.9, "extraPersonFee": 20, "cleaningFee": 50, "petFee": 75 }, "publicDescription": { "guestControls": { "allowsChildren": true, "allowsInfants": true } } } ``` ``` -------------------------------- ### Get All Listings Source: https://booking-api-docs.guesty.com/docs/property-descriptions Retrieves a list of all listings available through the booking engine. This endpoint is useful for displaying a general overview of available properties. ```APIDOC ## GET /listings ### Description Retrieves a list of all listings included in the booking engine. ### Method GET ### Endpoint /listings ### Parameters #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) - **listings** (array) - An array of listing objects. - **listingId** (string) - The unique identifier for the listing. - **name** (string) - The name of the listing. - **summary** (string) - A brief summary of the listing. - **description** (string) - A detailed description of the listing's space and neighborhood. - **houseRules** (string) - The house rules for the listing. - **bedArrangements** (object) - Object containing the listing's space arrangements. #### Response Example { "listings": [ { "listingId": "123e4567-e89b-12d3-a456-426614174000", "name": "Cozy Beach House", "summary": "Beautiful beach house with ocean views.", "description": "A charming 3-bedroom house perfect for families, located steps from the beach.", "houseRules": "No smoking, pets allowed.", "bedArrangements": { "bedrooms": [ { "roomNumber": 1, "name": "Master Bedroom", "type": "bedroom", "beds": { "queen": 1 } } ] } } ] } ``` -------------------------------- ### Booking Engine Activation Source: https://booking-api-docs.guesty.com/docs/quick-start Steps required to activate the Booking Engine API for reservations, including manual source activation and initial API reservation. ```APIDOC ## Booking Engine Activation ### Description Before utilizing the Booking Engine (BE) API reservation endpoints, it must be activated. This involves activating the 'manual' source and then making an initial reservation using the BE API. ### Steps: 1. **Activate the manual source**: Create a direct booking from your Guesty dashboard. This activates the *manual* booking source. 2. **Activate the Booking Engine API source**: Make your first reservation using the BE API [Reservation quote](ref:reservation-quote-1) endpoints. This initializes the Booking Engine API source, enabling automations for additional fees, taxes, payment automations, and automated messages. ``` -------------------------------- ### Get Listing Availability Calendar Endpoint Source: https://booking-api-docs.guesty.com/reference/getcalendarbylistingid Defines the GET endpoint for retrieving a listing's availability calendar. Requires a listing ID, start date ('from'), and end date ('to') as query parameters. Returns an array of calendar items indicating availability status and minimum night requirements. ```json { "/api/listings/{listingId}/calendar": { "get": { "tags": [ "Listings" ], "summary": "Get listing availability calendar", "description": "Return a listing calendar for period", "operationId": "getCalendarByListingId", "parameters": [ { "name": "listingId", "in": "path", "description": "ID of listing to return", "required": true, "example": "5bf544a600a9b000389f81d8", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Begin of calendar form period in format YYYY-MM-DD", "required": true, "example": "2021-12-21", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "End of calendar form period in format YYYY-MM-DD", "required": true, "example": "2021-12-25", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json; charset=utf-8": { "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "minNights": { "type": "integer" }, "isBaseMinNights": { "type": "boolean" }, "status": { "type": "string", "enum": [ "available", "unavailable", "reserved", "booked" ] }, "cta": { "type": "boolean" }, "ctd": { "type": "boolean" } }, "x-readme-ref-name": "ListingCalendarItem" } } } } } } } } } ``` -------------------------------- ### Sample JSON response from listings API Source: https://booking-api-docs.guesty.com/docs/search-capabilities Example JSON response from the Guesty Booking API showing details of a single property including amenities, nightly rates, and availability. ```json { "results": [ { "_id": "636b996fe886d20053ec3f05", "nickname": "J-city", "title": "Un lives here", "type": "SINGLE", "bedrooms": 1, "accommodates": 7, "amenities": [ "Pets allowed", "Suitable for children (2-12 years)", "Suitable for infants (under 2 years)" ], "nightlyRates": { "2023-12-22": 1306, "2023-12-23": 1306, "2023-12-24": 777, "2023-12-25": 777, "2023-12-26": 777, "2023-12-27": 777 }, "allotment": { "2023-12-22": 1, "2023-12-23": 1, "2023-12-24": 1, "2023-12-25": 1, "2023-12-26": 1, "2023-12-27": 1 } } ], "pagination": { "total": 1, "cursor": { "next": "eyJuZXh0Q3Vyc29yIjp7Imxpc3RpbmdJZCI6IjYzNmI5OTZmZTg4NmQyMDA1M2VjM2YwNSJ9fQ==" } } } ``` -------------------------------- ### GET /api/metasearch/pointofsale/{pointofsale}/config Source: https://booking-api-docs.guesty.com/reference/getmetasearchconfig Retrieves the metasearch configuration for a specified point of sale. This endpoint is used to get the URL parameters required for metasearch engines. ```APIDOC ## GET /api/metasearch/pointofsale/{pointofsale}/config ### Description Retrieves the metasearch configuration for a specified point of sale. This endpoint is used to get the URL parameters required for metasearch engines. ### Method GET ### Endpoint /api/metasearch/pointofsale/{pointofsale}/config ### Parameters #### Path Parameters - **pointofsale** (string) - Required - possible variants of pointofsale - google #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) - **url** (string) - property page url defined based on metasearch requirements #### Response Example { "url": "https://test-url.com/properties/(PARTNER-HOTEL-ID)?minOccupancy=(NUM-GUESTS)&checkIn=(CHECKINYEAR)-(CHECKINMONTH)-(CHECKINDAY)&checkOut=(CHECKOUTYEAR)-(CHECKOUTMONTH)-(CHECKOUTDAY)&pointofsale=google" } #### Error Responses - **400** Bad request - **401** Not authorized - **429** Too many requests ``` -------------------------------- ### Retrieve Listings with Query Parameters (Node.js) Source: https://booking-api-docs.guesty.com/reference This Node.js example shows how to fetch listings from the Guesty API using the 'node-fetch' library. It sets up query parameters for bedrooms, bathrooms, and the result limit, along with the necessary 'accept' header for the API request. ```javascript import fetch from 'node-fetch'; const options = { method: 'GET', headers: { 'accept': 'application/json; charset=utf-8' } }; fetch('https://booking.guesty.com/api/listings?numberOfBedrooms=0&numberOfBathrooms=0&limit=20', options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` -------------------------------- ### Create Reservation Quote - Ruby Source: https://booking-api-docs.guesty.com/reference/reservation-quote-1 Example of creating a reservation quote using Ruby and the `net/http` library. Demonstrates sending a POST request with JSON data. ```Ruby require 'net/http' require 'json' uri = URI('https://booking.guesty.com/api/reservations/quotes') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Post.new(uri.path, {'Content-Type' => 'application/json'}) request.body = { guestsCount: 1 }.to_json response = http.request(request) puts response.body ``` -------------------------------- ### GET /api/listings Source: https://booking-api-docs.guesty.com/docs/average-review-score Retrieves the average review scores for all listings. It's recommended to include `_id`, `title`, and `reviews` in your fields to identify and get the review score for each listing. ```APIDOC ## GET /api/listings ### Description Retrieves the average review score for all listings. This endpoint allows you to fetch a comprehensive list of review statistics across multiple listings. ### Method GET ### Endpoint /api/listings ### Query Parameters #### Recommended Query Parameters - **_id** (string) - Required - The unique Guesty ID assigned to the listing. - **title** (string) - Required - The official name under which the listing is marketed. - **reviews** (object) - Required - The reviews object containing the average review score. - **avg** (float) - The average score. - **total** (integer) - The number of reviews received. ### Request Example ```json { "curl --location --request GET 'https://booking.guesty.com/api/listings?fields=_id title reviews' \ --header 'authorization: Bearer {{Token}}'" } ``` ### Response #### Success Response (200) - **_id** (string) - The unique Guesty ID of the listing. - **title** (string) - The official name of the listing. - **reviews** (object) - The reviews object containing the average review score. - **avg** (float) - The average score of the listing reviews (1-10). - **total** (integer) - The total number of reviews received for the listing. #### Response Example ```json { "listings": [ { "_id": "listing123", "title": "Cozy Beachfront Cottage", "reviews": { "avg": 9.5, "total": 50 } }, { "_id": "listing456", "title": "Downtown Loft with City View", "reviews": { "avg": 8.8, "total": 75 } } ] } ``` ``` -------------------------------- ### Example Reservation Quote Response - JSON Source: https://booking-api-docs.guesty.com/docs/new-reservation-creation-flow This is a sample JSON response from the create reservation quote API endpoint. It includes details like promotions, coupons, and rate plans with pricing information. ```JSON {\n "_id": "string",\n "createdAt": "2022-04-06T14:36:02.553Z",\n "expiresAt": "2022-04-06T14:36:02.553Z",\n "promotions": {\n "name": "string",\n "type": "string",\n "description": "string",\n "adjustment": 0\n },\n "coupons": [\n {.\n "name": "string",\n "type": "percentage",\n "code": "string",\n "adjustment": 0\n }\n ],\n "rates": {\n "ratePlans": [\n {.\n "_id": "string",\n "name": "string",\n "type": "string",\n "mealPlans": [\n "string"\n ],\n "cancellationPolicy": [\n "string"\n ],\n "cancellationFee": "string",\n "priceAdjustment": {\n "type": "string",\n "direction": "string",\n "amount": 0\n },\n "days": [\n {.\n "date": "2022-04-06",\n "price": 0,\n "currency": "string",\n "basePrice": 0,\n "rateStrategy": 0,\n "ratePlan": 0,\n "lengthOfStay": 0\n }\n ],\n "money": {\n "invoiceItems": [\n {.\n "title": "string",\n "amount": 0,\n "currency": "USD",\n "type": "string",\n "normalType": "string",\n "description": "string"\n }\n ],\n "_id": "string",\n "fareAccommodationAdjusted": 0,\n "currency": "USD",\n "fareAccommodation": 0,\n "fareCleaning": 0,\n "totalFees": 0,\n "subTotalPrice": 0,\n "hostPayout": 0,\n "hostPayoutUsd": 0,\n "totalTaxes": 0\n }\n }\n ]\n },\n "guestId": "string"\n} ``` -------------------------------- ### GET /api/listings/availability Source: https://booking-api-docs.guesty.com/reference/getavailablelistings Retrieves a list of available property listings based on specified date ranges and filtering criteria. This endpoint is deprecated and will be removed in upcoming months. Use the 'Get listings' endpoint instead to avoid missing any functionality. ```APIDOC ## GET /api/listings/availability ### Description Get a list of listings according to their availability on selected dates. This endpoint will be deprecated in the next months. We suggest using 'Get listings' endpoint instead (you won't have any capability missing). ### Method GET ### Endpoint /api/listings/availability ### Parameters #### Query Parameters - **minOccupancy** (integer) - Required - The minimum value of listing occupancy (default: 1) - **numberOfBedrooms** (integer) - Optional - The minimum amount of listing bedrooms (default: 0) - **numberOfBathrooms** (integer) - Optional - The minimum amount of listing bathrooms (default: 0) - **listingType** (string) - Optional - The listing type (enum: SINGLE, MTL) - **propertyType** (string) - Optional - The listing property type (enum: APARTMENT, HOUSE, LOFT, BOAT, CAMPER_RV, CONDOMINIUM, CHALET, BED_Breakfast, VILLA, TENT, OTHER, CABIN, TOWNHOUSE, BUNGALOW, HUT, DORM, PARKING_SPACE, PLANE, TREEHOUSE, YURT, TIPI, IGLOO, EARTH_HOUSE, ISLAND, CAVE, CASTLE, STUDIO) - **roomType** (string) - Optional - The listing room type. All values of roomType are defined in RoomTypesQueryParameter definition - **minPrice** (number) - Optional - Minimum value of listing price. Should be passed with currency query parameter - **maxPrice** (number) - Optional - Maximum value of listing price. Should be passed with currency query parameter - **currency** (string) - Optional - Listing price currency. Should be provided with minPrice query parameter - **includeAmenities** (string) - Optional - Listing amenities separated by comma which should have listings. All values of amenities query parameters are defined in AmenitiesQueryParameter definition ### Authentication Bearer token required ### Request Example ``` GET /api/listings/availability?minOccupancy=1&numberOfBedrooms=2&maxPrice=100¤cy=EUR ``` ### Response #### Success Response (200) Array of available listings with matching criteria #### Response Example { "listings": [ { "id": "listing_id", "title": "Beautiful Apartment", "minOccupancy": 1, "numberOfBedrooms": 2, "numberOfBathrooms": 1, "propertyType": "APARTMENT", "roomType": "PRIVATE_ROOM", "price": 75, "currency": "EUR", "availability": "available" } ] } ``` -------------------------------- ### GET /api/reviews Source: https://booking-api-docs.guesty.com/docs/guest-and-host-reviews This GET endpoint retrieves the review published for a specific stay. It supports querying by reservation ID, external reservation ID, or external review ID. The response includes detailed review data from the channel and Guesty-specific fields. ```APIDOC ## GET /api/reviews ### Description This endpoint retrieves the review published for a specific stay using various identifiers such as reservation ID, external reservation ID, or external review ID. ### Method GET ### Endpoint https://booking.guesty.com/api/reviews ### Parameters #### Path Parameters None #### Query Parameters - **reservationId** (string) - Optional - ID of the reservation. - **externalReservationId** (string) - Optional - Channel reservation ID. - **externalReviewId** (string) - Optional - Channel review ID. #### Request Body None ### Request Example ```curl curl --request GET \ --url 'https://booking.guesty.com/api/reviews?externalReviewId=test_2' \ --header 'Accept: application/json; charset=utf-8' \ --header 'authorization: Bearer ' ``` ### Response #### Success Response (200) - **data** (array) - Array of review objects, each containing review details such as IDs, timestamps, raw review content, and scoring. - **limit** (integer) - The limit applied to the query (default 100). - **skip** (integer) - The number of reviews skipped (pagination). #### Response Example ```json { "data": [ { "_id": "62d001c8f3a7c7ba7e016a0f", "externalReviewId": "test_2", "accountId": "5db59615f6fc3b001f8ee56f", "channelId": "bookingCom", "createdAt": "2022-07-14T12:00:38.000Z", "createdAtGuesty": "2022-07-14T11:38:27.934Z", "externalComplexId": "7254686", "externalListingId": "725468602", "externalReservationId": "3965817397", "guestId": "628e5f5c34afd40033be6e8f", "listingId": "5f9010ffccce44002ab01f5d", "rawReview": { "listingId": "6075ee4717dcf40032e650a0", "last_change_timestamp": "2022-07-14 12:31:12", "reservation_id": 3965817397, "content": { "positive": "Good location and generally well fitted out. Great having an en-suite for each bedroom.", "negative": "Property was not fully equipped for the number of guests, as I guess due to past breakages not being replaced, there were not enough crockery or glassware. This was addressed for the second night. The fan in the top bedroom did not work, nor the iron in the boiler cupboard or the USB ports on one of the sockets in the top bedroom. This was reported but not put right during our short stay. The shower in the top floor bedroom took a good while to start to flow properly and randomly cut out though other 2 showers were fine; maybe this was due to lack of pressure as this was the highest point in the building. This may seem a bit of a list but I include it so that both the management can deal with issues and future guests are warned.", "headline": "Generally a good experience and a comfortable place for a short break in a great city.", "language_code": "en-gb" }, "review_id": "EAZ_y__14JA", "url": "https://supply-xml.booking.com/review-api/properties/7254686/reviews/EAZ_y__14JA", "reviewer": { "is_genius": true, "country_code": "gb", "name": "Michael" }, "reply": null, "created_timestamp": "2022-07-14 12:00:38", "scoring": { "staff": 7.5, "comfort": 7.5, "review_score": 6, "location": 7.5, "value": null, "clean": 7.5, "facilities": 5 } }, "reservationId": "628e8209cf403a0035de866d", "updatedAt": "2022-07-14T12:31:12.000Z", "updatedAtGuesty": "2022-07-14T11:40:28.133Z", "reviewReplies": [] } ], "limit": 100, "skip": 0 } ``` ``` -------------------------------- ### Create Reservation API Request (Python) Source: https://booking-api-docs.guesty.com/reference/reservations-v1 A Python example for creating a reservation using the Guesty API. This code uses the 'requests' library to send a POST request to the reservations endpoint with the required headers and a sample JSON body. ```Python import requests import json def create_reservation(): url = "https://booking.guesty.com/api/reservations" headers = { "accept": "application/json; charset=utf-8", "content-type": "application/json" } payload = { "policy": { "privacy": { "isAccepted": True }, "termsAndConditions": { "isAccepted": True }, "marketing": { "isAccepted": True } } } try: response = requests.post(url, headers=headers, data=json.dumps(payload)) response.raise_for_status() # Raise an exception for bad status codes return response.json() except requests.exceptions.RequestException as e: print(f"Error creating reservation: {e}") # Handle specific error details if available in response.text # print(f"Response content: {e.response.text}") raise e # Example usage: # try: # reservation_data = create_reservation() # print(reservation_data) # except Exception as e: # print(f"Failed to create reservation.") ``` -------------------------------- ### Get Cities List - OpenAPI Definition Source: https://booking-api-docs.guesty.com/reference/getcities Defines the GET endpoint for retrieving a list of cities, including parameters for pagination and search. It specifies the request parameters, response structure for successful (200) and error (400, 401) scenarios. ```json { "openapi": "3.0.0", "info": { "description": "Booking Engine API", "version": "1.0", "title": "Booking Engine API" }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/listings/cities": { "get": { "tags": [ "Listings" ], "summary": "Get list of cities", "description": "Returns a list of all the cities countries and states related to the booking engine listings", "operationId": "getCities", "parameters": [ { "in": "query", "name": "skip", "description": "The number of cities to skip. Default value is 0", "example": 25, "schema": { "type": "integer", "minimum": 0 } }, { "in": "query", "name": "limit", "description": "Limit the number of results within a subset. Default value is 25, max value is 100", "example": 100, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "searchText", "description": "Search for given case insensitive text in city name", "example": "york", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "state": { "type": "string" } }, "x-readme-ref-name": "ListingsCitiesItem" } }, "count": { "type": "integer" }, "skip": { "type": "integer" }, "limit": { "type": "integer" } } } } } }, "400": { "description": "Bad request", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message", "data" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "requestId" ], "properties": { "requestId": { "type": "string" }, "moreDetails": { "type": "object" } } } }, "x-readme-ref-name": "ResponseErrorPayload" } }, "x-readme-ref-name": "BadRequest" } } } }, "401": { "description": "Not authorized", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message", "data" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object" } }, "x-readme-ref-name": "ResponseErrorPayload" } }, "x-readme-ref-name": "NotAuthorized" } } } } } } } } } ``` -------------------------------- ### Booking Options Source: https://booking-api-docs.guesty.com/docs/booking-flow Explains the different booking options available in Guesty's Booking Engine API, including 'Only inquiries', 'Only instant booking', and 'Both'. It details how each option affects reservation status and credit card token usage. ```APIDOC ## Booking Options ### Description This section details the configuration options for the Guesty Booking Engine API, which determine how guests can make reservations. Users must ensure their Guesty account is activated for the booking engine and that the selected booking option matches their desired checkout flow. ### Booking Engine Settings * **Only Inquiries**: Guests can place a booking request. Payment is handled manually after inquiry confirmation. Credit card token is not required. * **Only Instant Booking**: Guests can book available dates instantly. Credit card validation is required for confirmation. * **Both**: Allows for both inquiry and instant booking options. Guests can choose or the system can be configured. ### Payment Handling by Booking Option | Booking Option | Credit card token | Reservation status | | :------------------ | :---------------------------------- | :----------------- | | Only Inquiries | No | Reserved | | Only Instant book | Yes | Confirmed | | Both (Inquiry) | No | Reserved | | Both (Instant book) | Yes | Confirmed | **Note**: Reservations are processed regardless of payment method validity. ``` -------------------------------- ### Authorization hold payment policy example Source: https://booking-api-docs.guesty.com/docs/auto-payments Example JSON structure showing an authorization hold policy that captures 10% of reservation payout one hour before check-in. Contains schedule timing, charge type, and guest card usage configuration. ```json { "autoPayments": { "policy": [ { "scheduleTo": { "timeRelation": { "relation": "BEFORE", "unit": "HOURS", "amount": 1 }, "reservationEvent": "CHECK_IN" }, "_id": "64527886740d33005258ae80", "chargeType": "PERCENTAGE", "isAuthorizationHold": true, "useGuestCard": true, "amount": 10 } ] } } ``` -------------------------------- ### Using Access Tokens Source: https://booking-api-docs.guesty.com/docs/authentication-1 Details on how to use the obtained access token to authenticate subsequent API requests and best practices for managing token expiration and renewal. ```APIDOC ## Using Your Access Token ### Description Once you have obtained an `access_token`, you need to include it in the `Authorization` header of your subsequent Booking Engine API requests to authenticate them. The token expires every 24 hours and must be refreshed. ### Method All HTTP Methods (GET, POST, PUT, DELETE, etc.) ### Endpoint Any Booking Engine API endpoint ### Parameters #### Request Headers - **Authorization** (string) - Required - Must be in the format `Bearer YOUR_ACCESS_TOKEN`, where `YOUR_ACCESS_TOKEN` is the token obtained from the `/oauth2/token` endpoint. - **Accept** (string) - Optional - Typically `application/json`. - **Content-Type** (string) - Optional - Varies depending on the request body format (e.g., `application/json`, `application/x-www-form-urlencoded`). ### Request Example ```curl curl --location --request GET 'https://booking.guesty.com/api/v1/listings' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \ --header 'accept: application/json' ``` ### Best Practices - **Caching**: Cache the `access_token` and reuse it for multiple API requests within its validity period (24 hours). - **Token Refresh**: Refresh the token daily using your `client_id` and `client_secret` to avoid interruptions. - **Rate Limiting**: To avoid hitting rate limits on the authentication endpoint, refresh the token only once a day and cache it for subsequent requests. - **Expiration Management**: Store the `expires_in` value locally and implement logic to refresh the token before it expires. ``` -------------------------------- ### Retrieve upsell fees via cURL GET request Source: https://booking-api-docs.guesty.com/reference/upsell Executes a GET request to retrieve upsell fees from the Guesty API. Requires quoteId and listingId path parameters. The request includes an Accept header for JSON response. ```Shell curl --request GET \ --url https://booking.guesty.com/api/reservations/upsell/quoteId/listingId/fee \ --header 'accept: application/json; charset=utf-8' ``` -------------------------------- ### POST /reservations Source: https://booking-api-docs.guesty.com/reference/getapplicationreservation Creates a new reservation in the booking system. The endpoint accepts reservation details including guest information, pricing, and accommodation specifics. Returns the created reservation object on success or a 400 error for bad requests. ```APIDOC ## POST /reservations ### Description This endpoint creates a new reservation, capturing details like status, pricing, and invoice items. It is used for booking accommodations in the Guesty system. ### Method POST ### Endpoint /reservations ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **reservation** (object) - Required - Reservation details including id, status, etc. ### Request Example { "id": "string", "status": "string" } ### Response #### Success Response (200) - **id** (string) - Unique reservation ID - **status** (string) - Current status of the reservation - **pricing** (object) - Pricing details including total and host payout - **createdAt** (string, date-time) - Creation timestamp #### Response Example { "id": "res_123", "status": "confirmed", "pricing": { "total": 100.0, "currency": "USD", "hostPayout": 80.0 }, "createdAt": "2014-12-17T08:33:44.510Z" } #### Error Response (400) - **error** (object) - Error details with code, message, and data #### Error Response Example { "error": { "code": "string", "message": "Bad request", "data": { "requestId": "req_123" } } } ``` -------------------------------- ### GET /api/listings Source: https://booking-api-docs.guesty.com/reference Fetch listings that match the provided filter criteria, with pagination support. ```APIDOC ## GET /api/listings ### Description Retrieve a list of property listings filtered by various parameters such as number of bedrooms, bathrooms, and limit per page. Supports pagination via cursor. ### Method GET ### Endpoint /​api/​listings ### Parameters #### Query Parameters - **numberOfBedrooms** (integer) - Optional - Filter listings by minimum number of bedrooms. - **numberOfBathrooms** (integer) - Optional - Filter listings by minimum number of bathrooms. - **limit** (integer) - Optional (default 20) - Number of listings to return per page. - **cursor** (string) - Optional - Pagination cursor for fetching next page. #### Path Parameters None. #### Request Body None. ### Request Example ```json { "method": "GET", "url": "https://booking.guesty.com/api/listings?numberOfBedrooms=0&numberOfBathrooms=0&limit=20" } ``` ### Response #### Success Response (200) - **results** (array) - List of listings. - **pagination** (object) - Pagination information. #### Response Example ```json { "results": [ { "_id": "abc123", "type": "MTL", "propertyType": "Apartment", "roomType": "Entire home/apt", "title": "Cozy Downtown Apartment", "accommodates": 4, "address": { "street": "123 Main St", "city": "New York", "state": "NY", "zipcode": "10001", "country": "USA" }, "timezone": "America/New_York", "amenities": ["Wi-Fi", "Air Conditioning"], "bathrooms": 1, "bedrooms": 1, "beds": 2, "picture": { "original": "https://example.com/original.jpg", "large": "https://example.com/large.jpg", "regular": "https://example.com/regular.jpg", "thumbnail": "https://example.com/thumbnail.jpg", "caption": "Living room view" }, "prices": { "nightly": 120 }, "publicDescription": { "short": "A lovely apartment in the heart of the city." }, "reviews": { "rating": 4.5, "count": 10 }, "tags": ["wifi", "air conditioning"], "bedArrangements": { "beds": [ { "type": "Queen", "count": 1 } ] }, "unitTypeHouseRules": { "checkIn": "15:00", "checkOut": "11:00" } } ], "pagination": { "total": 150, "cursor": "eyJjcmVhdG9ycyI6IDgwfQ==" } } ``` ### Error Handling #### 400 Bad Request ```json { "error": { "code": "BadRequest", "message": "Invalid query parameters", "data": {} } } ``` #### 401 Not Authorized ```json { "error": { "code": "Unauthorized", "message": "Authentication required", "data": {} } } ``` #### 429 Too Many Requests ```json { "error": { "code": "TooManyRequests", "message": "Rate limit exceeded", "data": {} } } ``` ```