# Flatmates Room Search API Documentation

Scrappa's `GET /api/flatmates/search` returns Flatmates.com.au rooms and shared rentals in Australia as structured JSON.

## Rentals only

Flatmates lists rooms, shares and rentals. It has no sale listings, so this API has no sale parameter.

## What you get

One request returns one page of 12 rooms in `data`. Each room has `id`, `link`, `title`, `subtitle`, `description`, `rent` (display text, `min`, `max`, AUD, per week), `bills`, `date_available`, `suburb`, bedroom, bathroom and occupant counts, `photos` and `activated_at`. Call the listing endpoint with the `link` for rooms, deposit, address and the lister.

## Location

`location` is a city slug such as `sydney`, or the `key` of a suburb (`bondi-2026`), train station (`central-station-sydney`) or university (`uc`) from `/api/flatmates/location-autocomplete`. Station and university searches add `distance` to each room. An unknown location returns `422` (`upstream_rejected`).

## Filters are honoured

Flatmates applies every filter and the sort itself, and all of them combine. Flatmates reports the filters it applied. If one is missing from that report, the request returns `422` (`upstream_rejected`) instead of unfiltered rooms. A room whose weekly rent lies fully outside your budget is also removed. `pagination.filtered_out` counts them, so a page can hold fewer than 12 rooms. Unknown parameters and values are rejected with `422`. Filters not offered yet (bedrooms, date available) are not accepted rather than ignored.

## Pagination

`page` is 1-based and the label always equals the page Flatmates served. `has_more` and `next_page` tell you whether another page exists. Flatmates gives no total count in its data feed, so none is returned.

## Data quality

`sort=cheapest` lists rooms priced `$0` first and `most-expensive` starts with `$9,999`. These are placeholders, kept in place so paging stays honest, and flagged with `rent.price_valid = false`.

- **Documentation:** [https://scrappa.co/docs/flatmates-api/flatmates_search](https://scrappa.co/docs/flatmates-api/flatmates_search)
- **API group:** Flatmates API
- **Endpoint:** `GET https://scrappa.co/api/flatmates/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `location` | string | Yes | City slug (sydney) or a suburb, station or university key (bondi-2026) from location-autocomplete. |
| `page` | integer | No | Result page, 1-based. 12 rooms per page. |
| `sort` | string | No | cheapest, most-expensive, newest, earliest-available or recently-active. Default: featured first. Combines with every filter. |
| `property_type` | string | No | share-houses, whole-properties, granny-flats, homestays, studios, 1-beds or student-accommodation. |
| `bathroom_type` | string | No | ensuite or ensuite-or-own. |
| `min_budget` | integer | No | Minimum weekly rent in AUD. |
| `max_budget` | integer | No | Maximum weekly rent in AUD. |
| `stay_length` | string | No | 1-week, 2-weeks, 3-weeks, 4-weeks, 2-months, 3-months, 6-months or 12-months. |
| `room_type` | string | No | private-room or shared-room. |
| `gender` | string | No | females, males or couples. |
| `furnishings` | string | No | furnished or unfurnished. |
| `parking` | string | No | no-parking, off-street-parking or on-street-parking. |
| `bills_included` | boolean | No | true for rooms with bills included in the rent. |
| `preferences` | string | No | Comma-separated: lgbt-friendly, retirees, students. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/flatmates/search?location=sydney&property_type=share-houses&bathroom_type=ensuite&min_budget=200&max_budget=300"
```

## Example response

```json
{
    "success": true,
    "data": [
        {
            "id": 1432574,
            "link": "https://flatmates.com.au/share-house-sydney-balgowlah-2093-P1432574",
            "listing_kind": "property",
            "tile_kind": "listing",
            "label": null,
            "title": "Ensuite room in a sunny house",
            "subtitle": "Balgowlah, NSW",
            "summary": "Share house, 3 bedrooms",
            "description": "Bright room close to the bus and the beach.",
            "rent": {
                "display": "$280",
                "min": 280,
                "max": 280,
                "currency": "AUD",
                "period": "week",
                "price_valid": true
            },
            "bills": "Bills included",
            "date_available": "Available now",
            "suburb": "Balgowlah",
            "locality": "Balgowlah, NSW 2093",
            "distance": null,
            "bedrooms": 3,
            "bathrooms": 2,
            "occupants": 3,
            "photo": "https://flatmates-res.cloudinary.com/image/upload/example-small.jpg",
            "photos": [
                {
                    "mobile": "https://flatmates-res.cloudinary.com/image/upload/example-small.jpg",
                    "desktop": "https://flatmates-res.cloudinary.com/image/upload/example.jpg"
                }
            ],
            "activated_at": "2026-10-20T01:12:00.000Z",
            "member_id": 8123456
        }
    ],
    "pagination": {
        "page": 1,
        "page_size": 12,
        "returned": 1,
        "filtered_out": 0,
        "has_more": true,
        "next_page": 2
    },
    "applied_filters": {
        "location": "sydney",
        "property_type": "share-houses",
        "bathroom_type": "ensuite",
        "min_budget": 200,
        "max_budget": 300
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true,
        "attempts": 1
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Location or Filter Rejected | Flatmates does not know the `location`, or did not apply a requested filter (`upstream_rejected`). The request is rejected instead of returning unfiltered rooms. Use a `key` from location-autocomplete. Non-billable. |
| 422 | Validation Error | A query parameter is missing, unknown or unusable. Unknown parameters are rejected, never ignored. Non-billable. |
| 503 | Upstream Unavailable | Flatmates could not be reached after retries or answered with something unusable (`upstream_unavailable`, `upstream_blocked`, `parser_drift`). Retryable and never billed. Clients are never rate limited. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)