Get started with the Houfy API
Make your first API call and connect your inventory to the direct-booking marketplace — listings, rates, availability, reservations and guest messaging over plain JSON REST.
Authentication
Every request carries two headers. A missing or invalid Authtoken or Authkey gets an empty 401: ask the host to reconnect. A listing the account can't manage (it neither owns nor co-hosts it) gets a 403 with a msg: the credentials are fine. A host can manage its own listings before Houfy verifies them.
Authtoken— self-serve: in your Houfy account open Settings & Privacy → API access token and generate one.Authkey— identifies your integration and is issued privately by Houfy. Email info@houfy.com; request it before your build starts.- Rate limit — 60 requests per minute per
Authkey, shared by every host you connect through it. Spread bulk syncs (e.g. rate pushes across a large portfolio) over time, and use the booking webhooks instead of polling reservations.
https://api.houfy.com. Send and expect Content-Type: application/json on every call.Quickstart
Set your credentials
Export both values as environment variables. The commands below read them from $HOUFY_AUTHTOKEN and $HOUFY_AUTHKEY.
export HOUFY_AUTHTOKEN="your-token-here" export HOUFY_AUTHKEY="your-key-here"
Make your first API call
List the (100% complete) listings on your account:
curl https://api.houfy.com/users/listings \ -H "Authtoken: $HOUFY_AUTHTOKEN" \ -H "Authkey: $HOUFY_AUTHKEY" \ -H "Content-Type: application/json"
Read the response
Each listing arrives with its verification and completion state. Note that numeric ids are serialized as strings on this endpoint.
{
"listings": [
{
"id": "77555",
"listingName": "Premium Villa with panoramic view",
"user_id": "51637",
"listing_photo": "https://www.assets.houfy.com/assets/images/properties/…",
"active": "Y",
"verified": "Y",
"percentage": "100",
"co_host": "N"
}
]
}
Downloads
Everything you need to explore the API in your own tools.
Postman collection
All 21 requests with auth headers, example bodies and per-field documentation.
Postman environment
base_url, authtoken, authkey, listing_id and rescode variables, ready to fill in.
OpenAPI 3.0 spec
The machine-readable source of truth behind this documentation, in YAML.
Using AI tools
Building the integration with a coding assistant? The complete
reference is published machine-readable — point your agent at
llms.txt, or hand it
the single-file markdown reference:
every endpoint with field types, required flags and example bodies in
one fetch.
Webhooks
Register a callback URL in your account settings (or via
POST /users/updateuser)
and Houfy notifies it with an HTTP GET carrying
notification_id, listing_id,
log_object and a unix timestamp. Reservation
events (req.acc, req.dec,
req.can, req.mark,
req.changed) are instant; other changes batch
every 10 minutes. Delivery is at-least-once within 24 hours — make your
receiver idempotent and never treat it as the only source of booking
state. Full object types are documented in the
Notifications section of the reference.
Listing photos
Photos are added from image URLs and imported in the background. Once imported, each photo has a
stored filename. Use that filename to set the order, the cover photo and
captions, or to delete the photo. The examples use listing 201.
Push the photos
POST /listings/push_photo/{id}.
Each item needs original_url: the full https:// URL of the
image file. Houfy downloads it, so it must open without a login or an expiring signature.
caption is optional. A bare filename is rejected.
{
"files": [
{
"original_url": "https://images.example.com/listing-201/lake-view.jpg",
"caption": "Lake view from the deck"
},
{
"original_url": "https://images.example.com/listing-201/deck.jpg"
}
]
}
curl -X POST https://api.houfy.com/listings/push_photo/201 \ -H "Authtoken: $HOUFY_AUTHTOKEN" \ -H "Authkey: $HOUFY_AUTHKEY" \ -H "Content-Type: application/json" \ -d @body.json
{
"filesresponse": [
{
"filename": "lake-view.jpg",
"original_url": "https://images.example.com/listing-201/lake-view.jpg",
"success": "yes"
},
{
"filename": "deck.jpg",
"original_url": "https://images.example.com/listing-201/deck.jpg",
"success": "yes"
}
],
"msg": "Files queued successfully; photos are processed asynchronously and appear within about a minute"
}
A rejected item has "success": "no" and an error saying why:
{
"filesresponse": [
{
"filename": null,
"original_url": "50fe40ddcf626770027a13ea23f0b018.jpg",
"success": "no",
"error": "original_url must be the full http(s) URL of a publicly reachable image, not a filename"
}
],
"msg": "No valid files supplied. Each item needs original_url, the full http(s) URL of a publicly reachable image"
}
Read the stored filenames
The photos appear within about a minute, after the existing photos, in the order you sent them.
GET /listings/getlistingdetails/{id}
then returns them in images, in display order. The first photo is the cover photo.
The filename push_photo returned is taken from your URL; the stored one is the one below.
{
"images": [
{
"filename": "201/9cc0c558da4ade6ab2d1e3ad16a34481.jpg",
"original_url": "https://www.assets.houfy.com/assets/images/properties/201/9cc0c558da4ade6ab2d1e3ad16a34481.jpg",
"caption": "Lake view from the deck"
},
{
"filename": "201/1cf43180081c6f711181f7001f5f0fed.jpg",
"original_url": "https://www.assets.houfy.com/assets/images/properties/201/1cf43180081c6f711181f7001f5f0fed.jpg",
"caption": "Deck"
}
]
}
If a photo hasn't appeared after a few minutes, Houfy couldn't download it. Check that the URL opens in a private browser window.
Set the order, cover photo and captions
POST /listings/update_listingdetails/{id}
with images. You can send the images array from getlistingdetails back as it is.
- The array order becomes the photo order. The first photo is the cover photo.
- Photos you leave out keep their current order, after the ones you list.
captionsets the caption,""clears it, and an item withoutcaptionkeeps the current one.- Filenames that are not photos of this listing are skipped and returned in
images_not_found.
{
"images": [
{
"filename": "201/9cc0c558da4ade6ab2d1e3ad16a34481.jpg",
"caption": "Lake view from the deck"
},
{
"filename": "201/1cf43180081c6f711181f7001f5f0fed.jpg",
"caption": ""
},
{
"filename": "201/b514996fa8b6e115a25aabd47e603a80.jpg"
}
]
}
{
"success": "yes",
"msg": "",
"percentage": 100,
"images_not_found": []
}
Delete photos
POST /listings/delete_photo/{id} with the stored filenames. The deletion completes within about a minute.
{
"files": ["201/b514996fa8b6e115a25aabd47e603a80.jpg"]
}
Updating listing content
POST /listings/update_listingdetails/{id} takes the shape getlistingdetails returns. Send only the groups and fields you want to change; everything you leave out stays as it is.
- Missing or
null: the field is unchanged. - A value: saved.
""for a text,0for a number: the field is cleared. This covers the headline, area, summary, about the owner, address, unit, floor, getting around, house rules, payment and cancellation policy, notes, minimum age, check-in text, and the amenity and suitability texts.- The listing name, guests, latitude and longitude always need a value. An empty one is ignored.
bedroomsreplaces the whole list: bedrooms and beds you leave out are deleted. Sendbedroomid/bed_idto keep existing ones.
{
"listingData": { "area": 0, "headline": "" },
"location": { "gettingaround": "" },
"policies": { "houserules": "", "minage": 0 }
}
The response is {"success": "yes", "msg": "", "percentage": 100} when anything was saved.
"success": "no" with "msg": "Nothing to update" means the body had no field that could be saved.