HoufyOpen API Docs
API reference llms.txt Support
Houfy Open API › Get started

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.

The base URL is https://api.houfy.com. Send and expect Content-Type: application/json on every call.

Quickstart

1

Set your credentials

Export both values as environment variables. The commands below read them from $HOUFY_AUTHTOKEN and $HOUFY_AUTHKEY.

Shell
export HOUFY_AUTHTOKEN="your-token-here"
export HOUFY_AUTHKEY="your-key-here"
2

Make your first API call

List the (100% complete) listings on your account:

cURL
curl https://api.houfy.com/users/listings \
  -H "Authtoken: $HOUFY_AUTHTOKEN" \
  -H "Authkey: $HOUFY_AUTHKEY" \
  -H "Content-Type: application/json"
3

Read the response

Each listing arrives with its verification and completion state. Note that numeric ids are serialized as strings on this endpoint.

Response · 200
{
  "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.

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.

1

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.

Request body · body.json
{
  "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
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
Response · 200
{
  "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:

Response · 200 (rejected)
{
  "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"
}
2

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.

Response · 200 (images, shortened)
{
  "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.

3

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.
  • caption sets the caption, "" clears it, and an item without caption keeps the current one.
  • Filenames that are not photos of this listing are skipped and returned in images_not_found.
Request body
{
  "images": [
    {
      "filename": "201/9cc0c558da4ade6ab2d1e3ad16a34481.jpg",
      "caption": "Lake view from the deck"
    },
    {
      "filename": "201/1cf43180081c6f711181f7001f5f0fed.jpg",
      "caption": ""
    },
    {
      "filename": "201/b514996fa8b6e115a25aabd47e603a80.jpg"
    }
  ]
}
Response · 200
{
  "success": "yes",
  "msg": "",
  "percentage": 100,
  "images_not_found": []
}
4

Delete photos

POST /listings/delete_photo/{id} with the stored filenames. The deletion completes within about a minute.

Request body
{
  "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.

Request body · clear values
{
  "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.