> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/documentation/api-and-references/apartments.md).

# Apartments

The Pullbay Apartments API provides programmatic access to Apartments.com property listings, photos, floor plans, virtual tours, and renter reviews. Integrate rental-market data into your applications, dashboards, and analytics pipelines without scraping or manual lookups.

**Base URL:** `https://dashboard.pullbay.com/api`

## Overview

The Apartments service lets you:

* Search Apartments.com properties by location, with optional rent, bedroom, and bathroom filters
* Look up full details for a single property by its `propertyId`
* Fetch a property's photos, floor plans, and virtual tours
* Fetch renter reviews for a property, with replies/comments included

All endpoints are read-only `GET` requests against public Apartments.com data — you don't need to manage or own a listing of your own.

## Common Use Cases

**Rental Market Research** — Search a metro area or neighborhood by location to see the current mix of available properties, bed/bath configurations, and rent ranges.

**Competitive Rent Analysis** — Pull rent ranges and unit-level pricing for a set of properties in the same area to benchmark pricing against comparable listings.

**Lead Generation** — Identify properties matching a renter's criteria (location, rent, bed/bath counts) to power a search tool or lead-qualification workflow.

**Listing Enrichment** — Use Get Property and Get Property Images together to pull full descriptions, amenities, floor plans, and virtual tours into your own listing pages.

**Review Monitoring for Property Managers** — Use Get Property Reviews on a schedule to track new renter feedback and management responses over time.

## Endpoints

| Endpoint                                          | Description                   | Pagination          |
| ------------------------------------------------- | ----------------------------- | ------------------- |
| `GET /apartments/properties`                      | Search properties by location | `page` / `maxItems` |
| `GET /apartments/properties/{propertyId}`         | Get a property by ID          | —                   |
| `GET /apartments/properties/{propertyId}/images`  | Get images for a property     | —                   |
| `GET /apartments/properties/{propertyId}/reviews` | Get reviews for a property    | `page` / `maxItems` |

## Search Properties

Search Apartments.com properties by location with optional rent/bed/bath filters.

**Request**

```bash
GET /apartments/properties
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Default | Description                                                       |
| ---------- | ------- | -------- | ------- | ----------------------------------------------------------------- |
| `location` | string  | Yes      | —       | Location to search, 2–40 characters (e.g. `Seattle, WA`)          |
| `sort`     | string  | No       | —       | One of `default`, `lastUpdated`, `rentHighToLow`, `rentLowToHigh` |
| `minRent`  | number  | No       | —       | Minimum monthly rent, 0–999999999                                 |
| `maxRent`  | number  | No       | —       | Maximum monthly rent, 0–999999999                                 |
| `minBed`   | number  | No       | —       | Minimum bedroom count, 0–4                                        |
| `maxBed`   | number  | No       | —       | Maximum bedroom count, 0–4                                        |
| `minBath`  | number  | No       | —       | Minimum bathroom count, 0–3                                       |
| `maxBath`  | number  | No       | —       | Maximum bathroom count, 0–3                                       |
| `page`     | integer | No       | —       | Page number, 1–100. Mutually exclusive with `maxItems`            |
| `maxItems` | integer | No       | —       | One-shot bulk pull, 1–200 results. Mutually exclusive with `page` |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/apartments/properties" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d location="Seattle, WA" \
  -d minRent=1500 \
  -d maxBed=2 \
  -d page=1
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "swv1xf7",
      "name": "110 Roy Apartments",
      "bedRange": "Studio - 2 Beds",
      "rentRange": "$1,500 - $3,500",
      "address": {
        "streetAddress": "110 Roy St",
        "city": "Seattle",
        "state": "WA",
        "postalCode": "98109"
      }
    }
  ],
  "pagination": { "page": 1, "hasNextPage": true, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Response Schema**

| Field                                     | Type              | Description                                                       |
| ----------------------------------------- | ----------------- | ----------------------------------------------------------------- |
| `data`                                    | array             | Array of [ApartmentsProperty objects](#apartmentsproperty-object) |
| `pagination.page`                         | integer, nullable | Current page number (only set when using `page`)                  |
| `pagination.hasNextPage`                  | boolean, nullable | Whether another page is available                                 |
| `pagination.cursor` / `pagination.offset` | string, nullable  | Unused by this endpoint — always `null` here                      |
| `pricing.creditsCharged`                  | number            | Credits charged for this request                                  |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. There is no published flat rate.

## Get Property

Returns full details for an Apartments.com property. Use the `includeScore`, `includeModelDetails`, and `includeImages` flags to opt into extra fields.

**Request**

```bash
GET /apartments/properties/{propertyId}
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter             | Type                    | Required | Default | Description                                                  |
| --------------------- | ----------------------- | -------- | ------- | ------------------------------------------------------------ |
| `propertyId`          | string                  | Yes      | —       | Apartments.com property ID, 1–20 characters (path parameter) |
| `includeScore`        | string (`true`/`false`) | No       | —       | Include the property's rating in the response                |
| `includeModelDetails` | string (`true`/`false`) | No       | —       | Include detailed floor plan/model data                       |
| `includeImages`       | string (`true`/`false`) | No       | —       | Include photo/floor plan/tour data inline                    |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/apartments/properties/swv1xf7" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d includeScore=true \
  -d includeModelDetails=true
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "swv1xf7",
      "propertyName": "110 Roy Apartments",
      "url": "https://www.apartments.com/110-roy-apartments-seattle-wa/swv1xf7/",
      "propertyWebsite": "https://www.110royapts.example/",
      "lastUpdated": "2026-04-30T10:00:00.000Z",
      "description": "Modern apartments in the heart of Queen Anne.",
      "rating": 4.2,
      "beds": "Studio - 2 Beds",
      "baths": "1 - 2 Baths",
      "sqft": "500 - 1,200 sq ft",
      "baseRent": { "min": 1500, "max": 3500 },
      "totalRent": { "min": 1580, "max": 3620 },
      "location": {
        "streetAddress": "110 Roy St",
        "city": "Seattle",
        "state": "WA",
        "postalCode": "98109"
      },
      "coordinates": { "latitude": 47.6262, "longitude": -122.3521 },
      "contact": { "phone": "(206) 555-0110", "officeHours": "Mon-Fri 9am-6pm" },
      "specials": null,
      "schools": { "elementary": "John Hay Elementary", "district": "Seattle Public Schools" },
      "amenities": [
        { "category": "Unique Amenities", "items": ["In Unit Washer & Dryer", "Rooftop Deck"] }
      ],
      "fees": [
        { "name": "Application Fee", "amount": "$45" }
      ],
      "models": [
        { "name": "Studio A", "beds": 0, "baths": 1, "sqft": 500 }
      ],
      "rentals": [
        { "unit": "204", "rent": 1750, "sqft": 540, "availability": "2026-07-01" }
      ],
      "transportation": [
        { "type": "Transit", "name": "Route 8", "distance": "0.1 mi" }
      ],
      "transitAndPOI": [
        { "type": "Grocery", "name": "QFC Queen Anne", "distance": "0.3 mi" }
      ]
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                                                   |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------- |
| `data`                   | array  | Array containing a single [ApartmentsPropertyDetail object](#apartmentspropertydetail-object) |
| `pricing.creditsCharged` | number | Credits charged for this request                                                              |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. There is no published flat rate.

## Get Property Images

Returns photos, floor plans, virtual tours, and extended virtual tours for a property.

**Request**

```bash
GET /apartments/properties/{propertyId}/images
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter    | Type   | Required | Default | Description                                                  |
| ------------ | ------ | -------- | ------- | ------------------------------------------------------------ |
| `propertyId` | string | Yes      | —       | Apartments.com property ID, 1–20 characters (path parameter) |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/apartments/properties/swv1xf7/images" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "photos": [
        { "url": "https://images1.apartments.com/i2/swv1xf7-1/110-roy-apartments-seattle-wa.jpg", "caption": "Building exterior" }
      ],
      "floorPlans": [
        { "name": "Studio A", "url": "https://images1.apartments.com/i2/swv1xf7-floorplan-1/studio-a.jpg" }
      ],
      "virtualTours": [
        { "name": "Studio A 3D Tour", "url": "https://my.matterport.com/show/?m=example1" }
      ],
      "virtualTourExtended": [
        { "name": "Full Property Walkthrough", "url": "https://my.matterport.com/show/?m=example2" }
      ]
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                                                   |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------- |
| `data`                   | array  | Array containing a single [ApartmentsPropertyImages object](#apartmentspropertyimages-object) |
| `pricing.creditsCharged` | number | Credits charged for this request                                                              |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. There is no published flat rate.

## Get Property Reviews

Returns reviews for an Apartments.com property.

**Request**

```bash
GET /apartments/properties/{propertyId}/reviews
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter    | Type    | Required | Default | Description                                                       |
| ------------ | ------- | -------- | ------- | ----------------------------------------------------------------- |
| `propertyId` | string  | Yes      | —       | Apartments.com property ID, 1–20 characters (path parameter)      |
| `page`       | integer | No       | —       | Page number, 1–100. Mutually exclusive with `maxItems`            |
| `maxItems`   | integer | No       | —       | One-shot bulk pull, 1–200 results. Mutually exclusive with `page` |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/apartments/properties/swv1xf7/reviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d page=1
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "key": "r-12345",
      "title": "Loved living here",
      "text": "Great staff and amenities. Highly recommend!",
      "rating": 4.5,
      "submissionDate": "Apr 30, 2026",
      "isOwner": false,
      "positiveFeedbackCount": 3,
      "comments": [
        { "author": "Property Manager", "text": "Thank you for the kind words!" }
      ]
    }
  ],
  "pagination": { "page": 1, "hasNextPage": true, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Response Schema**

| Field                                     | Type              | Description                                                                   |
| ----------------------------------------- | ----------------- | ----------------------------------------------------------------------------- |
| `data`                                    | array             | Array of [ApartmentsPropertyReview objects](#apartmentspropertyreview-object) |
| `pagination.page`                         | integer, nullable | Current page number (only set when using `page`)                              |
| `pagination.hasNextPage`                  | boolean, nullable | Whether another page is available                                             |
| `pagination.cursor` / `pagination.offset` | string, nullable  | Unused by this endpoint — always `null` here                                  |
| `pricing.creditsCharged`                  | number            | Credits charged for this request                                              |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. There is no published flat rate.

## Errors

All non-2xx responses share the same envelope:

```json
{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}
```

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `400`  | Bad request — missing/invalid parameters |
| `402`  | Insufficient credits                     |
| `404`  | Property or review set not found         |

## Object Schema

### ApartmentsProperty object

| Field       | Type   | Description                                             |
| ----------- | ------ | ------------------------------------------------------- |
| `id`        | string | Apartments.com property ID                              |
| `name`      | string | Property name                                           |
| `bedRange`  | string | Bedroom range across all units (e.g. `Studio - 2 Beds`) |
| `rentRange` | string | Rent range across all units (e.g. `$1,500 - $3,500`)    |
| `address`   | object | Property address fields                                 |

### ApartmentsPropertyDetail object

| Field             | Type               | Description                                                 |
| ----------------- | ------------------ | ----------------------------------------------------------- |
| `id`              | string             | Apartments.com property ID                                  |
| `propertyName`    | string             | Property name                                               |
| `url`             | string             | Apartments.com listing URL                                  |
| `propertyWebsite` | string             | Property's own website                                      |
| `lastUpdated`     | string (date-time) | When the listing was last updated                           |
| `description`     | string             | Property description                                        |
| `rating`          | number             | Average rating (present when `includeScore=true`)           |
| `beds`            | string             | Bedroom range                                               |
| `baths`           | string             | Bathroom range                                              |
| `sqft`            | string             | Square footage range                                        |
| `baseRent`        | object             | Base rent range                                             |
| `totalRent`       | object             | Total rent range (including estimated fees)                 |
| `location`        | object             | Address fields                                              |
| `coordinates`     | object             | `latitude` / `longitude`                                    |
| `contact`         | object             | Contact info (phone, office hours, etc.)                    |
| `specials`        | object, nullable   | Current leasing specials, if any                            |
| `schools`         | object             | Nearby school info                                          |
| `amenities`       | array              | Amenity categories and items                                |
| `fees`            | array              | Fee names and amounts                                       |
| `models`          | array              | Floor plan models (present when `includeModelDetails=true`) |
| `rentals`         | array              | Individual available units                                  |
| `transportation`  | array              | Nearby transit options                                      |
| `transitAndPOI`   | array              | Nearby transit and points of interest                       |

### ApartmentsPropertyImages object

| Field                 | Type  | Description                      |
| --------------------- | ----- | -------------------------------- |
| `photos`              | array | Property photos                  |
| `floorPlans`          | array | Floor plan images                |
| `virtualTours`        | array | Virtual tour links               |
| `virtualTourExtended` | array | Extended/full virtual tour links |

### ApartmentsPropertyReview object

| Field                   | Type    | Description                                             |
| ----------------------- | ------- | ------------------------------------------------------- |
| `key`                   | string  | Review ID                                               |
| `title`                 | string  | Review title                                            |
| `text`                  | string  | Review body                                             |
| `rating`                | number  | Rating, e.g. out of 5                                   |
| `submissionDate`        | string  | Date the review was submitted (e.g. `Apr 30, 2026`)     |
| `isOwner`               | boolean | Whether the reviewer is the property owner/manager      |
| `positiveFeedbackCount` | integer | Number of "helpful" votes                               |
| `comments`              | array   | Replies to the review (e.g. property manager responses) |

## Finding Property IDs

* A property's `propertyId` is returned by the Search Properties endpoint above — use the `id` field from a search result to look up that property's detail, images, or reviews.
* Either run a location search first to discover IDs, or reuse a `propertyId` you've already obtained from a prior search response.

## Sort and Flag Values

* `sort` (Search Properties) accepts exactly one of: `default`, `lastUpdated`, `rentHighToLow`, `rentLowToHigh`.
* `includeScore`, `includeModelDetails`, and `includeImages` (Get Property) are each typed as a string enum of the literal values `"true"` / `"false"` — pass the string, not a real boolean.

## Python Example

This example searches for properties in a location and paginates through results until `pagination.hasNextPage` is `false` or the page cap (10) is reached:

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://dashboard.pullbay.com/api"

def search_all_properties(location, max_pages=10):
    all_properties = []
    page = 1
    while page <= max_pages:
        resp = requests.get(
            f"{BASE_URL}/apartments/properties",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"location": location, "sort": "lastUpdated", "page": page},
        )
        resp.raise_for_status()
        body = resp.json()
        all_properties.extend(body["data"])
        if not body.get("pagination", {}).get("hasNextPage"):
            break
        page += 1
    return all_properties

properties = search_all_properties("Seattle, WA")
print(f"Fetched {len(properties)} properties")
```

Each request is billed independently, with the charged amount reported in that response's `pricing.creditsCharged` — there's no separate "fetch everything in one call" endpoint, so a multi-page pull like this makes one request per page.

## FAQ

<details>

<summary>How do I find a property's ID?</summary>

Run a Search Properties request for the location you're interested in, then read the `id` field off any result in `data`. Use that value as the `propertyId` path parameter on the detail, images, and reviews endpoints.

</details>

<details>

<summary>What's the difference between `baseRent` and `totalRent` on Get Property?</summary>

`baseRent` is the property's base rent range; `totalRent` is the rent range including estimated fees. Both are returned as min/max objects.

</details>

<details>

<summary>Can I get a property's photos without calling the images endpoint separately?</summary>

Yes — pass `includeImages=true` on Get Property to receive image data inline, or call Get Property Images directly if you only need photos/floor plans/tours.

</details>

<details>

<summary>How many properties or reviews can I fetch in one call?</summary>

Up to 200 with `maxItems`, or up to 100 pages via `page` (page size isn't fixed by the spec). `page` and `maxItems` are mutually exclusive — use one or the other per request.

</details>

<details>

<summary>Can I filter reviews by rating?</summary>

The API doesn't expose a server-side rating filter for reviews. Fetch the reviews you need and filter client-side on the `rating` field.

</details>

<details>

<summary>What's the credit cost per request?</summary>

It's dynamic — every response includes `pricing.creditsCharged` with the exact amount for that call. There's no fixed published rate per endpoint or per result.

</details>

## Next Steps

* [**API Integration Guide**](broken://pages/68e75ab1a73d266350bd68301be87ff97cad563e) — integrate the Pullbay API into your backend application.
* [**n8n Integration Guide**](broken://pages/4308164455b56bbc694cf74c9768ea689c2fe719) — set up automated workflows using n8n with no coding required.
* [**Services Overview**](broken://pages/0d55376cbcca70097a683a71a593d3077825dbf1) — explore all available Pullbay services.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pullbay.com/documentation/api-and-references/apartments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.