Connect your software

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

Open Settings, then API.
Click Generate API key.
Copy the key and save it in your software’s secret manager. UnitBook only shows it once.
Send it to the person connecting your software. Use a secure password manager or secret-sharing tool, not email or a support message. Send them this guide for the API address and request examples.

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.

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.