Related resources: API Help Collections

List of content:

1. For Partners: adding a webhook to be notified when your integration is activated

2. For Partners: pulling for new activated agencies

3. Adding and retrieving properties

3.1 Adding properties
3.2 Retrieving properties

3.3 Using the GraphQL interface

4 Retrieving leads and booking

4.1 Registering webhooks

4.2 Getting leads and bookings

1. For Partners: adding a webhook to be notified when your integration is activated

If you have a Partner account (not a customer Premium account), you can optionally register a webhook of type “INTEGRATION_ACTIVATED”. With this webhook, the Hostfully system will call back your system every time a customer activates your integration. This is the suggested option.

The callback payload will contain the UID of the agency activating the integration, so you can take real time action on your end as soon as this happens.

For more details on webhood, please refer to this section: https://dev.hostfully.com/reference#getting-started-with-your-api

Sample Call

curl --location --request POST 'https://sandbox-api.hostfully.com/v2/webhooks' \
--header 'Content-Type: application/json' \
--header 'X-HOSTFULLY-APIKEY: <YOUR_API_KEY>' \
--data-raw '{
​ "objectUid" : "<YOUR_API_KEY>",
​ "eventType" : "INTEGRATION_ACTIVATED",
​ "webHookType" : "POST_JSON",
"callbackUrl" : "https://yoursite.com"
}'


2. For Partners: pulling for new activated agencies

The other option to be informed of new activations is to pull from the /agency API for new agencies. This is not the most efficient way to proceed compared to webhooks, as you will have to compare your list of agencies on every pull.

Sample Call

curl --location --request GET 'https://sandbox-api.hostfully.com/v2/agencies' \
--header 'X-HOSTFULLY-APIKEY: <YOUR_API_KEY>'

3. Adding and retrieving properties

3.1 Adding properties

Sample Call

curl --location --request POST https://sandbox-api.hostfully.com/v2/properties' \
--header 'Content-Type: application/json' \
--header 'X-HOSTFULLY-APIKEY: <YOUR_API_KEY>' \
--data-raw '{
​ "agencyUid" : "3593fab6-71ba-4317-a3c0-be3365180c7b",
​ "type" : "APARTMENT",
​ "name" : "ApiProperty",
"baseGuests" : 1,
"maximumGuests" : 4,
"baseDailyRate" : 75.25,
"city" : "Sacramento",
"state" : "CA",
"address1" : "5th st.",
"postalCode" : "00446",
"countryCode" : "US",
"acceptBookingRequest" : true,
"bedTypes" : {
​ "kingBed" : 3,
"queenBed" : 0,
"doubleBed" : 0,
"singleBed" : 0,
​ "sofaBed" : 0,
"futonBed" : 0,
"floorMattress" : 0,
"bunkBed" : 0,
"toddlerBed" : 0,
"crib" : 0,
"hammockBed" : 0,​
"airMattress" : 0,​
"waterBed" : 0,
}
}'


3.2 Retrieving properties

Retrieving property data happens in multiple batches. You first need to get the property list from the /property API, and then iterate through the list to get data for each property:

Sample Call

curl --location --request GET ‘https://sandbox-api.hostfully.com/v2/properties agencyUid=<AGENCY_UID>' \
--header 'X-HOSTFULLY-APIKEY: <YOUR_API_KEY>' \

3.3 Using the GraphQL interface

By leveraging GraphQL interface, you can define which fields would you like to pull in on every call. In the below example there’s only UID and name of a property being fetched from the server.

Sample Call

curl --location --request POST 'https://sandbox-api.hostfully.com/v2/propertiesql' \
--header 'Content-Type: application/json' \
--header 'X-HOSTFULLY-APIKEY: <YOUR_API_KEY>' \
--data-raw '{
"query":"{
properties(agencyUid:\"3593fab6-71ba-4317-a3c0-be3365180c7b\") {UID, name}
}","variables":{}}'

propertiesql/ endpoint is fully capable read-only graphql endpoint, therefore you can introspect for schema and get current data model back:

Sample Call

curl --location --request POST 'https://sandbox-api.hostfully.com/v2/propertiesql' \
--header 'Content-Type: application/json' \
--header 'X-HOSTFULLY-APIKEY: <YOUR_API_KEY>' \
​--data-raw '{"query":"{\n __schema {\n queryType {\n name\n }\n ,\n types{\n name,\n fields{\n name,\n type{\n name,\n kind\n }\n }\n }\n }\n}","variables":{}}'


4 Retrieving leads and booking


A lead in Hostfully Platform lingo is an inquiry. This mostly comes from channels that do not require instant bookings. A booking will still be a “Lead” object with a different status (such as BOOKED or PAID_IN_FULL).

For more details on lead management, please refer to this section: https://dev.hostfully.com/reference#leads-info

4.1 Registering webhooks

Registering webhook dedicated for an agency (NEW_BOOKING, BOOKING_UPDATED ...):

Sample Call:

curl --location --request POST 'https://sandbox-api.hostfully.com/v2/webhooks' \
​--header 'Content-Type: application/json' \
--header 'X-HOSTFULLY-APIKEY: <YOUR_API_KEY>' \
--data-raw '{
"agencyUid" : "agencyUid",
"objectUid" : "agencyUid",
​ "eventType" : "BOOKING_UPDATED",
​ "webHookType" : "POST_JSON",
"callbackUrl" : "https://yoursite.com"
}'

4.2 Getting leads and bookings


Sample Call

curl --location --request GET 'https://sandbox-api.hostfully.com/v2/leads?agencyUid=3593fab6-71ba-4317-a3c0-be3365180c7b' \
--header 'X-HOSTFULLY-APIKEY: <YOUR_API_KEY>'

Please feel free to report issues by sending emails to api@hostfully.com. If you want to send us API feature requests, you can do so from UserVoice.

Did this answer your question?