V2 -> 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.

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..

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 v2 & 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
Messages	Retrieve and send message by leadUid
Owner Adjustments	Retrieve info and manage property's owner adjustments
Rate Multipliers	Retrieve and update channel(s)' rate multiplier setting
Rooms Bulk	Add new or update existing property' rooms

Updates on existing endpoints

Agencies

Path: /v2/agencies -> /api/v3/agencies
Response:
- Added currencyCode

Amenities

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

Bedtypes

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

Method	Request	Response
GET		new bedCounts objects
POST	new bedCount objects, roomType, roomNumber	new bedCounts objects
PUT	new bedCount objects, roomType	new bedCounts objects

Custom Amenities

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

Method	Renamed	New
GET	Request: query param: `propertyUid` becomes `objectUid`	Response: Added `objectUid` and `objectType`
POST	Request: body param: `propertyUid` becomes `objectUid`, added `objectType`	Response: Added `objectUid`, `objectType`, `uid`

Custom Data

Path: v2/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 `propertyUid`, `leadUid`, `index`
POST	Added `leadUid` in body param	Added `propertyUid`, `leadUid`, `index`

Custom Data Fields

Path: v2/customdatafields → api/v3/custom-data-fields
Updated fields:

Method	Request	Response
GET		Added `index`
POST	Added `variable`, `index`	Added `index`

Custom Fees

Path: v2/customfees → /api/v3/fees
Updated fields:

Method	Request	Response
GET		Renamed `bookingcomType` > `bookingDotComType`. Added `attestation`, `propertyUid`, `hvmiType`, `longTermStayExemption`
POST / PUT	Rename `isOptional` > `optional`, `bookingcomType` > `bookingDotComType`	Added `attestation`, `propertyUid`, `hvmiType`, `longTermStayExemption`

External Calendars

Path: v2/externalcalendars → /api/v3/icals

Guest

Path: v2/guests → /api/v3/guests
Updated fields:

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

Jobs

Path: v2/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`. Removed `jobDate` `startHour`, `startMinute` `endHour`, `endMinute`
GET/{uid}	-	same as GET
POST	-	same as GET
PUT	-	same as GET

Leads

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

Method	Request	Response
GET	Replaced `modifiedSince` > `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` param	Replaced `leadType` > `type` `checkInDateTime` > `checkInZonedDateTime` `checkOutDateTime` > `checkOutZonedDateTime` `externalBookingID` > `externalBookingId` `address` > `address1` `created` > `metadata. createdUtcDateTime` `modified` > `metadata.updatedUtcDateTime` `creationMetaData` > `metadata.creationCircumstances` `preferredLocale` > `guestInformation.preferredLocale`object `booked` > `bookedUtcDateTime` Added `assignee` object (`uid` & `type`) `metadata` object `guestInformation` object `guestInformation.passportId` `guestInformation.passportCountryCode` Removed `checkInLocalDate` `checkOutLocalDate` `checkInDate` `checkOutDate` `hasCompletedPreArrivalForm` `assigneeUid` `rentalAgreementURL`
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: v2/localspots → /api/v3/local-spots

Orders

Path: v2/orders → /api/v3/orders
Method:
- Removed GET/{uid}
- GET now supports query by guestUid, besides existing propertyUid & leadUid
Updated fields (removed balance 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: v2/owners → /api/v3/owners
Method:
- Removed: POST & PUT
- Added: PATCH
- GET query by agencyUid only. (removed propertyUid)
- DELETE: with v3, delete the owner for good. While with v2, remove the owner from the property
Updated fields

Renamed / Removed	New fields
`ccs` [array] becomes `ccEmails` "string". Removed `commissionRate`	Added `airbnbUserId`, `businessName`, `country`, `externalCalendarUrl`, `permissionTypes` , `phoneNumberAreaCode`, `pictureUrl`, `preferredLocale`, `website`

Photos

Path: v2/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: v2/pincodes → /api/v3/pin-codes
Updated fields

Method	Request	Response
GET		Added `startDateTimeUTC`, `endDateTimeUTC`. Removed `startDateTime`, `endDateTime`
POST	Added `propertyUid`	same as GET
PUT	Added`propertyUid`, `leadUid`, `lockType`, `startDateTimeUTC`, `endDateTimeUTC`	same as GET

Pricing Periods

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

Method	Request	Response
GET	-	Renamed `amount → price`, `isCheckinAllowed → availableForCheckIn`, `isCheckoutAllowed → availableForCheckOut`. Added `name`. Removed`from`, `to`
POST	Added`operation`	Same as GET

Pricing Periods Bulk

Path: v2/pricingperiodsbulk → /api/v3/pricing-periods/bulk
Updated fields:

Method	Request	Response
POST	Renamed `amount → price`, `isCheckinAllowed → availableForCheckIn`, `isCheckoutAllowed → availableForCheckOut`
GET	Added new query filter: `_offset`, `_limit`, `updatedSince`

Properties

Path: v2/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`, `availability` object `availability.allowBookingRequestsAboveMaximumStay` `availability.allowBookingRequestWhenOutOfLeadTime` `availability.checkInTimeEnd`, `availability.checkInTimeEndFlexible`, `availability.daysOfTheWeekToCheckInOn` `address` object `pricing` object `pricing.ignoreTaxRateChargeOverXDays` `pricing.daysOverWhichTaxRateChargeShouldBeIgnored` `pricing.cleaningFeeTaxRate` 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 `listingType`, `roomType`, `businessType`, `bookingWindowAfterCheckout` `rentalCondition` `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 Channel Links

Path: v2/property-channel-links → /api/v3/property-channel-links
Method:
- PUT: removed channel in Request

Property Descriptions

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

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

Property Ownership

Path: v2/propertyownership → /api/v3/property-ownership
Method:
- Removed POST
- Added PATCH
Updated fields

Method	Request	Response
GET		Renamed `ownerUid > owner.uid`. Added `email`, `firstName` `lastName` `phoneNumberAreaCode` `phoneNumber` `businessName` `pictureUrl` `preferredLocale` `ccEmails` `agencyCommissionRate` `permissionTypes` `copyOwnerWhenBookingConfirmed` `collectAndRemitTaxes`
PATCH	same as GET response	same as GET response

Property Pricing Rules

Path: v2/pricingrules → /api/v3/property-pricing-rules
Method:
- Added PUT
Updated fields

Method	Request	Response
GET		Renamed `priceRuleType` > `ruleType` Added `increaseRate` `increaseRateLowerBound` `decreaseRate` `decreaseRateHigherBound` `decreaseRateMonthly` `decreaseRateHigherBoundMonthly` `enabledForAirbnb`
PUT	same as GET response	same as GET response

Property Rules

Path: v2/propertyrules → /api/v3/property-rules
- In v2, 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 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 v2 it used to update only the description field
Updated fields:

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

Property Calendar

Path: v2/propertycalendar → /api/v3/property-calendar
- The price values returned by the API (calendarEntry.pricing.value) are now serialised to number instead of string (eg "value": 100.00 instead of "value": "100.00")
Method:
- Added GET for multiple propertyUids
Updated fields

Update details	Request	Response
GET (new)	`notes` becomes `availabilityComments`	-
GET/{propertyUid} (existing)	`notes` becomes `availabilityComments`	-

Quotes

Path: v2/quote → /api/v3/quotes
Method:
- Removed GET
- Added POST
Updated fields

Update category	Request	Response
Renamed	`guestNumber > guests`	`rent > rent.rentNetPrice` `extraGuestFeeAmount > rent.extraGuestsNetPrice` `amount > rent.grossPrice` `securityDepositAmount > securityDeposit` `discount > rent.discount` object `cleaningFeeAmount > fees.cleaningFee.grossPrice` `cleaningFeeTaxAmount > fees.cleaningFee.taxAmount` `customFees` array > `otherFees` array `amountToPay > totalAmount` `channelCommission > channelCommission.amount`
Added	`agencyUid` `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	`totalPrice`	`extraGuestFeeTaxes` `property` object `totalWithoutTaxes` `totalWithTaxes` `totalWithTaxesAndSecDeposit`

Reviews

Path: v2/reviews → /api/v3/reviews
Updated fields:

Method	Request	Response
GET	new query `updateSince`	Added `propertyUid` `leadUid` `comment` `responseDateTimeUTC` `updatedUtcDateTime`
POST / PUT	Added `reviewResponses` object	same as GET response

Reviews Bulk

Path: v2/reviewsbulk → /api/v3/reviews-bulk
Response same as /api/v3/reviews GET

Services

Path: v2/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: v2/serviceproviders → /api/v3/service-providers
Updated fields:

Method	Request	Response
PUT	Added body param `agencyUid`	-

Transactions

Path: v2/transactions → /api/v3/transactions
Updated fields:

Method	Request	Response
GET	Renamed `referenceTransactionID → referenceTransactionId`, `created → createdZonedDateTime`, `isManual → manual` Added query param `createdSince`	Renamed: `referenceTransactionID → referenceTransactionId`, `created → createdZonedDateTime`, `isManual → manual` Added: `orderUid` `transactionId` Removed: `order` object
POST	Renamed `referenceTransactionID → referenceTransactionId`, `created → createdZonedDateTime`, `isManual → manual` Added `transactionId` `fullPayment` `errorMessage`	Same as GET

Units

Path: v2/units → /api/v3/units

Webhooks

Path: v2/webhooks → /api/v3/webhooks

Method	Request	Response
GET		Added `creatorIdentifier`
POST	Added new `eventType` - `NEW_BOOKING_REQUEST` - `NEW_HOLD` Added `creatorIdentifier`	Added `creatorIdentifier`