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:

EndpointsDescriptions
Available AmenitiesReturn all available amenities that can be interacted with
Available Property RulesReturn all property rules that can be interacted with
EmployeesRetrieve and update team member(s)'s info
Extra GuestsRetrieve info of extra guest by leadUid
GraphQLAll graphQL endpoints like propertiesql, and leadsql
iCalsReturn property’s iCal configuration
MessagesRetrieve and send message by leadUid
Property CalendarsRetrieve property's availability and pricing settings
Property Channel LinksUpdate channel links for a property for supported channels: HomeToGo, Golightly, VacayMyWay, Homads
Property OwnershipManage property's ownership setting
Property Pricing RulesRetrieve pricing rules for a given property
Owner AdjustmentsRetrieve info and manage property's owner adjustments
Rate MultipliersRetrieve and update channel(s)' rate multiplier setting
Reviews BulkAdd reviews in bulk
Rooms BulkAdd new or update existing property' rooms
Sub UnitsReturns 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
MethodRequestResponse
GETRenamed propertyUid > objectUid . Added objectTypenew bedCounts objects
POSTnew bedCount objects, roomType, roomNumbernew bedCounts objects
PUTnew bedCount objects, roomTypenew bedCounts objects

Custom Amenities

  • Path: v1/customamenities → /api/v3/custom-amenities
  • Method:
    • Removed: PUT
  • Updated fields:
MethodRenamedNew
GETRequest:
Rename propertyUid > objectUid
Added objectType
Response:
Added objectUid and objectType. Replaced id > uid
POSTSame as GETSame 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:
MethodRequestResponse
GETQuery by leadUid or propertyUidAdded customDataField object
POSTAdded leadUid in body paramSame as GET

Custom Data Fields

  • Path: v1/customdatafields → api/v3/custom-data-fields
  • Method:
    • Added GET/{uid}, POST, DELETE
  • Updated fields:
MethodRequestResponse
POSTAdded variable, indexAdded agencyUid, variable, index
Replaced id > uid

Custom Fees

  • Path: v1/customfees → /api/v3/fees
  • Method:
    • Added GET/{uid}, PUT, DELETE
  • Updated fields:
MethodRequestResponse
GET-Replace id > uid
Renamed isOptional > optional.
Added airbnbType, bookingDotComType, vrboType, hostfullyType, hvmiType, attestation, propertyUid, taxationRate, type, longTermStayExemption
POSTRename 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:
MethodRequestResponse
GETRenamed createdDate (Date) to created (LocalDateTime) . Added address2. Removed airbnbID, agencyUid, id, lastLogin, registrationToken

Jobs

  • Path: v1/jobs → /api/v3/jobs
MethodRequestResponse
GETAdded new query params from & to. Added ability to query jobs from multiple propertyUidsAdded startLocalDateTime, startZonedDateTime, endLocalDateTime, endZonedDateTime, leadUid, propertyUid
Removed jobDate, startTime, endTime
GET/{uid}-same as GET
POSTRemoved jobDate, startTime, endTime
Added startLocalDateTime object, endLocalDateTime object, leadUid
same as GET
PUTRemoved 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
MethodRequestResponse
GETReplaced
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.preferredLocaleobject
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
POSTPlease refer to https://dev.hostfully.com/v3.0/reference/leads-flow for more detailsSame as GET

Local Spots

  • Path: v1/localspots → /api/v3/local-spots
  • Method: added /GET/{uid}
  • Updated fields
MethodRequestResponse
GETReplaced id > uid
Renamed note > shortNote
POST / PUTRenamed `note > shortNoteSame 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)
RenamedNew 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
MethodRequestResponse
GETAdded airbnbRoomId, propertyUid, originalImageUrl, largeScaleImageUrl, mediumScaleImageUrl, largeThumbnailScaleImageUrl. Removed url
POSTAddedairbnbRoomId, description, displayOrdersame as GET
PUTAdded airbnbRoomIdsame as GET

Pincodes

  • Path: v1/pincodes → /api/v3/pin-codes
  • Method: added PUT
  • Updated fields
MethodRequestResponse
GETRemoved lockType
Added leadUid
Renamed type > lockType
Added uid, startDateTimeUTC, endDateTimeUTC, pincodeUrl
Removed startDateTime, endDateTime, propertyUid, id, userEmail
POSTAdded pincodeUrl, startDateTimeUTC, endDateTimeUTCsame 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:
MethodRequestResponse
GET-Renamed amount → price
isCheckinAllowed → availableForCheckIn
isCheckoutAllowed → availableForCheckOut
uid > propertyUid
Added name
Removedfrom, to
POSTAddedoperation 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
MethodRequestResponse
GETadded new query filter: _offset, _limit, updatedSinceAdded 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
GETRenamed 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
GETRemoved pricingRule > v3/property-pricing-rules endpoint
bedType > v3/rooms endpoint
rules > v3/pricing-rulesendpoint
descriptions and shortDescription moved to v3/propertydescriptions endpoint
listingType,
roomType,
businessType,
bookingWindowAfterCheckout
rentalCondition
availabilityCalendarUrl,
reviews
createdDate
listingLinks object > v3/property-channel-links endpoint
propertyURL
currencySymbol
acceptInstantBook
acceptBookingRequest
flipkeyID
homeAwayID
POST & PUTsame as GET's response|same as GET's response

Property Descriptions

  • Path: v1/propertydescriptions → /api/v3/property-descriptions
  • Updated fields
MethodRequestResponse
GETAdded propertyUid, houseManual
PUTAdded propertyUid, houseManualAdded 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:
MethodRequestResponse
GETAdded uid, rule, propertyUid
Removed locale
POSTAdded ruleSame as GET response

Quotes

  • Path: v1/quote → /api/v3/quotes
  • Method:
    • Removed GET
    • Added POST
      • Add query by leadUid
  • Updated fields
Update categoryRequestResponse
RenamedguestCount > guestsextraGuestFeeAmount > rent.extraGuestsNetPrice
amount > rent.grossPrice
securityDepositAmount > securityDeposit
cleaningFeeAmount > fees.cleaningFee.grossPrice
customFees array > otherFees array`
AddedagencyUid
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
Removedproperty object
totalWithoutTaxes
totalWithTaxes
totalWithTaxesAndSecDeposit

Reviews

  • Path: v1/reviews → /api/v3/reviews
  • Method:
    • Added GET/{uid}, PUT, DELETE
  • Updated fields:
MethodRequestResponse
GETAdded query param
updateSince
leadUid
Added uid
propertyUid
leadUid
source
privateFeedback
reviewResponse object
ratingCategories object
comment
updatedUtcDateTime
POSTRemoved agencyUid

Added leadUid
source
privateFeedback
reviewResponses object
ratingCategories object
same as GET response

Services

  • Path: v1/services → /api/v3/services
  • Updated fields:
MethodRequestResponse
GETAdd query params agencyUid & cateredToRenamed cateredToTypecateredTo
Removed serviceProviderUID
POST-Same as GET
PUTAdded body param serviceProviderUIDSame as GET

Service Providers

  • Path: v1/serviceproviders → /api/v3/service-providers
  • Updated fields:
MethodRequestResponse
GETRemoved query param propertyUid-
PUTAdded body param agencyUid

Transactions

  • Path: v1/transactions → /api/v3/transactions
  • Method:
    • Added POST method
  • Updated fields:
MethodRequestResponse
GETAdded query param createdSinceRenamed:
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}
MethodRequestResponse
GETAdded query param integrationWebhooks (boolean)Removed id
Added uid
agencyUid
webhookType
creatorIdentifier
POSTAdded many new eventType
Added
agencyUid
webhookType
creatorIdentifier
Same as GET