Create a Property
How to create a listing in Guesty.
Important
Properties are automatically created as active (
"pms.active": trueand"active": true).
Overview
To create listings via the API, you must make requests to multiple endpoints, such as listings, spaces, house-rules and complex. This guide provides you with the recommended parameters to include to create the property in Guesty. Booking settings and policies, marketing descriptions, financial strategies, and automation should be configured via updates through their respective endpoints. For information about key parameters from a specific endpoint, please refer to its respective documentation.
Creating a Property
Available Endpoints
| Method | Endpoint |
|---|---|
| POST | /listings |
Key Parameters
The complete list of parameters can be found in the developer document. The parameters below represent Guesty's recommendations for creating the base listing structure you will enhance later.
| Body Parameter | Type | Description | Required |
|---|---|---|---|
title | string | The name used to market the property. | |
nickname | string | The internal name for the property. | ✔️ |
address | object | The street location of the property. See the Create a Property section below. | ✔️ |
prices | object | The basic fees. See the Prices table below. | |
terms | object | Defines the permitted stay lengths and default cancelation policy. See below for more details. | |
pictures | [object] | Property photos. Upload five, including at least one interior and exterior picture. See the Pictures section below. | |
type | string | Define the property as a SINGLE property or Multi-Unit (MTL) - see the Multi-Units section below. | |
accommodates | number | The total number of people the property can accommodate. | |
roomType | string | This correlates with the Listing type field of the property's details settings on the FE. Choose from three options: Entire home/apartment, Shared room, or Private room. | |
propertyType | string | This correlates with the Property type field of the property's details settings on the FE. Choose from: Condominium, Apartment, House, Loft, Boat, Camper/RV, Condominium, Chalet, Bed & Breakfast, Villa, Tent, Cabin, Townhouse, Bungalow, Hut, Dorm, Parking Space, Plane, Treehouse, Yurt, Tipi, Igloo, Earth House, Island, Cave, Castle, Studio, or Other. | |
otaRoomType | string | This correlates with the Room type field in the property's details settings on the FE. Select from the following: apartment, suite, studio, family, dormitory_room, bungalow, chalet, holiday_home, villa, mobile_home, or tent. This is required for Booking.com only. | |
defaultCheckInTime | string | The default is 15:00. Only include it if you wish to specify a different time (Hh:mm). | |
defaultCheckoutTime | string | The default is 11:00. Only include it if you wish to specify a different time ((Hh:mm). | |
amenities | [string] | This is a list of the amenities provided at the property. Choose from this list. | |
areaSquareFeet | number | Specify the size of the property. | |
timezone | string | Select the relevant value from this list. E.g., "America/Cancun". | |
isListed | boolean | Enter true to make it visible to the market, or false to hide it from the marketplace. | |
minimumAge | number | The minimum age the guest needs to be to book the property. E.g., 21. |
Property Address
To provide us with your address, simply enter any complete street address into the full field. The data will automatically be parsed into the remaining fields. However, if you encounter any issues with the address, you may consider entering the address data into the individual address fields shown below in addition to thefull address.
| Body Parameter | Type | Description | Required |
|---|---|---|---|
full | string | The whole street address. | ✔️ |
lng | number | The longitude of the location. It must be entered in decimal format. | recommended |
lat | number | The latitude of the location. It must be entered in decimal format. | recommended |
street | string | The street name and number. | recommended |
city | string | The name of the city the property is located in. This value is used in the city filters wherever they appear in Guesty. | recommended |
zipcode | string | The zipcode/postcode. | recommended |
state | string | The state within which the property is located. | recommended |
country | string | The country within which the property is located. | recommended |
Example
"address": {
"full": "<string>",
"lng": <number>, // Thelongitude coordinate in decimal.
"lat": <number>, // The latitude coordinate in decimal.
"street": "<string>",
"city": "<string>",
"state": "<string>",
"zipcode": "<string>",
"country": "<string>"
}
Prices
| Body Parameter | Type | Description | Required |
|---|---|---|---|
basePrice | number | The default rate per night. This will apply to the weekend if no weekend price is defined. | ✔️ |
basePriceUSD | number | The default US dollar rate per night. | |
currency | string | The currency to be used for bookings at the property. Choose from this list of ISO 4217 alphabetic codes. E.g., USD. | ✔️ |
weekendBasePrice | number | The default weekend rate per night. | |
cleaningFee | number | The price charged to the guest for cleaning the property between stays. | |
securityDepositFee | number | Set the security deposit for the property. | |
guestsIncludedInRegularFee | number | The number of guests covered by the price. | |
extraPersonFee | number | The fee charged for guests above the number included in the price. | |
monthlyPriceFactor | number | The monthly length of stay discount. It is written as a decimal and represented as 100% less the discount. E.g.,0.8 grants a 20% discount. | |
weeklyPriceFactor | number | The weekly length of stay discount. It is written as a decimal and represented as 100% less the discount. E.g. 0.95 grants a 5% discount. |
Terms
| Body Parameter | Type | Description | Required |
|---|---|---|---|
minNight | number | The default minimum stay length. | |
maxNights | number | The maximum length of stay that can be booked. |
Example
"terms": {
"minNights": <number>,
"maxNights": <number>,
}
Pictures
Photos
Including a minimum of five photos, with at least one showing the interior and exterior, can help avoid Trust and Safety suspensions on booking channels. Listings with few photos that don't display both views are more likely to be flagged.
| Body Parameter | Type | Description | Required |
|---|---|---|---|
original | string | The URL for accessing the original image. | ✔️ |
thumbnail | string | The URL for accessing the thumbnail image. The recommended height for the image is 200 pixels. Guesty will scale the width proportionally. | ✔️ |
caption | string | Add a caption to describe the photo. | recommended |
Example
"pictures": [
{
"original": "<URL>",
"caption": "<string>",
}
]
Optional Parameters
| Body Parameter | Type | Description |
|---|---|---|
origin | string | Include if you need to record the platform from which the listing was migrated. |
originID | string | The property ID from the platform it was previously migrated from. |
Put this all together, and your request should resemble this example:
curl 'https://open-api.guesty.com/v1/v1/listings' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer <accessToken>' \
--data '{
"title": "<string>",
"nickname": "<string>",
"isListed": <boolean>,
"timezone": "<string>",
"address": {
"full": "<string>",
"lat": <number>,
"lng": <number>,
"street": "<string>",
"city": "<string>",
"zipcode": "<string>",
"state": "<string>",
"country": "<string>"
},
"prices": {
"guestsIncludedInRegularFee": <integer>,
"extraPersonFee": <number>,
"basePrice": <number>,
"basePriceUSD": <number>,
"monthlyPriceFactor": <number>,
"weeklyPriceFactor": <number>,
"weeendBasePrice": <number>,
"securityDepositFee": <number>,
"currency": "<string>",
"cleaningFee": <number>
},
"terms": {
"minNights": <number>,
"maxNights": <number>
},
"pictures": [
{
"original": "<URL>",
"caption": "<string>"
},
{
"original": "<URL>",
"caption": "<string>"
},
{
"original": "<URL>",
"caption": "<string>"
},
{
"original": "<URL>",
"caption": "<string>"
},
{
"original": "<URL>",
"caption": "<string>"
}
],
"type": "<enum>",
"accommodates": <number>,
"otaRoomType": "<enum>",
"minimumAge": <number>,
"propertyType": "<enum>",
"roomType": "<enum>",
"defaultCheckInTime": "<string>",
"defaultCheckOutTime": "<string>",
"areaSquareFeet": <number>,
"amenities": [
"<string>",
"<string>",
"<etc.>"
],
"origin": "<string>",
"originId": "<string>"
}'
const myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");
myHeaders.append("Authorization", "Bearer {accessToken}");
const raw = "{\n \"title\": \"<string>\",\n \"nickname\": \"<string>\",\n \"isListed\": <boolean>,\n \"timezone\": \"<string>\",\n \"address\": {\n \"full\": \"<string>\",\n \"lat\": <number>,\n \"lng\": <number>,\n \"street\": \"<string>\",\n \"city\": \"<string>\",\n \"zipcode\": \"<string>\",\n \"state\": \"<string>\",\n \"country\": \"<string>\"\n },\n \"prices\": {\n \"guestsIncludedInRegularFee\": <integer>,\n \"extraPersonFee\": <number>,\n \"basePrice\": <number>,\n \"basePriceUSD\": <number>,\n \"monthlyPriceFactor\": <number>,\n \"weeklyPriceFactor\": <number>,\n \"weeendBasePrice\": <number>,\n \"securityDepositFee\": <number>,\n \"currency\": \"<string>\",\n \"cleaningFee\": <number>\n },\n \"terms\": {\n \"minNights\": <number>,\n \"maxNights\": <number>\n },\n \"pictures\": [\n {\n \"original\": \"<URL>\",\n \"caption\": \"<string>\"\n },\n {\n \"original\": \"<URL>\",\n \"caption\": \"<string>\"\n },\n {\n \"original\": \"<URL>\",\n \"caption\": \"<string>\"\n },\n {\n \"original\": \"<URL>\",\n \"caption\": \"<string>\"\n },\n {\n \"original\": \"<URL>\",\n \"caption\": \"<string>\"\n }\n ],\n \"type\": \"<enum>\",\n \"accommodates\": <number>,\n \"otaRoomType\": \"<enum>\",\n \"minimumAge\": <number>,\n \"propertyType\": \"<enum>\",\n \"roomType\": \"<enum>\",\n \"defaultCheckInTime\": \"<string>\",\n \"defaultCheckOutTime\": \"<string>\",\n \"areaSquareFeet\": <number>,\n \"amenities\": [\n \"<string>\",\n \"<string>\",\n \"<etc.>\"\n ],\n \"origin\": \"<string>\",\n \"originId\": \"<string>\"\n}";
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "manual"
};
fetch("https://open-api.guesty.com/v1/v1/listings", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://open-api.guesty.com/v1/v1/listings',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"title": "<string>",
"nickname": "<string>",
"isListed": <boolean>,
"timezone": "<string>",
"address": {
"full": "<string>",
"lat": <number>,
"lng": <number>,
"street": "<string>",
"city": "<string>",
"zipcode": "<string>",
"state": "<string>",
"country": "<string>"
},
"prices": {
"guestsIncludedInRegularFee": <integer>,
"extraPersonFee": <number>,
"basePrice": <number>,
"basePriceUSD": <number>,
"monthlyPriceFactor": <number>,
"weeklyPriceFactor": <number>,
"weeendBasePrice": <number>,
"securityDepositFee": <number>,
"currency": "<string>",
"cleaningFee": <number>
},
"terms": {
"minNights": <number>,
"maxNights": <number>
},
"pictures": [
{
"original": "<URL>",
"caption": "<string>"
},
{
"original": "<URL>",
"caption": "<string>"
},
{
"original": "<URL>",
"caption": "<string>"
},
{
"original": "<URL>",
"caption": "<string>"
},
{
"original": "<URL>",
"caption": "<string>"
}
],
"type": "<enum>",
"accommodates": <number>,
"otaRoomType": "<enum>",
"minimumAge": <number>,
"propertyType": "<enum>",
"roomType": "<enum>",
"defaultCheckInTime": "<string>",
"defaultCheckOutTime": "<string>",
"areaSquareFeet": <number>,
"amenities": [
"<string>",
"<string>",
"<etc.>"
],
"origin": "<string>",
"originId": "<string>"
}',
CURLOPT_HTTPHEADER => array(
'accept: application/json',
'content-type: application/json',
'Authorization: Bearer {accessToken}'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import http.client
import json
conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = "{\n \"title\": \"<string>\",\n \"nickname\": \"<string>\",\n \"isListed\": <boolean>,\n \"timezone\": \"<string>\",\n \"address\": {\n \"full\": \"<string>\",\n \"lat\": <number>,\n \"lng\": <number>,\n \"street\": \"<string>\",\n \"city\": \"<string>\",\n \"zipcode\": \"<string>\",\n \"state\": \"<string>\",\n \"country\": \"<string>\"\n },\n \"prices\": {\n \"guestsIncludedInRegularFee\": <integer>,\n \"extraPersonFee\": <number>,\n \"basePrice\": <number>,\n \"basePriceUSD\": <number>,\n \"monthlyPriceFactor\": <number>,\n \"weeklyPriceFactor\": <number>,\n \"weeendBasePrice\": <number>,\n \"securityDepositFee\": <number>,\n \"currency\": \"<string>\",\n \"cleaningFee\": <number>\n },\n \"terms\": {\n \"minNights\": <number>,\n \"maxNights\": <number>\n },\n \"pictures\": [\n {\n \"original\": \"<URL>\",\n \"caption\": \"<string>\"\n },\n {\n \"original\": \"<URL>\",\n \"caption\": \"<string>\"\n },\n {\n \"original\": \"<URL>\",\n \"caption\": \"<string>\"\n },\n {\n \"original\": \"<URL>\",\n \"caption\": \"<string>\"\n },\n {\n \"original\": \"<URL>\",\n \"caption\": \"<string>\"\n }\n ],\n \"type\": \"<enum>\",\n \"accommodates\": <number>,\n \"otaRoomType\": \"<enum>\",\n \"minimumAge\": <number>,\n \"propertyType\": \"<enum>\",\n \"roomType\": \"<enum>\",\n \"defaultCheckInTime\": \"<string>\",\n \"defaultCheckOutTime\": \"<string>\",\n \"areaSquareFeet\": <number>,\n \"amenities\": [\n \"<string>\",\n \"<string>\",\n \"<etc.>\"\n ],\n \"origin\": \"<string>\",\n \"originId\": \"<string>\"\n}"
headers = {
'accept': 'application/json',
'content-type': 'application/json',
'Authorization': 'Bearer {accessToken}'
}
conn.request("POST", "/v1/v1/listings", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
The response will return a status 200 OK with the listing object as its payload.
Multi-Units
When creating a new multi-unit, include the following additional parameters in your request.
| Body Parameter | Type | Description | Required | |
|---|---|---|---|---|
numberOfChildrenToCreate
|
number | The amount of sub-units to create. | ||
manageSubunitPictures
|
boolean |
Set as true for the sub-units to inherit the multi-unit's
pictures, or false to manage the pictures on the unit
level.
|
||
mtl |
object | The multi-unit management settings. | ||
| aas | string |
When to assign a reservation to a unit. It can be one of the following:
oc (on create), m (manual), or
bc (before check-in).
|
||
| aao | string |
Defines the automatic assignment rules for the selected multi-unit - it
is not relevant for listings that have manual assignment logic ("aas": "m"). It must be one of the following: f (first free by
unit's nickname), r (randomly), or fu (evenly- to a unit with the lowest occupancy rate).
|
||
| bc | number |
When "aas": "bc", set the number of days before check-in to
assign the reservation to a unit.
|
||
| hdb4 | number | Defines the number of days before check-in to highlight unassigned upcoming reservations on the multi-calendar. | ||
| lmcn | boolean |
When true it limits availability to match consecutive
available nights for a specific sub-unit, else it will be calculated
according to the number of vacant sub-units (false).
|
||
Example
{ ...
"mtl":{
"aas":"bc",
"aao":"f",
"bc":14,
"hdb4":14,
"lmcn":true
},
"numberOfChildrenToCreate":5,
"manageSubunitPictures":true
...
}
Complexes
A complex is a hotel-like property with different types of listings at the same address. It is a holding structure within minimal parameters. A complex can be comprised of single-units, multi-units, or both.
While some channels require listings to be set up as complexes, you may decide to utilize this listing type to organize your listings in Guesty. Learn more here.
Create a Complex
First, create the complex's properties according to the recommendations in the Create a Property section. Afterward, Create the complex and assign the properties to the complex.
Updated about 2 months ago