V1.5 -> V3 Migration Guide

There are 3 versions of Hostfully APIs:

v1: to be removed shortly after version 3 is released to production
v2: to be deprecated. It's still working, but no longer receive bug fixes and added features
v3: to be the active supported version.

A - For Hostfully Integration Partners, the main difference, is the permission service.

For v1, Property Managers (PMs) active once on agency level, and it will be applied for all of their properties.
For v3, PMs need to take an extra step, to explicitly activate the integration on the property level. Only the property toggle ON will be accessible to integration / channel partners.

Also for Hostfully Integration Partners, the difference is with OAuth 2.0 Authorization Code Flow, which is how Hostfully Customers authorize Partners to access their data..

If you are on v1, and need help migrating v3, (to prepare UI for property-level activation), please reach out to [email protected] for further support.

B - For Hostfully Premium accounts, the authentication is going to continue to be served by the api keys, just like it was in V1 and V2 versions of our API key.

To make calls to v3, update your requests to use the new v3 endpoints. Some endpoints take different parameters or return different data; make sure you check out the API documentation here: https://dev.hostfully.com/v3.0/reference/getting-started

If you have any question or suggestion on the Hostfully APIs, please reach out to our API Support team at [email protected].

Difference in endpoints between v1.5 & v3

New Endpoints:

Endpoints	Descriptions
Available Amenities	Return all available amenities that can be interacted with
Available Property Rules	Return all property rules that can be interacted with
Employees	Retrieve and update team member(s)'s info
Extra Guests	Retrieve info of extra guest by leadUid
GraphQL	All graphQL endpoints like propertiesql, and leadsql
iCals	Return property’s iCal configuration
Messages	Retrieve and send message by leadUid
Property Calendars	Retrieve property's availability and pricing settings
Property Channel Links	Update channel links for a property for supported channels: HomeToGo, Golightly, VacayMyWay, Homads
Property Ownership	Manage property's ownership setting
Property Pricing Rules	Retrieve pricing rules for a given property
Owner Adjustments	Retrieve info and manage property's owner adjustments
Rate Multipliers	Retrieve and update channel(s)' rate multiplier setting
Reviews Bulk	Add reviews in bulk
Rooms Bulk	Add new or update existing property' rooms
Sub Units	Returns information about master-sub units relation, and whether the master unit is bookable.

Updates on existing endpoints

Agencies

Path: /v1/agencies -> /api/v3/agencies
Response:
- Added currencyCode
- Added currency
- Added rentalCondition

Amenities

Path: v1/amenities → /api/v3/amenities
Method:
- Added: GET/{uid}, POST, DELETE
- Updated: PUT can update amenity's description only
Response: key-value pair in v1 becomes amenity object in v3

Bedtypes

Path: v1/bedtypes → /api/v3/rooms
Method:
- Added: GET/{uid}, POST, PUT, DELETE
Updated fields: Bed count values on new v3 is wrapped in an object “bedCounts", instead of being on root of the object in v1

Method	Request	Response
GET	Renamed `propertyUid > objectUid` . Added `objectType`	new `bedCounts` objects
POST	new `bedCount` objects, `roomType`, `roomNumber`	new `bedCounts` objects
PUT	new `bedCount` objects, `roomType`	new `bedCounts` objects

Custom Amenities

Path: v1/customamenities → /api/v3/custom-amenities
Method:
- Removed: PUT
Updated fields:

Method	Renamed	New
GET	Request: Rename `propertyUid > objectUid` Added `objectType`	Response: Added `objectUid` and `objectType`. Replaced `id > uid`
POST	Same as GET	Same as GET

Custom Data

Path: v1/customdata → api/v3/custom-data
Method:
- Added: DELETE.
  - Delete custom data of a property or lead. The custom data is identified by 'customDataFieldUid' and one of 'propertyUid' or 'leadUid'
Updated fields:

Method	Request	Response
GET	Query by `leadUid` or `propertyUid`	Added `customDataField` object
POST	Added `leadUid` in body param	Same as GET

Custom Data Fields

Path: v1/customdatafields → api/v3/custom-data-fields
Method:
- Added GET/{uid}, POST, DELETE
Updated fields:

Method	Request	Response
POST	Added `variable`, `index`	Added `agencyUid`, `variable`, `index` Replaced `id > uid`

Custom Fees

Path: v1/customfees → /api/v3/fees
Method:
- Added GET/{uid}, PUT, DELETE
Updated fields:

Method	Request	Response
GET	-	Replace `id > uid` Renamed `isOptional` > `optional`. Added `airbnbType`, `bookingDotComType`, `vrboType`, `hostfullyType`, `hvmiType`, `attestation`, `propertyUid`, `taxationRate`, `type`, `longTermStayExemption`
POST	Rename `isOptional` > `optional` Added `airbnbType`, `bookingDotComType`, `vrboType`, `hostfullyType`, `hvmiType`, `attestation`, `propertyUid`, `taxationRate`, `type`, `longTermStayExemption`	same as GET

Guest

Path: v1/guests → /api/v3/guests
Method:
- Removed: GET/{uid}, POST, PUT, DELETE
Updated fields:

Method	Request	Response
GET		Renamed `createdDate` (Date) to `created` (LocalDateTime) . Added `address2`. Removed `airbnbID`, `agencyUid`, `id`, `lastLogin`, `registrationToken`

Jobs

Path: v1/jobs → /api/v3/jobs

Method	Request	Response
GET	Added new query params `from` & `to`. Added ability to query jobs from multiple `propertyUids`	Added `startLocalDateTime`, `startZonedDateTime`, `endLocalDateTime`, `endZonedDateTime`, `leadUid`, `propertyUid` Removed `jobDate`, `startTime`, `endTime`
GET/{uid}	-	same as GET
POST	Removed `jobDate`, `startTime`, `endTime` Added `startLocalDateTime` object, `endLocalDateTime` object, `leadUid`	same as GET
PUT	Removed `jobDate`, `startTime`, `endTime` Added `startLocalDateTime` object, `endLocalDateTime` object, `serviceUid`	same as GET

Leads

Path: v1/leads → /api/v3/leads
Method:
- Removed PUT
- Added PATCH
Updated fields

Method	Request	Response
GET	Replaced `modified` > `updatedSince` `checkin_to` > `checkInTo` `checkin_from` > `checkInFrom` `checkout_to` > `checkOutTo` `checkout_from` > `checkOutFrom` Added ability to query by list of `leadUids` Added `_cursor` param Removed `offset`, `status` param	Replaced `property.uid` > `propertyUid` `checkInDateTime` > `checkInZonedDateTime` `checkOutDateTime` > `checkOutZonedDateTime` `created` > `metadata. createdUtcDateTime` `preferredLocale` > `guestInformation.preferredLocale`object `dateBooked` > `bookedUtcDateTime` address details from property > lead Added `agencyUid` `assignee` object (`uid` & `type`) `metadata` object `guestInformation` object `guestInformation.passportId` `guestInformation.passportCountryCode` `externalBookingId` `type` `arrivalLocalDateTime` `departureLocalDateTime` Removed `agency` object `property` object `stayDetails` object (kept `extraNotes`) `checkInLocalDate` `checkOutLocalDate` `checkInDate` `checkOutDate` `ipaddress` `userAgent` `quoteAmount`
GET/{uid}	-	Same as GET
POST	Please refer to https://dev.hostfully.com/v3.0/reference/leads-flow for more details	Same as GET

Local Spots

Path: v1/localspots → /api/v3/local-spots
Method: added /GET/{uid}
Updated fields

Method	Request	Response
GET		Replaced `id > uid` Renamed `note > shortNote`
POST / PUT	Renamed `note > shortNote	Same as GET

Orders

Path: v1/orders → /api/v3/orders
Method:
- Removed GET/{uid}
- GET now supports query by guestUid, besides existing propertyUid & leadUid
Updated fields (removed balance, transactions object in the response)

Renamed New fields

baseAmount > rent.rentNetPrice
extraGuestFeeAmount > rent.extraGuestsNetPrice
subTotal > rent.grossPrice
securityDepositAmount > securityDeposit
cleaningFeeAmount > fees.cleaningFee.grossPrice
cleaningFeeTaxAmount > fees.cleaningFee.taxAmount
orderFees array > otherFees array
total > totalAmount
channelCommission > channelCommission.amount creationUtcDateTime
rent.listPrice = rentNetPrice + extraGuestsNetPrice
discount object
rent.netPrice = rent.listPrice - rent.discount.discountAmount
taxationRate
grossPrice = netPrice + taxAmount
fees object (cleaningFee + otherFees)
cleaningFee object
otherFees object
services object
adjustments array
adjustmentItems array
rateMultiplier
totalTaxAmount"

Renamed	New fields
`baseAmount` > `rent.rentNetPrice` `extraGuestFeeAmount` > `rent.extraGuestsNetPrice` `subTotal` > `rent.grossPrice` `securityDepositAmount` > `securityDeposit` `cleaningFeeAmount` > `fees.cleaningFee.grossPrice` `cleaningFeeTaxAmount` > `fees.cleaningFee.taxAmount` `orderFees` array > `otherFees` array `total` > `totalAmount` `channelCommission` > `channelCommission.amount`	`creationUtcDateTime` `rent.listPrice` = `rentNetPrice` + `extraGuestsNetPrice` `discount` object `rent.netPrice` = `rent.listPrice` - `rent.discount.discountAmount` `taxationRate` `grossPrice` = `netPrice` + `taxAmount` `fees` object (`cleaningFee` + `otherFees`) `cleaningFee` object `otherFees` object `services` object `adjustments` array `adjustmentItems` array `rateMultiplier` `totalTaxAmount`"

Owners

Path: v1/owners → /api/v3/owners
Method:
- Removed: POST & PUT
- Added: PATCH
- GET query by agencyUid and ownerUid only. (removed propertyUid)
- DELETE: with v3, delete the owner for good. While with v1, remove the owner from the property
Updated fields

New fields
Added `uid`, `airbnbUserId`, `businessName`, `country`, `externalCalendarUrl`, `permissionTypes` , `phoneNumberAreaCode`, `pictureUrl`, `preferredLocale`, `website`, `ccEmails`

Photos

Path: v1/photos → /api/v3/photos
Updated fields

Method	Request	Response
GET		Added `airbnbRoomId`, `propertyUid`, `originalImageUrl`, `largeScaleImageUrl`, `mediumScaleImageUrl`, `largeThumbnailScaleImageUrl`. Removed `url`
POST	Added`airbnbRoomId`, `description`, `displayOrder`	same as GET
PUT	Added `airbnbRoomId`	same as GET

Pincodes

Path: v1/pincodes → /api/v3/pin-codes
Method: added PUT
Updated fields

Method	Request	Response
GET	Removed `lockType` Added `leadUid`	Renamed `type > lockType` Added `uid`, `startDateTimeUTC`, `endDateTimeUTC`, `pincodeUrl` Removed `startDateTime`, `endDateTime`, `propertyUid`, `id`, `userEmail`
POST	Added `pincodeUrl`, `startDateTimeUTC, endDateTimeUTC`	same as GET

Pricing Periods

Path: v1/pricingperiods →/api/v3/pricing-periods
Method:
- GET: new query param from
- POST: new operation to REMOVE, beside SET
Updated fields:

Method	Request	Response
GET	-	Renamed `amount → price` `isCheckinAllowed → availableForCheckIn` `isCheckoutAllowed → availableForCheckOut` `uid > propertyUid` Added `name` Removed`from`, `to`
POST	Added`operation` method Body request fields are similar to GET response	Same as GET

Pricing Periods Bulk

Path: v1/pricingperiodsbulk → /api/v3/pricing-periods/bulk
Method:
- Added GET

Properties

Path: v1/properties → /api/v3/properties
Method:
- GET: added new query filter: _offset, _limit, updatedSince
Updated fields

Method	Request	Response
GET	added new query filter: `_offset`, `_limit`, `updatedSince`	Added `agencyUid`, `address` object for all address settings `availability` object for all availability settings `pricing` object for all pricing settings channel-related objects: `airbnbData`, `bookingDotComData`, `hvmiData`, `vrboData` `guideBookRecsOnlyUrl` `accountingId` `showPropertyExactLocation` `agentUid` `bookingNotes` `extraNotes` `ownerNotes` `cancellationPolicy` `useMinimumPriceRule` `updatedUtcDateTime`
GET		Renamed `bedCount > beds`, `type > propertyType` `maximumGuests > availability.maxGuests` `areaSize > area.size` `areaSizeUnit > area.unitType` `defaultCheckinTime > availability.checkInTimeStart` `defaultCheckoutTime > availability.checkOutTime` `picture > pictureLink` `address1 > address.address` `postalCode > address.zipCode` `baseDailyRate > pricing.dailyRate` `weekEndRatePercentAdjustment > pricing.weekendAdjustmentRate` `taxationRate > pricing.taxRate` `securityDepositAmount > pricing.securityDeposit` `cleaningFeeAmount > pricing.cleaningFee` `floor > numberOfFloors` `airBnBID > airbnbData.airBnBId`
GET		Removed `pricingRule` > `v3/property-pricing-rules` endpoint `bedType` > `v3/rooms` endpoint `rules > v3/pricing-rules`endpoint `descriptions` and `shortDescription` moved to `v3/propertydescriptions` endpoint `listingType`, `roomType`, `businessType`, `bookingWindowAfterCheckout`, `availabilityCalendarUrl`, `reviews` `createdDate` `listingLinks` object > `v3/property-channel-links` endpoint `propertyURL` `currencySymbol` `acceptInstantBook` `acceptBookingRequest` `flipkeyID` `homeAwayID`
POST & PUT	same as GET's response	\|same as GET's response

Property Descriptions

Path: v1/propertydescriptions → /api/v3/property-descriptions
Updated fields

Method	Request	Response
GET		Added `propertyUid`, `houseManual`
PUT	Added `propertyUid`, `houseManual`	Added `propertyUid`, `houseManual`

Property Rules

Path: v1/propertyrules → /api/v3/property-rules
- In v1, this endpoint works with property's House Rules in property's Fees & Policies tab
- In v3, this endpoint works with property's Rules section in property's Amenities tabz
Method:
- Added GET/{uid}, DELETE, PATCH (with an option to provide fieldsToClear collection for resetting values to null - only descripition field is nullable)
- PUT: for v3 updates entire entity, before in v1 it used to update only the description field
Updated fields:

Method	Request	Response
GET		Added `uid`, `rule`, `propertyUid` Removed `locale`
POST	Added `rule`	Same as GET response

Quotes

Path: v1/quote → /api/v3/quotes
Method:
- Removed GET
- Added POST
  - Add query by leadUid
Updated fields

Update category	Request	Response
Renamed	`guestCount > guests`	`extraGuestFeeAmount > rent.extraGuestsNetPrice` `amount > rent.grossPrice` `securityDepositAmount > securityDeposit` `cleaningFeeAmount > fees.cleaningFee.grossPrice` `customFees` array > `otherFees` array`
Added	`agencyUid` `leadUid` `overrides` object	`rent.listPrice` = `rentNetPrice` + `extraGuestsNetPrice` `rent.discount` object {} `rent.netPrice` = `rent.listPrice` - `rent.discount.discountAmount` `rent.taxationRate` `rent.grossPrice` = `rent.netPrice` + `rent.taxAmount` `fees` object (`cleaningFee` & `otherFees` objects) `services` object `adjustments` array `adjustmentItems` array `overrides` object `totalPrice` = `totalAmount` + `overrides` `force100PercentPaymentAtReservation` `currencySymbol`
Removed		`property` object `totalWithoutTaxes` `totalWithTaxes` `totalWithTaxesAndSecDeposit`

Reviews

Path: v1/reviews → /api/v3/reviews
Method:
- Added GET/{uid}, PUT, DELETE
Updated fields:

Method	Request	Response
GET	Added query param `updateSince` `leadUid`	Added `uid` `propertyUid` `leadUid` `source` `privateFeedback` `reviewResponse` object `ratingCategories` object `comment` `updatedUtcDateTime`
POST	Removed `agencyUid` Added `leadUid` `source` `privateFeedback` `reviewResponses` object `ratingCategories` object	same as GET response

Services

Path: v1/services → /api/v3/services
Updated fields:

Method	Request	Response
GET	Add query params `agencyUid` & `cateredTo`	Renamed `cateredToType` → `cateredTo` Removed `serviceProviderUID`
POST	-	Same as GET
PUT	Added body param `serviceProviderUID`	Same as GET

Service Providers

Path: v1/serviceproviders → /api/v3/service-providers
Updated fields:

Method	Request	Response
GET	Removed query param `propertyUid`	-
PUT	Added body param `agencyUid`

Transactions

Path: v1/transactions → /api/v3/transactions
Method:
- Added POST method
Updated fields:

Method	Request	Response
GET	Added query param `createdSince`	Renamed: `transactionID → transactionId` `created → createdZonedDateTime`, `isManual → manual` Added: `uid` `orderUid` `transactionId` `referenceTransactionID` `errorMessage` `status` `transactionFees` object Removed: `id` `agencyID` `order` object
GET/{uid}	Removed `id` query param Added `uid` query param	Same as GET

Webhooks

Path: v1/webhooks → /api/v3/webhooks
Method:
- Added GET/{uid}

Method	Request	Response
GET	Added query param `integrationWebhooks` (boolean)	Removed `id` Added `uid` `agencyUid` `webhookType` `creatorIdentifier`
POST	Added many new `eventType` Added `agencyUid` `webhookType` `creatorIdentifier`	Same as GET