Properties

Housemates collaborates with over 100 accommodation providers and manages the complex relationships with them, so you don't have to. We have numerous technical integrations and operational processes in place to ensure that the data in our API is always up-to-date.

A "Property" in the context of the Housemates API represents a student accommodation building. Each property can have multiple units or "rooms". Properties can be categorised in various ways based on their attributes, such as location, amenities, type (such as shared apartment, private studio, or dormitory), and more.

For the purposes of this API, each Property is considered a unique entity with its own identifier (referred to as a Property ID). This identifier can be used to retrieve detailed information about the specific property.

The Property model

The Property model contains all the information about a property that is stored on Housemates' system. Following is a list of all the attributes that are available on the Property model.

Attributes

Name
id
Type
string
Description
This is the unique identifier that is used to identify the property in our system. It is also used to retrieve detailed information about the property.
Name
operator_id
Type
string
Description
Unique identifier used to identify the accommodation provider in our system.
Name
name
Type
string
Description
The name of the property. e.g. "The Electra".
Name
slug
Type
string
Description
The slug of the property. e.g. "the-electra". It can be used to filter properties. e.g. /v1/properties?filter[slug=the-electra]
Name
price_range
Type
object
Description
The price range of rooms in the property per week
Name
description
Type
text
Description
Text description of the property.
Name
rich_description
Type
text
Description
HTML i.e. rich description of the property.
Name
summary
Type
string
Description
Summary of the property.
Name
amenities
Type
object
Description
Amenities available at the property. Amenities are grouped into categories. i.e. General, Kitchen and Services. Each category contains a list of amenities that are available at the property. The status of each amenity indicates if the amenity is available. The label of each amenity can be used to filter properties by. A full list of amenities can be retrieved from the Amenities endpoint.
Name
coordinates
Type
object
Description
The coordinates of the property. i.e. latitude and longitude.
Name
address
Type
object
Description
The address of the property.
Name
currency
Type
string
Description
The currency set for the property. e.g. GBP. As we work with accommodation providers from different countries, this attribute is used to determine the currency in which the prices are displayed.
Name
location
Type
string
Description
The location of the property. e.g. "Manchester".
Name
location_slug
Type
string
Description
The slug of the location of the property. e.g. "manchester". It can be used to filter properties by city. e.g. /v1/properties?filter[city=manchester]
Name
offer_amount
Type
integer
Description
Any offer that is available on the property. e.g. 200. This could be a discount or a cashback.
Name
virtual_tours
Type
array
Description
A list of virtual tours of the property.
Name
images
Type
array
Description
A list of images of the property.
Name
rooms
Type
array
Description
List of rooms of the property. Returned only when fetching individual property.
Name
_links
Type
array
Description
A list of links to related resources.

Property model

{
  "id": "01H14V1E5EVWGANKXQG7TVYGQ1",
  "operator_id": "03d7438a-309f-446e-96be-7b123180e155",
  "name": "Vega",
  "slug": "vega",
  "price_range": {
    "min": "£98.04",
    "max": "£98.04"
  },
  "description": "The Electra brings a touch of luxury to student accommodation in Liverpool.",
  "rich_description": "<p>The Electra brings a touch of luxury to student accommodation in Liverpool.</p>",
  "summary": "The Electra brings a touch of luxury to student accommodation in Liverpool",
  "amenities": {
    "general": [
      {
        "name": "All Bills Included",
        "label": "AIB",
        "status": false
      },
      {
        "name": "Air Conditioning",
        "label": "AIR",
        "status": true
      }
    // ...
    ],
    "kitchen": [
      {
        "name": "Dryer",
        "label": "DRY",
        "status": true
      },
      {
        "name": "Dishwasher",
        "label": "DSH",
        "status": true
      }
    // ...
    ],
    "services": [
      {
        "name": "Cinema Room",
        "label": "CR",
        "status": true
      },
      {
        "name": "Study Area",
        "label": "SA",
        "status": false
      }
    // ...
    ]
  },
  "coordinates": {
    "lat": "53.4963380",
    "long": "-2.1564880"
  },
  "address": {
    "first_line": "1 Manchester Road",
    "second_line": "",
    "city": "Manchester",
    "region": "",
    "postcode": "M35 0PS",
    "country": "United Kingdom"
  },
  "currency": "GBP",
  "location": "Manchester",
  "location_slug": "manchester",
  "offer_amount": 0,
  "virtual_tours": [
    {
      "link": "https://link-to-virtual-tour.com",
      "title": "Lobby"
    }
  ],
  "images": [
    {
      "id": 1,
      "url": "https://ik.imagekit.io/rk1sb42mtmr/tr:h-639,w-1136,f-jpg,q-70/cadc73b0-295e-43d9-acd4-060f3d58a605/media/Qm274NHbhuCPPQ8E0kXQQLIUcH14F23A7X4wa8bx.jpg"
    }
  ],
  "_links": [
    {
      "rel": "self",
      "type": "GET",
      "href": "https://api.housemates.io:8060/api/properties/01H14V1E5EVWGANKXQG7TVYGQ1"
    },
    {
      "rel": "property_amenities",
      "type": "GET",
      "href": "https://api.housemates.io:8060/api/amenities?type=property"
    }
  ]
}

GET/api/properties

List all properties

This endpoint allows you to retrieve a paginated list of all available properties. By default, a maximum of ten properties are shown per page.

Required attributes

Name
X-API-PARTNER-ID
Type
string
Description
Your API partner ID provided by Housemates. It should be provided in the header.

Optional attributes

Name
per_page
Type
integer
Description
Limit the number of properties returned.
Name
page
Type
integer
Description
The page number to be returned. e.g. page=2. By default, the first page is returned. It is usually used for pagination.

Filters

You can filter the properties by using the following optional query parameters:

Name
city
Type
string
Description
Filter properties by city. e.g. filter[city]=manchester
Name
slug
Type
string
Description
Filter properties by slug. e.g. filter[slug]=gainsborough-house
Name
slug
Type
string
Description
Filter properties by amenities. e.g.
filter[amenities]=[BLC=true,CTH=true,BLC=true,BRD=false]
Name
filter[exclude_unavailable]
Type
boolean
Description
Exclude unavailable properties from the API response.
filter[exclude_unavailable]=true

Request

GET

/api/properties

curl --request GET \
    --url https://api.housemates.io/api/properties \
    --header 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer {access_token}'

# Filtering properties by city
curl --request GET \
    --url https://api.housemates.io/api/properties?filter[city]=manchester \
    --header 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer {access_token}'

Response

{
  "success": true,
  "code": 0,
  "locale": "en",
  "message": "OK",
  "data": {
    "items": [
      {
        "id": "01H14V1E5EVWGANKXQG7TVYGQ1",
        "operator_id": "03d7438a-309f-446e-96be-7b123180e155",
        "name": "Vega",
        "slug": "vega",
        "price_range": {
          "min": "£98.04",
          "max": "£98.04"
        },
         // ... refer to the property model above
     },
     // ...
    ],
    "meta": {
      "total": 17,
      "count": 10,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 2,
      "path": "https://api.housemates.io/properties",
      "links": [
        {
          "url": null,
          "label": "&laquo; Previous",
          "active": false
        },
        {
          "url": "https://api.housemates.io/properties?page=1",
          "label": "1",
          "active": true
        },
        {
          "url": "https://api.housemates.io/properties?page=2",
          "label": "2",
          "active": false
        },
        {
          "url": "https://api.housemates.io/properties?page=2",
          "label": "Next &raquo;",
          "active": false
        }
      ]
    },
    "links": {
      "first": "https://api.housemates.io/properties?page=1",
      "last": "https://api.housemates.io/properties?page=2",
      "next": "https://api.housemates.io/properties?page=2",
      "prev": null
    }
  }
}

GET/api/properties/:id

Retrieve a property

This endpoint allows you to retrieve a property by providing their unique id. Refer to the list at the top of this page to see which properties are included with property objects.

Required attributes

Name
X-API-PARTNER-ID
Type
string
Description
Your API partner ID provided by Housemates. It should be provided in the header.
Name
property_id
Type
string
Description
Unique identifier for the property to be provided in the path.

Request

GET

/api/properties/:id

curl --location 'https://api.housemates.io/api/properties/{property_id}' \
--header 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Response

{
  "success": true,
  "code": 0,
  "locale": "en",
  "message": "OK",
  "data": {
    "item": {
        "id": "01H14V1E5EVWGANKXQG7TVYGQ1",
        "operator_id": "03d7438a-309f-446e-96be-7b123180e155",
        "name": "Vega",
        "slug": "vega",
        "price_range": {
          "min": "£98.04",
          "max": "£98.04"
        },
         // ... refer to the property model above
     },
   }
}