> 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://api.pullbay.com`

## 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://api.pullbay.com/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://api.pullbay.com/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://api.pullbay.com/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://api.pullbay.com/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://api.pullbay.com"

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.