Skip to main content

Rentals

Overview​

This resource represents Rentals which are the actual properties that are the subject of most actions in the BookingSync ecosystem.

Parameters​

NameTypeRead/WriteDescription
accountIntegerReadAccount's ID related to the Rental
availabilityIntegerReadAvailability's ID related to the Rental
change_overIntegerReadChangeOver's ID related to the Rental
destinationIntegerReadDestination's ID related to the Rental
payment_gatewayIntegerReadPayment Gateway's ID related to the Rental (requires preferences_payments_read scope)
rates_tableIntegerReadRates Table's ID related to the Rental
rental_agreementIntegerReadRental Agreement's ID related to the Rental
rental_cancelation_policyIntegerReadRental Cancelation Policy's ID related to the Rental
nightly_rate_mapIntegerReadNightly Rate Map's ID related to the Rental
mid_term_rate_mapIntegerReadMid Term Rate Map's ID related to the Rental
photosArrayReadPhotos' IDs related to the Rental
reviewsArrayReadReviews' IDs related to the Rental
host_reviewsArrayReadHost Reviews' IDs related to the Rental
special_offersArrayReadSpecial Offers' IDs related to the Rental
ratesArrayReadRates' IDs related to the Rental
rentals_amenitiesArrayReadRentals Amenities' IDs related to the Rental
rentals_feesArrayReadRentals Fees' IDs related to the Rental
bathroomsArrayReadBathrooms' IDs related to the Rental
bedroomsArrayReadBedrooms' IDs related to the Rental
living_roomsArrayReadLiving Rooms' IDs related to the Rental
rentals_tagsArrayReadRentals Tags' IDs related to the Rental
rental_contactsArrayReadRental Contacts' IDs related to the Rental
videosArrayReadVideos' IDs related to the Rental
idIntegerReadRental's ID.
absolute_min_priceDecimalReadRental's minimum price based on base_rate_kind.
base_rateDecimalReadRental's base rate, used by the rates table to calculate the seasonability and discounted prices. We recommend using the highest price as base rate.
base_rate_kindStringReadRental's rate type attached to the base rate. List of types described in enums section.
balance_dueIntegerReadNumber of day since the booking confirmation to collect the full booking price.
bathrooms_countIntegerReadRental's bathrooms count.
bedrooms_countIntegerReadRental's bedrooms count.
bookable_onlineBooleanReadRental's online booking status.
checkin_typeStringReadRental's checkin type, list of values described in enums section.
checkin_timeIntegerReadRental's checkin time.
checkin_end_timeIntegerReadRental's checkin end time.
checkout_timeIntegerReadRental's checkout time.
cityStringReadRental's city.
contact_nameStringReadRental's contact name.
country_codeStringReadRental's country code, list of codes is available at wikipedia.
currencyStringReadRental's currency code, list of codes described in enums section.
damage_depositDecimalReadRental's required damage deposit.
charge_damage_deposit_on_arrivalBooleanReadRental's charge damege deposit on arrival status. Can be true or false for Pro subscriptions, only false allowed for Service subscriptions when damage_deposit_collection_method is "smily_damage_deposit_with_swikly", and only true allowed for Service subsriptions when damage_deposit_collection_method is "with_smily"
damage_deposit_collection_methodStringReadRental's damage deposit collection method. List of values described in enums section.
damage_deposit_external_collection_method_nameStringReadDamage deposit collection method name (in case damage_deposit_collection_method is "external").
descriptionObjectReadRental's description, list of locales described in enums section.
downpaymentIntegerReadRental's default downpayment percentage. If none defined, the default downpayment percentage of the account will be used.
final_priceIntegerReadRental's final price (after discount). Available only for a search query with valid dates, for other cases please refer to base_rate and base_rate_kind.
floorStringReadRental's floor
headlineObjectReadRental's headline, list of locales described in enums section.
initial_priceIntegerReadRental's initial price. Available only for a search query with valid dates, for other cases please refer to base_rate and base_rate_kind.
latFloatReadRental's latitude.
lngFloatReadRental's longitude.
max_priceDecimalReadRental's maximum weekly or nightly price, depending on the base_rate_kind.
mid_term_pricing_activeBooleanReadEnable mid term pricing feature for the rental.
min_priceDecimalReadRental's minimum weekly or nightly price, depending on the base_rate_kind.
nameStringReadRental's name.
nightly_rates_managed_externallyBooleanReadDefines whether nightly_rate_map can be updated via API. Defaults to false.
permit_issue_dateTimeReadRental's Registration/License/Permit number's issue date.
permit_numberStringReadRental's Registration/License/Permit number.
positionIntegerReadRental's position on the list.
price_public_notesObjectReadRental's price notes for public, list of locales described in enums section.
rental_typeStringReadRental's type (example: villa, apartment), all types described in enums section.
reviews_average_ratingDecimalReadRental's overall rating from reviews.
reviews_countIntegerReadRental's count of all reviews.
rounding_kindStringReadRounding kind for initial_price. All the possible values described at enums section
sleepsIntegerReadRental's number of comfortable sleeps.
sleeps_maxIntegerReadRental's maximum number of sleeps.
stateStringReadRental's state.
stories_countIntegerReadRental's number of stories.
summaryObjectReadRental's summary, list of locales described in enums section.
surfaceIntegerReadRental's surface area.
surface_unitStringReadRental's surface area unit, either metric or imperial.
website_urlObjectReadRental's primary website url, list of locales described in enums section.
residency_categoryStringReadRental's residency category. All types are described in enums section
certificationsObjectReadRental's certifications, all allowed values described in enums section.
management_typeStringReadRental's management type. All types are described in enums section
bookable_on_requestBooleanReadRental's Bookable on request status (requires Rental to be published and Account needs a configuration for contract management)
instantly_bookableBooleanReadRental's instantly bookable status (requires Rental to be bookable on request, bookable_online to be set to true and Rental needs to have a Payment Gateway configured)
full_bathrooms_countIntegerReadRental's full bathrooms count
standalone_toilets_countIntegerReadRental's standalone toilets count
vr_bathrooms_countFloat/IntegerReadRental's VR bathrooms count (Float is possible only if there are standalone Bathrooms as the value equal to: bathrooms_count - standalone_toilets_count + 0.5 will be returned, otherwise bathrooms_count will be returned as an Integer)
absolute_min_stayIntegerReadRental's absolute minimum stay
public_notesStringReadRental's public notes
refund_damage_deposit_afterIntegerReadRental's refund damage deposit after value (in days)
created_atTimeReadRental's create time.
updated_atTimeReadRental's update time.
published_atTimeReadRental's publish time.

Check-in Type​

The check-in type defines how guests can check in to the rental. This can be one of the following values:

  • meetup - The guest needs to meet the host or a representative to check in
  • self - Self check-in is available (lockbox, keypad, etc.)
  • managed - Check-in is managed by a third-party service

List rentals​

List all rentals for a given account(s).

GET /rentals
response.json
{
  "links": {
    "rentals.account": "https://www.bookingsync.com/api/v3/accounts/{rentals.account}",
    "rentals.availability": "https://www.bookingsync.com/api/v3/availabilities/{rentals.availability}",
    "rentals.destination": "https://www.bookingsync.com/api/v3/destinations/{rentals.destination}",
    "rentals.rates_table": "https://www.bookingsync.com/api/v3/rates_tables/{rentals.rates_table}",
    "rentals.rental_agreement": "https://www.bookingsync.com/api/v3/rental_agreements/{rentals.rental_agreement}",
    "rentals.rental_cancelation_policy": "https://www.bookingsync.com/api/v3/rental_cancelation_policies/{rentals.rental_cancelation_policy}",
    "rentals.photos": "https://www.bookingsync.com/api/v3/photos/{rentals.photos}",
    "rentals.reviews": "https://www.bookingsync.com/api/v3/reviews/{rentals.reviews}",
    "rentals.special_offers": "https://www.bookingsync.com/api/v3/special_offers/{rentals.special_offers}",
    "rentals.rates": "https://www.bookingsync.com/api/v3/rates/{rentals.rates}",
    "rentals.rentals_amenities": "https://www.bookingsync.com/api/v3/rentals_amenities/{rentals.rentals_amenities}",
    "rentals.rentals_fees": "https://www.bookingsync.com/api/v3/rentals_fees/{rentals.rentals_fees}",
    "rentals.bathrooms": "https://www.bookingsync.com/api/v3/bathrooms/{rentals.bathrooms}",
    "rentals.bedrooms": "https://www.bookingsync.com/api/v3/bedrooms/{rentals.bedrooms}",
    "rentals.rentals_tags": "https://www.bookingsync.com/api/v3/rentals_tags/{rentals.rentals_tags}",
    "rentals.change_over": "https://www.bookingsync.com/api/v3/change_overs/{rentals.change_over}",
    "rentals.nightly_rate_map": "https://www.bookingsync.com/api/v3/nightly_rate_maps/{rentals.nightly_rate_map}"
  },
  "rentals": [
    {
      "links": {
        "account": 1,
        "availability": 1,
        "destination": 134,
        "rates_table": 1,
        "rental_agreement": 1,
        "rental_cancelation_policy": 1,
        "photos": [
          1
        ],
        "reviews": [
          1,
          2,
          3,
          4,
          5
        ],
        "special_offers": [
          1
        ],
        "rates": [
          1
        ],
        "rentals_amenities": [
          1,
          2,
          3
        ],
        "rentals_fees": [],
        "bathrooms": [
          5,
          6,
          7
        ],
        "bedrooms": [
          8,
          9,
          10,
          11
        ],
        "rentals_tags": [],
        "change_over": 1,
        "nightly_rate_map": 1
      },
      "id": 1,
      "name": "Cottage 1",
      "headline": {
        "en": "Villa in Nevache, France"
      },
      "summary": {
        "en": "Great value. A place to enjoy peace and tranquility, away from mass tourism."
      },
      "description": {
        "en": "First class Villa for 8 people with private pool. Situated in a pleasant residential area."
      },
      "rental_type": "villa",
      "management_type": "professional",
      "downpayment": 30,
      "bedrooms_count": 4,
      "sleeps": 8,
      "sleeps_max": 9,
      "bathrooms_count": 3,
      "surface": 120,
      "surface_unit": "metric",
      "bookable_online": false,
      "min_price": "420.0",
      "max_price": "600.0",
      "base_rate": "600.0",
      "base_rate_kind": "weekly",
      "currency": "EUR",
      "price_public_notes": {
        "en": null
      },
      "lat": 45.02,
      "lng": 6.6,
      "city": "Nevache",
      "state": null,
      "country_code": "FR",
      "contact_name": "Betty Reichert",
      "reviews_count": 5,
      "reviews_average_rating": "4.0",
      "published_at": "2025-03-31T17:52:12.171Z",
      "created_at": "2025-03-31T17:52:12.171Z",
      "updated_at": "2025-04-07T17:52:12.171Z",
      "checkin_time": 16,
      "checkout_time": 10,
      "initial_price": null,
      "final_price": null,
      "position": 1,
      "absolute_min_price": "300.0",
      "stories_count": 2,
      "floor": "A",
      "residency_category": "primary_residence",
      "mid_term_pricing_active": false,
      "nightly_rates_managed_externally": false,
      "website_url": {
        "en": "https://example.com/en/rentals/123-rental-headline"
      },
      "permit_number": "AQD9382857",
      "certifications": {
        "meubles_de_tourisme": [
          "1_etoile",
          "2_etoiles",
          "3_etoiles",
          "4_etoiles"
        ]
      }
    }
  ],
  "meta": {}
}

Search rentals​

Search parameters allow to filter rentals by specified fields.

Example:

GET /rentals/search?start_at=20140324&end_at=20140330

Search Parameters​

NameTypeDefaultDescription
amenitiesStringList of comma separated amenities to include.
adultsIntegerNumber of adults to take into account when calculating final_price.
bb_neFloatRentals located between bb_sw & bb_ne. Format latitude, longitude.
bb_swFloatRentals located between bb_sw & bb_ne. Format latitude, longitude.
bedrooms_countIntegerRentals with amount of bedrooms equal to or above given number.
bookable_onlineBooleanblanktrue to get rentals that are allowed to be bookable online (requiring no human interaction), false to get those that are not.
instantly_bookableBooleantrue to get rentals that are instantly bookable (with payment confirming the booking)
childrenIntegerNumber of children to take into account when calculating final_price.
cityStringRentals matching given city.
country_codeStringRentals matching given country code, list of codes is available at wikipedia.
destinationStringList of comma separated destinations.
directionStringDirection to sort rentals, either asc or desc.
exchange_to_currencyStringConvert amounts to the currency of your choice (ex: EUR, USD, ...)
guestsIntegerUsed to filter out rentals with maximum number of sleeps below given number of guests.
idStringList of comma separated rental ids.
include_not_availableBooleanfalseInclude not available rentals in the response.
include_tentativeBooleanfalseTreat tentative periods as available ones.
max_priceIntegerRentals with max_price below given price. Will use final_price if computed.
min_priceIntegerRentals with min_price above given price. Will use final_price if computed.
pageIntegerUsed to browse multi-paged listings.
per_pageIntegerLimit amount of returned rentals to given number. Full list can then be browsed with page parameter.
published_onlyBooleanfalseShow only published rentals.
reject_amenitiesStringList of comma separated amenities to exclude.
rental_idStringList of comma separated rental ids. (if you want to limit the search to some specific ones that you know in advance)
rental_typeStringList of comma separated types, all types described in enums section.
rentals_tagsStringList of comma separated rentals tags.
sortStringSort rentals by given attribute. Possible values: price, sleeps, sleeps_max, bedrooms_count
special_offersBooleanfalseShow only rentals with special offers.
full_bathrooms_countIntegerRentals with amount of full bathrooms equal to or above given number.
included_amenitiesArrayRentals containing Amenities identified by the provided IDs
excluded_amenitiesArrayRentals not containing Amenities identified by the provided IDs
start_atTimeRentals available between start_at & end_at.
end_atTimeRentals available between start_at & end_at.
response.json
{
  "rentals": [
    {
      "links": {
        "rentals_fees": "http://www.bookingsync.com/api/v3/rentals_fees/{rentals.rentals_fees}"
      },
      "id": 1,
      "currency": "EUR",
      "damage_deposit": 35.5,
      "updated_at": "2014-01-21T11:46:15Z",
      "initial_price": 700,
      "final_price": 858.33,
      "price_to_pay_now": 858.33,
      "taxes": [
        {
          "name": {
            "en": "VAT"
          },
          "percentage": "10.0",
          "amount": "58.33"
        }
      ],
      "price_details": {
        "taxes": [
          {
            "name": {
              "en": "VAT"
            },
            "percentage": "10.0",
            "amount": "58.33",
            "taxable_type": "Rental",
            "taxable_id": 2,
            "tax_id": 1,
            "included": false
          }
        ],
        "fees": [
          {
            "name": {
              "en": "some fee"
            },
            "required": true,
            "price": "100.0",
            "quantity": 1,
            "id": 10,
            "rentals_fee_id": 12
          }
        ]
      }
    }
  ]
}

Search response Parameters​

GroupSubgroupNameTypeDescription
damage_depositFloatRental's required damage deposit.
final_priceFloatRental's price with fees and taxes.
initial_priceFloatRental's price.
price_to_pay_nowFloatPart of the price to pay at this moment if the rental was to be booked now.
price_to_pay_now_with_damage_depositFloatPart of the price to pay at this moment if the rental was to be booked now including damage deposit (if chargeable during the booking).
price_detailsHashFees and taxes breakdown contributing to the final price.
taxesArrayDetailed breakdown of Taxes with reference to the item which was taxed by the Tax (Fee or Rental) and own ID.
nameStringTax's name.
percentageStringTax's percentage.
amountStringTax's amount.
taxable_typeStringTaxed item type (Fee or Rental)
taxable_idIntegerFee or Rental ID
tax_idIntegerTax's ID
includedBooleanTrue/False status if this tax is already included in taxable's (Fee or Rental) price or not
feesArrayDetails of the bookings fees required to be booked with the rental.
nameStringFee's name.
requiredBooleanTrue/False status for always required.
priceStringFee's price.
quantityStringFee's quantity.
idIntegerFee's ID
rentals_fee_idIntegerRentals Fee's ID
taxesArrayGrouped taxes by their identity with summed amounts.
nameStringTax's name.
percentageStringTax's percentage.
amountStringTax's amount.

Get a single rental​

Returns a single rental identified by ID.

GET /rentals/:rental_id
response.json
{
  "links": {
    "rentals.account": "https://www.bookingsync.com/api/v3/accounts/{rentals.account}",
    "rentals.availability": "https://www.bookingsync.com/api/v3/availabilities/{rentals.availability}",
    "rentals.destination": "https://www.bookingsync.com/api/v3/destinations/{rentals.destination}",
    "rentals.rates_table": "https://www.bookingsync.com/api/v3/rates_tables/{rentals.rates_table}",
    "rentals.rental_agreement": "https://www.bookingsync.com/api/v3/rental_agreements/{rentals.rental_agreement}",
    "rentals.rental_cancelation_policy": "https://www.bookingsync.com/api/v3/rental_cancelation_policies/{rentals.rental_cancelation_policy}",
    "rentals.photos": "https://www.bookingsync.com/api/v3/photos/{rentals.photos}",
    "rentals.reviews": "https://www.bookingsync.com/api/v3/reviews/{rentals.reviews}",
    "rentals.special_offers": "https://www.bookingsync.com/api/v3/special_offers/{rentals.special_offers}",
    "rentals.rates": "https://www.bookingsync.com/api/v3/rates/{rentals.rates}",
    "rentals.rentals_amenities": "https://www.bookingsync.com/api/v3/rentals_amenities/{rentals.rentals_amenities}",
    "rentals.rentals_fees": "https://www.bookingsync.com/api/v3/rentals_fees/{rentals.rentals_fees}",
    "rentals.bathrooms": "https://www.bookingsync.com/api/v3/bathrooms/{rentals.bathrooms}",
    "rentals.bedrooms": "https://www.bookingsync.com/api/v3/bedrooms/{rentals.bedrooms}",
    "rentals.rentals_tags": "https://www.bookingsync.com/api/v3/rentals_tags/{rentals.rentals_tags}",
    "rentals.change_over": "https://www.bookingsync.com/api/v3/change_overs/{rentals.change_over}",
    "rentals.nightly_rate_map": "https://www.bookingsync.com/api/v3/nightly_rate_maps/{rentals.nightly_rate_map}"
  },
  "rentals": [
    {
      "links": {
        "account": 1,
        "availability": 1,
        "destination": 134,
        "rates_table": 1,
        "rental_agreement": 1,
        "rental_cancelation_policy": 1,
        "photos": [
          1
        ],
        "reviews": [
          1,
          2,
          3,
          4,
          5
        ],
        "special_offers": [
          1
        ],
        "rates": [
          1
        ],
        "rentals_amenities": [
          1,
          2,
          3
        ],
        "rentals_fees": [],
        "bathrooms": [
          5,
          6,
          7
        ],
        "bedrooms": [
          8,
          9,
          10,
          11
        ],
        "rentals_tags": [],
        "change_over": 1,
        "nightly_rate_map": 1
      },
      "id": 1,
      "name": "Cottage 1",
      "headline": {
        "en": "Villa in Nevache, France"
      },
      "summary": {
        "en": "Great value. A place to enjoy peace and tranquility, away from mass tourism."
      },
      "description": {
        "en": "First class Villa for 8 people with private pool. Situated in a pleasant residential area."
      },
      "rental_type": "villa",
      "management_type": "professional",
      "downpayment": 30,
      "bedrooms_count": 4,
      "sleeps": 8,
      "sleeps_max": 9,
      "bathrooms_count": 3,
      "surface": 120,
      "surface_unit": "metric",
      "bookable_online": false,
      "min_price": "420.0",
      "max_price": "600.0",
      "base_rate": "600.0",
      "base_rate_kind": "weekly",
      "currency": "EUR",
      "price_public_notes": {
        "en": null
      },
      "lat": 45.02,
      "lng": 6.6,
      "city": "Nevache",
      "state": null,
      "country_code": "FR",
      "contact_name": "Betty Reichert",
      "reviews_count": 5,
      "reviews_average_rating": "4.0",
      "published_at": "2025-03-31T17:52:12.186Z",
      "created_at": "2025-03-31T17:52:12.186Z",
      "updated_at": "2025-04-07T17:52:12.186Z",
      "checkin_time": 16,
      "checkout_time": 10,
      "initial_price": null,
      "final_price": null,
      "position": 1,
      "absolute_min_price": "300.0",
      "stories_count": 2,
      "floor": "A",
      "residency_category": "primary_residence",
      "mid_term_pricing_active": false,
      "nightly_rates_managed_externally": false,
      "website_url": {
        "en": "https://example.com/en/rentals/123-rental-headline"
      },
      "permit_number": "AQD9382857",
      "certifications": {
        "meubles_de_tourisme": [
          "1_etoile",
          "2_etoiles",
          "3_etoiles",
          "4_etoiles"
        ]
      }
    }
  ],
  "meta": {}
}

Create a new rental​

Price increase

Please note that creating rentals will increase the account monthly fee. For further details, check our pricing.

Translated attributes

Please note that translated attributes are updated differently than you read them. To set the English headline, locale en, you need to use the headline_en attribute. List of locales described in enums section.

Returns a newly created rental.

POST /rentals

Update a rental​

Returns an updated rental identified by ID.

Translated attributes

Please note that translated attributes are updated differently than you read them. To set the English headline, locale en, you need to use the headline_en attribute. List of locales described in enums section.

PUT /rentals/:rental_id

Destroy a rental​

Price decrease

Please note that destroying rentals will decrease the account monthly fee. For further details, check our pricing.

Returns an empty response with 204 No Content status code on success.

DELETE /rentals/:rental_id