Building Units API

Overview

Returns a JSON array of every unit in a building that is flagged advertised_on_website: true. Use it to power a building's listings page, a unit picker on a tour-request form, or any frontend that needs an up-to-date catalog of what's available.

• One building per request, identified by its token.
• Narrow the results with optional query-parameter filters — beds, baths, rent, outdoor space, status, and more. See Filtering & search.
• Units that aren't advertised on the website are excluded from the response.
• Units whose price is marked private (price_advertised: false) are still returned, but with monthly_rent_gross and monthly_rent_net set to null.

Authentication

There is no API key or bearer token. Each building has its own opaque token, and you pass it as a query parameter to fetch that building's units.

• A SeeClickRent admin issues the token to you when your integration is set up.
• It's the same token you'd use with the Website Leads API — one token per building, used for both reading units and posting leads.
• Treat the token like a shared secret — anyone with it can read advertised inventory for that building.

Rate limits

• 300 requests per 5 minutes per source IP across the entire /api/* namespace.
• Excess requests get an HTTP 429 Too Many Requests with a Retry-After header (in seconds) and this body:

{
  "error": {
    "message": "throttled",
    "human_message": "Too many requests. Please try again later."
  }
}

If you're rendering a high-traffic listings page, cache the response on your end (a few minutes is usually plenty — inventory doesn't change second-to-second). Contact SeeClickRent if you need a higher limit.

Request

Headers

Accept: application/json

Query parameters

Only token is required. Every other parameter is an optional filter — combine as many as you like to narrow the results (see Filtering & search). Omitting all filters returns every advertised unit.

Example

GET /api/v1/building_units?token=abc123def456 HTTP/1.1
Host: seeclickrent.com
Accept: application/json

Filtering & search

All filtering happens server-side via query parameters — there is no separate search endpoint. Each filter you add is combined with AND, so the response only contains units that match every filter. Parameters you leave off are simply not applied.

• bed matches exactly and accepts a comma-separated list (e.g. bed=0,1 for studios and one-bedrooms).
• bath, min_rent, max_rent, and min_square_feet are range bounds (greater-than-or-equal / less-than-or-equal), not exact matches.
• outdoor and status accept a comma-separated list and match any of the listed values. Unrecognized values are ignored.
• Filtering never overrides the base rules: units that aren't advertised_on_website are always excluded, and private-price units still return with null rent.

Common recipes

Response

200 OK — success

Returns a JSON array. Each element represents one advertised unit. The array is empty ([]) if the building has no units flagged for the website.

[
  {
    "id": 9821,
    "building_id": 412,
    "floor": 2,
    "unit": "2A",
    "bed": 1,
    "bath": 1.0,
    "exposure": "South",
    "outdoor": "balcony",
    "status": "available",
    "monthly_rent_gross": 3200.0,
    "monthly_rent_net": 2933.33,
    "square_feet": 675,
    "weeks_free": 4,
    "months_free": 1,
    "lease_term": 13,
    "floor_plan": {
      "original": "https://seeclickrent.com/rails/active_storage/blobs/.../floor-plan.pdf",
      "thumbnail": "https://seeclickrent.com/rails/active_storage/representations/.../floor-plan.png"
    },
    "images": [
      {
        "original": "https://seeclickrent.com/rails/active_storage/blobs/.../living-room.jpg",
        "thumbnail": "https://seeclickrent.com/rails/active_storage/representations/.../living-room.jpg"
      }
    ],
    "price_advertised": true,
    "date_available": "2026-06-01",
    "created_at": "2026-04-12T18:22:13.000Z",
    "updated_at": "2026-05-02T10:14:55.000Z"
  }
]

Field reference

Every object in the response array contains the following keys:

Images and floor plans

Both floor_plan and each entry in images use the same shape:

{
  "original": "https://seeclickrent.com/rails/active_storage/blobs/.../photo.jpg",
  "thumbnail": "https://seeclickrent.com/rails/active_storage/representations/.../photo.jpg"
}

• original is the full-resolution upload.
• thumbnail is a 400x400 contained variant, generated lazily on first request — the first hit may be slightly slower while it's processed; subsequent hits are served from cache.
• thumbnail may be null for non-image attachments (e.g. PDF floor plans without a renderable preview).
• floor_plan itself is null if no floor plan has been uploaded.
• URLs are signed and long-lived but not guaranteed to be permanent — always re-fetch from this endpoint rather than caching URLs forever.

Code samples

# All advertised units for the building
curl -G https://seeclickrent.com/api/v1/building_units \
  -H "Accept: application/json" \
  --data-urlencode "token=abc123def456"

# Filtered: 2-bedrooms with at least 1 bath and outdoor space
curl -G https://seeclickrent.com/api/v1/building_units \
  -H "Accept: application/json" \
  --data-urlencode "token=abc123def456" \
  --data-urlencode "bed=2" \
  --data-urlencode "bath=1" \
  --data-urlencode "outdoor=any"

const token = "abc123def456";

// Build a filtered query: just the one-bedrooms under $4,000/mo
const params = new URLSearchParams({
  token,
  bed: "1",
  max_rent: "4000",
  status: "available",
});
const url = `https://seeclickrent.com/api/v1/building_units?${params}`;

const response = await fetch(url, {
  method: "GET",
  headers: { "Accept": "application/json" },
});

if (response.ok) {
  const units = await response.json();
  console.log(`Loaded ${units.length} units`);
} else {
  console.error("Failed to load units:", response.status);
}

import requests

# Studios and one-bedrooms with a balcony or terrace
resp = requests.get(
    "https://seeclickrent.com/api/v1/building_units",
    params={
        "token": "abc123def456",
        "bed": "0,1",
        "outdoor": "balcony,terrace",
    },
    headers={"Accept": "application/json"},
    timeout=10,
)

if resp.status_code == 200:
    units = resp.json()
    print(f"Loaded {len(units)} units")
elif resp.status_code == 429:
    retry_after = int(resp.headers.get("Retry-After", "60"))
    print(f"Throttled, retry in {retry_after}s")
else:
    print(f"Failed: {resp.status_code} {resp.text}")

Troubleshooting

Support

For tokens, building setup, or rate-limit increases, reach out to your SeeClickRent point of contact or contact us.