Connect your software

Introducing the Listings APIVideo · 0:56

The Listings API lets your own software create listings in UnitBook, update them, and take them down. A firm owner starts the connection, then gives the details on this page to the person who maintains that software.

Generate the key

1. Open Settings, then API.

2. Click Generate API key.

3. The key stays on this page, so you can come back and copy it any time.

4. Under Hand off to your developer, copy it as a ready message, a .env file, or a first request, and send it to the person connecting your software. A password manager or secret-sharing tool is the safest way to send it. The message links to this guide for the API address and request examples.

One key per firm

Your firm has one active API key. Replace key turns off the old key as soon as the new one is created. Existing listings and their IDs stay the same.

Check the connection

Set these two values on your server, then run the request. Never place the key in code sent to a web browser or mobile app.

export UNITBOOK_API_URL="https://api.unitbook.app/v1"
export UNITBOOK_API_KEY="YOUR_API_KEY"

curl "$UNITBOOK_API_URL/me" \
  --header "Authorization: Bearer $UNITBOOK_API_KEY"

A successful response names the firm connected to the key.

Create or update a listing

Give every listing a stable ID from your own system. Keep using the same ID for later updates to that unit.

curl --request PUT "$UNITBOOK_API_URL/listings/webster-74-3b" \
  --header "Authorization: Bearer $UNITBOOK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": {
      "line_1": "74 Webster Avenue",
      "city": "Jersey City",
      "state": "NJ",
      "postal_code": "07307",
      "country": "US"
    },
    "unit": "3B",
    "bedrooms": 2,
    "bathrooms": 1,
    "monthly_rent": 2450,
    "availability_status": "available",
    "publication_status": "published"
  }'

The first request creates the listing. Sending PUT again with the same ID updates it. Add source_updated_at with your system’s last-changed time when updates may arrive out of order.

Every PUT needs a complete address object, unit, and number of bedrooms. UnitBook verifies the building with Google and returns the formatted address, Google place ID, and coordinates. If Google cannot match a precise premises, the request returns 422 with the fields that need attention. A listing also needs either a monthly rent or voucher type before it can be published.

Add photos

Add a photos list to the same request, in the order they should appear. The first photo is the cover.

"photos": [
  { "url": "https://example.com/photos/74-webster-3b-living-room.jpg" },
  { "url": "https://example.com/photos/74-webster-3b-kitchen.jpg" }
]

UnitBook downloads each photo in the background. Each one shows processing in the response until it’s ready. Send the full list every time. Dropping a URL removes that photo, and leaving photos out changes nothing.

Change a status or take a listing down

Use PATCH when only a few fields changed.

curl --request PATCH "$UNITBOOK_API_URL/listings/webster-74-3b" \
  --header "Authorization: Bearer $UNITBOOK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"availability_status":"rented_out"}'

rented_out and unavailable take the listing down automatically. Marking it available later does not publish it again unless the request also includes "publication_status":"published".

To take a listing down without changing its availability, send DELETE to the same listing address. This hides the listing instead of erasing it.

For every field, status, response, and limit, see the Listings API reference.