Docs

Docs / Integrations / Hostfully integration

Hostfully

Each booking in Hostfully sends the guest the agreement and waivers that property needs, read back from Hostfully so what they sign matches the booking.

Beta. Built against Hostfully's published API documentation and tested against stand-ins on our side, which is what beta means here: it has not yet run against a live Hostfully account. It uses the API key from your own Agency Settings, which Hostfully shows on plans that include API access; a listing in Hostfully's Integration Zone is a separate program we have not joined. Links go by email. They go by text only to a guest whose consent to receive texts from you is on file in SignSealer: a booking system knowing a phone number is not that guest agreeing to be texted, and SignSealer never treats it as if it were. Texts go from your business's own number, which is coming soon.

Before you start

  • The membership: connecting a booking system comes with it (how that works). On Free, your 10 signings a month are sent from the dashboard.
  • A SignSealer account with the terms signed and a published form for each document.
  • A Hostfully plan that includes API access. Hostfully shows the API key under Agency Settings only then; its billing team adds it.
  • Once it is connected, documents chosen on its page for what each property's bookings need.

Connect Hostfully

  1. In Hostfully, open Agency Settings. Copy the API key, under API, and the agency UID, at the bottom of the page.
  2. In SignSealer, open Integrations, choose Hostfully → Connect, and paste both.
  3. Choose the settings and press Connect Hostfully. SignSealer reads your agency from Hostfully with the key, which proves the key and the UID together, then registers its webhooks on the agency.
  4. Make a test booking in Hostfully and watch it arrive under the connection's activity.

What SignSealer sets up in Hostfully

Three webhooks (POST /api/v3/webhooks) on your agency, one each for NEW_BOOKING, BOOKING_UPDATED and BOOKING_CANCELLED, sending JSON to this connection's delivery address. If Hostfully refuses one, those already made are deleted again and nothing is connected. Disconnecting deletes all three; a new address deletes them and registers three more.

What comes across

HostfullyIn SignSealerNotes
uidReservation external IDThe lead's UID, so every update is the same reservation
property name, externalBookingIdLabel“Lighthouse Cabin · HA-77120”; the name is read from the property, and the start of the UID stands in for a missing booking ID
checkInLocalDateTime / checkOutLocalDateTimeStarts on / ends onThe property's own dates
guestInformation: firstName + lastName, email, cellPhoneNumber or phoneNumberPrimary guestHostfully gives a lead's guest no ID of their own; they are the lead's primary guest on every update
adultCount, childrenCount, infantCount, petCountFacts: guests, adults, minors, petsGuests counts adults, children and infants; minors counts children and infants
channel, or source where there is no channelFact: channelLower-cased: airbnb, vrbo, booking_com, hostfully …
propertyUidFacts: property, property_name
statusWhat happensBOOKED: worked · inquiries (NEW, ON_HOLD, CLOSED), booking requests (PENDING, DECLINED) and blocks: ignored · CANCELED: canceled

Documents that read it

The reservation carries these facts, which a document's Only bookings where can read: guests, adults, minors, pets, channel, property and property_name. For example, a waiver for every adult on stays with more than six guests is Each adult, Only bookings where guests is more than 6.

Documents are chosen under Documents for bookings on the connection's page in Integrations (there is no API route for them yet); see Reservations and packets.

How a delivery is proven

Hostfully does not sign its webhooks, and a delivery carries only the agency, the event, the lead's UID and its property's UID. The 64-character token in the delivery address is the secret; the delivery is used only to learn which lead changed, and the lead is always read back from Hostfully's API with your key before anything is built from it. A forged delivery can at most make SignSealer re-read one of your own bookings. Other events, such as messages, are accepted and ignored. Hostfully sends the same words for every change to a lead, so a delivery counts as a repeat only when it arrives in the same second as the one before; a later one is always read.

Settings

SettingChoicesWhat it does
When a booking arrivesSend straight away (default) · Build the list and wait Straight away starts everything the packet owes as soon as the booking is worked. Waiting builds the reservation and its packet and sends nothing until somebody presses Send on the reservation, or your code calls POST /v1/packets/{id}/start.
When a booking is canceledVoid what nobody has signed (default) · Leave it Voiding marks every unfinished document with the reason and the packet void. Anything already signed is kept: an executed waiver is evidence of what was agreed.

What each guest is sent is decided by the connection's documents for bookings, chosen on its page: each says which document, who signs it — the person who booked, every adult, or a parent or guardian for each minor — and which bookings, read from the reservation's facts (dates, guest counts, property, channel). A default covers the bookings nothing else fits, and a booking that matched nothing says so in the connection's activity (Reservations and packets).

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through POST /v1/sms-consents, or on SignSealer's own opt-in. That check runs when the link is queued (app.may_text), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — VERIFIED_CONSENT, NO_CONSENT or INSUFFICIENT_EVIDENCE — and only NO_CONSENT changes anything: the guest's number is not written at all. Every provider built so far can only ever say INSUFFICIENT_EVIDENCE. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

How to record consent you took yourself.

Duplicates, order and retries

  • Once. A delivery is recorded once per connection and event id. A provider that redelivers the same event gets 200 {"duplicate": true} and nothing happens twice.
  • Newest wins. Each event means "read this booking as it is now". A newer event about a booking supersedes an older one still waiting, and one booking is never worked twice at once.
  • Nothing is sent twice. Guests are recognized by their id in the provider (or by address and name), so an update keeps each guest's link to what they were already sent.
  • Retries. A failure is retried after 1, 2, 4, 8 … minutes, up to six hours apart, and gives up after eight tries. It is then listed, with its reason, under the connection's activity, where it can be tried again once whatever refused it is fixed.
  • The reason is in our words. What the activity says of a failure is one plain sentence about what happened and what to do: the provider refused our credentials, did not answer, is limiting us, answered with an error, or says the booking or listing does not exist. It carries the provider's status code where there is one, such as (422), and a short reference to quote if you write to us. What the provider itself wrote back is not kept or shown, because it can quote a guest's name, email or phone.
  • Refused credentials. If the provider refuses SignSealer's credentials, the connection goes to needs attention and stops working events until new credentials are given. What arrives meanwhile is kept and worked afterwards.
  • Retention. What arrived is cleared thirty days after it was worked; the outcome and the reservation it made are kept.

Troubleshooting

What you seeWhyWhat to do
“Hostfully refused our credentials” when connectingThe API key is wrong or was replaced, or it may not read that agencyCopy the key and the agency UID again from Agency Settings
“Hostfully has no such record” when connectingThe agency UID is not one the key can readCopy the agency UID from the bottom of Agency Settings
No API key in Agency SettingsYour Hostfully plan does not include API accessAsk Hostfully's billing team to add it
Needs attention after it workedHostfully stopped accepting the keyPaste a new key on the connection's page
An inquiry or a booking request never arrives as a reservationOnly a booked lead is a bookingIt is worked when it is booked in Hostfully
The guest is named “Guest”, with no emailHostfully sent the guest's details as HIDDEN, which it does for a key that may not see themConnect with the API key from your own Agency Settings
A guest got nothingNo email on the lead, or no document fits the bookingThe activity names the guest and the reason, or says nothing fitted

Hostfully's limits

Hostfully limits calls per hour: its developer portal gives 10,000 an hour per caller, and its help center a default of 1,000. It blocks a caller that abuses them. SignSealer reads the lead once per delivery and, for a booking, its property once. Hostfully calls only HTTPS addresses, and does not document retrying a delivery that fails.

Hostfully's Integration Zone

This connection uses the API key from your own Agency Settings. Partners listed in Hostfully's Integration Zone connect through Hostfully's OAuth flow instead, and Hostfully withholds guests' personal details from them. A listing there would be a separate connection.

Pausing and disconnecting

Pause keeps recording what arrives and works nothing until you resume. New address stops the old delivery address at once (and re-registers the webhook with the provider where SignSealer set it up). Disconnect revokes the connection's key, clears its credentials, removes the webhook from the provider where it can, and closes the address. The reservations and documents it made stay, with where they came from.

From your own code

curl https://api.signsealer.com/v1/integrations -H "Authorization: Bearer $KEY"
curl https://api.signsealer.com/v1/integrations/$CONNECTION/events -H "Authorization: Bearer $KEY"

The first lists every provider with its status and your connections with their state; the second is what arrived from one connection and what became of it. Neither ever returns a credential, a delivery address or what arrived. Both need the signing:read scope. Connecting happens in the dashboard, where the provider confirms the credentials. See the API reference.

This page as Markdown Ask an AI about it: ChatGPT · Claude · Perplexity · Google AI · Grok

Ready to build? An API key takes a minute in the portal, and the free plan covers the first 10 agreements a month.

Get an API key