Skip to content
UnitBookUnitBook Academy

What do you do at your firm?

We'll show you the guides for your role. You can change it any time from the top of the sidebar.

Listings API reference

Introducing the Listings APIVideo · 0:56

Use this base URL for every request:

https://api.unitbook.app/v1

Send your firm’s one active key with every request:

Authorization: Bearer YOUR_API_KEY

A key works for one year from the day it’s generated. Replace it in Settings → API before then. Keys belong in server-side secret storage. Never put one in browser or mobile app code. Download the OpenAPI definition for a machine-readable version of this reference.

Requests

Section titled “Requests”
Request What it does
GET /me Checks the key and returns the firm
GET /listings Lists the firm’s API listings
GET /listings/{external_id} Gets one listing
PUT /listings/{external_id} Creates or replaces one listing
PATCH /listings/{external_id} Updates only the fields you send
DELETE /listings/{external_id} Hides a listing without erasing it

external_id is the listing’s ID in your system. It must stay the same for the life of that listing. Use 1 to 128 letters, numbers, periods, underscores, tildes, or hyphens. Start with a letter or number.

Listing fields

Section titled “Listing fields”

JSON field names use lowercase letters and underscores.

Field Accepted value
address Complete object with line_1, city, state, postal_code, and two-letter country; required for PUT
unit Text, required for PUT
bedrooms Number from 0 to 20, required for PUT
bathrooms Number from 0 to 20, or null
monthly_rent Number from 0 to 1,000,000, or null
voucher_requirement NHA, DCA, NHA_OR_DCA, or null
neighborhood Text or null
description Text up to 5,000 characters, or null
available_on A YYYY-MM-DD date, or null
availability_status One availability value from the next table
publication_status draft, published, or hidden
photos Up to 50 objects with an https url, in display order
source_updated_at An RFC 3339 date and time

UnitBook verifies every new or changed address with Google. It must resolve to a precise premises and match the supplied city, state, postal code, and country. The response includes formatted_address, google_place_id, latitude, longitude, and verified: true. Apartment or suite unit stays separate from the Google building address.

A published listing needs an address, bedrooms, and either monthly_rent or voucher_requirement. PUT clears optional fields you leave out. PATCH changes only the fields you send, and null clears an optional field. PATCHes without address and all DELETEs remain available if Google is temporarily down.

Photos

Section titled “Photos”

Send photos in the order they should appear. The first one 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" }
]
  • Leaving photos out keeps the listing’s photos as they are, on PUT too.
  • An empty array removes every photo the API added.
  • A URL you stop sending removes that photo. A new URL adds one.
  • Photos someone added in UnitBook stay put. API photos are shown first.

Each URL must be public https and return a JPEG, PNG, WebP, GIF, AVIF, or TIFF image up to 15 MB. UnitBook stores its own copy, so the photo stays up if the link later breaks. To change an image, send it at a new URL.

Photos download in the background, so the response doesn’t wait for them. Each listing response lists its photos with a status:

Status Meaning
processing Downloading
ready On the listing
failed Could not be added; error says why. Send the photos again to retry
removed Someone deleted it in UnitBook. It stays off while you keep sending the URL

Availability

Section titled “Availability”
Value Meaning
vacant, available Ready to market
listing_shown Already shown
showing_scheduled Showing scheduled
application_pending Application pending
rented_out, unavailable Not available, always hidden from brokers

Changing a hidden listing back to available does not publish it. Send "publication_status":"published" when it should go live again.

Safe updates and limits

Section titled “Safe updates and limits”

Send source_updated_at when your system has a last-changed time. UnitBook ignores an older update, safely accepts an identical retry, and returns 409 when two different updates use the same time.

GET /listings accepts limit from 1 to 100 and returns 50 by default. Send the returned next_cursor as cursor to get the next page. The starting limit is 300 requests per key per minute.

Responses

Section titled “Responses”
Status Meaning
200, 201, 204 The request succeeded
400 A field or request needs correcting
401 The key is missing, invalid, expired, or turned off
403 The key does not allow the request, or the firm’s billing needs attention
404 The listing was not found
409 The update conflicts with a newer or different update
422 Google could not verify the address, the listing is missing something required to publish, or the firm has reached its plan’s listing limit
429 Too many requests; wait for the Retry-After value
503 Address verification is temporarily unavailable or already in progress for this address; wait for Retry-After and retry

Every response includes X-Request-Id. Keep it when reporting a problem to UnitBook.