Listings API reference

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

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

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

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`
`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.

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

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

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 or firm’s plan does not allow the request
`404`	The listing was not found
`409`	The update conflicts with a newer or different update
`422`	Google could not verify the address, or the listing is missing something required to publish
`429`	Too many requests; wait for the `Retry-After` value
`503`	Address verification is temporarily unavailable; wait for `Retry-After`

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