GUguesty
Listings

Create a listing

Changed on

Create a listing on your account. The address you supply is geocoded to resolve its coordinates. A new listing is unlisted until you publish it, and check-in and check-out default to 15:00 and 11:00 when defaultCheckInTime and defaultCheckOutTime are omitted.

post/listings

Request

  • Base URL
    https://open-api.guesty.com/v1
  • URL
    https://open-api.guesty.com/v1/listings
  • Auth
    API key in header authorization

Request body

titlestring required

Listing title. Must be 3-50 characters long

originstring

Marks the origin platform that the listing was migrated from

originIdstring

Marks the origin platform listing ID

accommodatesnumber

Maximum number of guests the listing accommodates. Defaults to 2.

bathroomsnumber float

Starting March 4th 2025, the bathroom field will be deprecated. Please use the Spaces endpoints to add and manage bathroom details moving forward.

minimumAgenumber

Minimum age required for the primary guest of a reservation at this listing.

timezonestring

IANA timezone identifier for the listing.

propertyType'Aparthotel' | 'Apartment' | 'Barn' | 'Bed & Breakfast' | 'Boat' | 'Boutique hotel' | 'Bungalow' | 'Cabin' | 'Camper/RV' | 'Casa particular (Cuba)' | 'Castle' | 'Cave' | 'Chalet' | 'Condominium' | 'Cottage' | 'Cycladic house (Greece)' | 'Dammuso' | 'Dome house' | 'Dorm' | 'Earth house' | 'Farm stay' | 'Guest suite' | 'Guesthouse' | 'Heritage hotel (India)' | 'Holiday home' | 'Hostel' | 'Hotel' | 'House' | 'Houseboat' | 'Hut' | 'Igloo' | 'In-law' | 'Inn' | 'Island' | 'Lighthouse' | 'Loft' | 'Minsu' | 'Nature lodge' | 'Other' | 'Parking Space' | 'Pension (South Korea)' | 'Plane' | 'Resort' | 'Rv' | 'Ryokan (Japan)' | 'Serviced apartment' | 'Shepherds hut' | 'Studio' | 'Tent' | 'Timeshare' | 'Tiny house' | 'Tipi' | 'Townhouse' | 'Train' | 'Treehouse' | 'Trullo (Italy)' | 'Vacation home' | 'Villa' | 'Windmill' | 'Yurt'

Describes the kind of property where your guest will stay (e.g., Apartment, House, Villa, Boat, Tent, etc.). Corresponds to the Property type in the UI

roomType'Entire home/apt' | 'Private room' | 'Shared room'

Indicates the level of privacy your guest will have during their stay (e.g., Entire home/apt, Private room, or Shared room). Corresponds to the Listing type in the UI

otaRoomType'Apartment' | 'Bed in dormitory' | 'Bungalow' | 'Chalet' | 'Dormitory room' | 'Double' | 'Family' | 'Holiday home' | 'Mobile home' | 'Quadruple' | 'Single' | 'Studio' | 'Suite' | 'Tent' | 'Triple' | 'Twin' | 'Villa'

A Booking.com-specific field that defines either the property type or room capacity, depending on whether the stay is in a full unit or a single-room setup (e.g., Suite, Double, Villa, Bed in dormitory). Corresponds to the Room type in the UI

defaultCheckInTimestring

Default check-in time for reservations at this listing, in HH:mm format.

defaultCheckOutTimestring

Default check-out time for reservations at this listing, in HH:mm format.

type'SINGLE' | 'MTL' required

Listing type

tagsstring[]

Array of free-text tags associated with the listing.

nicknamestring required

Listing nickname. Must be 1-20 characters long.

amenitiesstring[]

Array of amenity names available at the listing. Manage amenities via the Amenities endpoints.

manageSubunitPicturesboolean

Whether pictures are managed at the sub-unit level for multi-unit (MTL) listings. Set as true for the sub-units to inherit the multi-unit's pictures, or false to manage the pictures on the unit level.

isListedboolean

Whether the listing is published and visible.

numberOfChildrenToCreatenumber

Number of child/sub-unit listings to create when creating a multi-unit (MTL) listing.

isTestboolean

Marks the listing as a test property. Test property titles must include the 'Test_' prefix. Only SINGLE-type listings can be selected.

Example request

{
  "address": {
    "full": "Kaplan St 2, Ramat Gan, Israel",
    "lng": 34.8202173,
    "lat": 32.0695525
  },
  "title": "Example listing title",
  "origin": "company_name",
  "originId": "67890234",
  "prices": {
    "guestsIncludedInRegularFee": 6,
    "extraPersonFee": 55.5,
    "monthlyPriceFactor": 0.9,
    "weeklyPriceFactor": 0.9,
    "weekendBasePrice": 150,
    "securityDepositFee": 100,
    "cleaningFee": 50
  },
  "terms": {
    "minNights": 1,
    "maxNights": 30,
    "cancellation": "STANDARD"
  },
  "pictures": [
    {
      "thumbnail": "https://res.cloudinary.com/guesty/image/upload/c_fit,h_200/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
      "large": "https://res.cloudinary.com/guesty/image/upload/c_fit,w_756/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
      "caption": "Living room",
      "height": 756,
      "original": "https://res.cloudinary.com/guesty/image/upload/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
      "size": 39516,
      "width": 756
    }
  ],
  "pms": {
    "cleaningStatus": {
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  },
  "mtl": {
    "aas": "bc",
    "aao": "f",
    "bc": 3
  }
}

Response

Listing

_idstring

Unique Guesty listing ID.

accountIdstring

Unique Guesty account ID.

createdAtstring
isVirtualboolean
nicknamestring
tagsstring[]
isListedboolean
titlestring
propertyTypestring
roomTypestring
bedTypestring
accommodatesnumber
bedroomsnumber
areaSquareFeetnumber
timezonestring
defaultCheckInTimestring
defaultCheckOutTimestring
amenitiesstring[]

Array of amenities. Use the amenities endpoints to review and manage this list.

amenitiesNotIncludedstring[]

Array of amenities not included. Use the amenities endpoints to review and manage this list.

netIncomeFormulastring
commissionFormulastring
commissionTaxPrecentagestring
activeboolean
customFieldsobject
calendarRulesobject
publicDescriptionobject
privateDescriptionobject
markupsobject
isTestboolean

Marks the listing as a test property. Test property titles must include the 'Test_' prefix. Only SINGLE-type listings can be selected.

Example response

{
  "_id": "59ac245d27cb310f0017afe3",
  "accountId": "59ac245d27cb310f0017afe3",
  "createdAt": "2017-09-03T15:48:45.070Z",
  "integrations": [
    {
      "_id": "5958c7e5884e961000817799",
      "airbnb2": {
        "ignored": {
          "reservations": [],
          "listings": []
        },
        "emailsFromSupport": []
      },
      "nickname": "naama",
      "id": "naama@user.guesty.com",
      "userId": "563e0b6a08a2710e00057b85",
      "accountId": "563e0b6a08a2710e00057b82"
    }
  ],
  "address": {
    "full": "Kaplan St 2, Ramat Gan, Israel",
    "lng": 34.8202173,
    "lat": 32.0695525
  },
  "publishedAddress": {
    "full": "Kaplan St 2, Ramat Gan, Israel",
    "lng": 34.8202173,
    "lat": 32.0695525
  },
  "cleaningStatus": {
    "updatedAt": "2019-08-24T14:15:22Z"
  },
  "picture": {
    "thumbnail": "https://res.cloudinary.com/guesty/image/upload/c_fit,h_200/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
    "large": "https://res.cloudinary.com/guesty/image/upload/c_fit,w_756/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
    "caption": "Living room",
    "height": 756,
    "original": "https://res.cloudinary.com/guesty/image/upload/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
    "size": 39516,
    "width": 756
  },
  "pictures": [
    {
      "thumbnail": "https://res.cloudinary.com/guesty/image/upload/c_fit,h_200/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
      "large": "https://res.cloudinary.com/guesty/image/upload/c_fit,w_756/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
      "caption": "Living room",
      "height": 756,
      "original": "https://res.cloudinary.com/guesty/image/upload/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
      "size": 39516,
      "width": 756
    }
  ],
  "terms": {
    "minNights": 1,
    "maxNights": 30,
    "cancellation": "STANDARD"
  },
  "prices": {
    "guestsIncludedInRegularFee": 6,
    "extraPersonFee": 55.5,
    "monthlyPriceFactor": 0.9,
    "weeklyPriceFactor": 0.9,
    "weekendBasePrice": 150,
    "securityDepositFee": 100,
    "cleaningFee": 50
  },
  "pms": {
    "cleaningStatus": {
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  }
}

Changes

  • 3122b8618183Revision changes
    • breaking

      added subschema #1 to the request property allOf list

    • breaking

      added subschema #1 to the request property allOf list

    • breaking

      added subschema #1 to the request property allOf list

    • breaking

      added subschema #1 to the request property allOf list

    • breaking

      added subschema #1 to the request property allOf list

    • breaking

      removed subschema #1 subschema #2 from the / request property oneOf list

    • breaking

      added the pattern ^([01]\d|2[0-3]):([0-5]\d)$ to the request property

    • breaking

      added the pattern ^([01]\d|2[0-3]):([0-5]\d)$ to the request property

    • breaking

      the request property format changed from no format to int32

    • breaking

      the request property type changed from object to no type

    • breaking

      the request property format changed from no format to float

    • breaking

      the request property format changed from no format to int32

    • breaking

      the request property type changed from object to no type

    • breaking

      the request property format changed from no format to int32

    • breaking

      the // request property format changed from no format to int32

    • breaking

      the // request property format changed from no format to uri

    • breaking

      the // request property format changed from no format to uri

    • breaking

      the // request property format changed from no format to int32

    • breaking

      the // request property format changed from no format to uri

    • breaking

      the // request property format changed from no format to int32

    • breaking

      the request property type changed from object to no type

    • breaking

      the request property type changed from object to no type

    • breaking

      the request property type changed from object to no type

    • breaking

      the // response's property type changed from integer to string for status

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • info

      api operation id propertiesListingCreate was added

    • info

      added subschema #1 subschema #2 to the / request property oneOf list

    • info

      added the optional property to the response with the status

    • info

      the / response's property pattern ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$ was added for the status