Portfolio
Insights
Support
View guides

GET /api/houses

This end point allows you to list properties in property manager's portfolio. It accepts GET requests to

https://sturents.com/api/houses

To return a specific property add the reference to the URL. E.g. for property with reference 1234:

GET /api/houses/1234

To return all properties which have been added to the system after a specific date and time you can place added-since/{date}/{time} (time optional) in your request URL. E.g. for properties added after 12:30pm on 4th July 2017:

GET /api/houses/added-since/2017-07-04/12:30

You can combine the single property fetch and added routes to store data locally for a portfolio and re-fetch just the data you need when you need it. Check our developer support email at the base of this page for more suggestions.

All data types are assumed to be strings unless stated otherwise. All strings and arrays may be empty unless stated otherwise. Objects will always contain the specified keys.

Pagination

If a request would return more than 50 properties then the first 50 properties will be returned. If this is the case the root object will contain a pagination object. Making requests with a page integer value in the query string will fetch that page.

List object
  • date - a timestamp in the format yyyy-mm-dd hh:min:sec
  • format - the API version being returned
  • provider - our name
  • pagination - optional a pagination object
  • branches - an array containing a single branch object
Pagination object
  • pages - the number of pages total
  • current - for data integrity, the page that these results relate to
  • next - if present this shows there is another page available after this one
  • prev - if present this shows there is another page available prior to this one
Branch object
  • agent_id - the ID of the branch on StuRents, this will match the value of landlord provided in the request
  • name - the name recorded for the branch
  • website - if listed, the website for the branch *
  • properties - an array containing zero or more property objects
Property object
  • reference - a unique reference to the property on your platform which will not change
  • available - an array of one or more availability objects
  • designation - "house" | "pbsa"
  • beds_available - the number of bedrooms (formerly called "beds"). If set to "zero" this will list the property as a studio flat
  • beds_total - the number of bedrooms (if not specified, will be set the same as the value above)
  • rooms_let_individually - boolean where true indicates each room may be let on a separate contract
  • quantity - When designation is set to "pbsa" this describes the number of identical rental options available
  • quantity_available - as above, but currently available to rent
  • room_type - When designation is set to "pbsa" each property record describes a type of room. This field gives that type a name e.g. "Deluxe En-suite"
  • property_type - "Residential"
  • description - a plain text or HTML description of the property. Please note HTML will be stripped but the HTML structure will be used to render line breaks where necessary
  • bathrooms - number of bathrooms
  • floor_space - floor space of the property in square metres
  • facilities - an array of zero or more facility names. Click to view allowed facilities
  • address - an address object
  • coordinates - a coordinates object
  • contracts - an array of one or more contract objects
  • media - a media object
  • energy_performance - an energy performance object
  • accreditations - an array of zero or more accreditation objects
  • incomplete - boolean where true indicates that the property is not ready to be made public to students or shown in search results
  • eligibility - an eligibility object
Availability object
  • start_date - the earliest date at which it is possible to move in to the property
  • end_date - the latest date at which it is possible to vacate the property
  • min_contract_days - the minimum time a tenant may rent the property for in days
Address object
  • property_name - this is required if "property_number" is empty
  • property_number - this is required if "property_name" is empty
  • road_name
  • city
  • postcode
  • uprn - if available, the unique property reference
Coordinates object
  • lat
  • lng
Contract object
Price object
  • amount - a monetary value float
  • amount_per - "person" | "property"
  • time_period - "month" | "week" | "quarter" | "year"
  • utilities - a utilities object
Deposit object
  • amount - a monetary value float
  • amount_per - "person" | "property"
Utilities object

All keys are boolean where true indicates that this utility is included with the rent.

  • water
  • gas
  • electricity
  • broadband
  • phone
  • contents_insurance
Restriction object
  • start_date - the date that the contract this restriction belongs to is available from
  • end_date - the date that the contract this restriction belongs to is available until
  • terms - a text block describing this restriction (e.g. "For home students only")
  • min_contract_days - minimum days a student must be renting for the prices in this contract to be valid
Media object
  • photos - an array of zero or more photo objects. The order of photos will be maintained in the gallery; the 1st will be the profile photo
  • videos - an array of zero or more video embed URLs
  • floorplans - an array of zero or more URLs which link to floorplan files (image or pdf)
  • tours - an array of zero or more 360 tour URLs to an external service. Any 360 tour source can be supplied and used as a link
Photo object
  • type - "url"
  • photo - a URL linking to a photo file
  • thumb - a URL linking to a thumbnail photo file
  • caption - a string

A planned future development is to allow a separate mechanism to upload photos via FTP, which will utilise the "type" field

Energy performance object
  • epc_reference - the reference on the property's energy performance certificate
  • epc_certificate - a URL to download the energy performance certificate
  • eef_current - an integer
  • eef_potential - an integer
  • co2_current - an integer
  • co2_potential - an integer
Accreditation object
  • type - title of an accreditation on the property
  • reference - the reference connecting the property to its accrediting agency
  • expiry - when the accreditation will expire (empty is assumed to not expire)
Eligibility object

Each key is a boolean indicating if the specified item is eligible to rent the property. At least one field must be set to true

  • undergraduate_student
  • postgraduate_student
  • professional
  • trainee
  • dss - indicates a recipient of UK housing benefit
  • pets_permitted
  • smoking_permitted
  • female_only
  • male_only

Example code

Your browser may render > symbols as ">" in the examples below, if necessary please fix this before using the code.

JavaScript (client side, using jQuery)

var url = 'https://sturents.com/api/houses'; $.getJSON(url, {landlord : , public: '', version: '1.2'}, function(response){ var $list = $('
    '); $.each(response.branches[0].properties, function(i, property){ $('
  • ').text(property.address.road_name+' '+property.address.postcode).appendTo($list); }); $list.appendTo('body'); });

    Ruby (server side)

    require "net/http" require "uri" require 'json' uri = URI('https://sturents.com/api/houses') params = { :landlord => , :public => '', :version => '' } uri.query = URI.encode_www_form(params) res = Net::HTTP.get_response(uri) data = JSON.parse(res.body) properties = data['branches'][0]['properties'] for property in properties puts property['address']['road_name'] end

    PHP (server side)

    $uri = 'https://sturents.com/api/houses'; $params = [ 'landlord' => , 'public' => '', 'version' => '' ]; $query = $uri.'?'.http_build_query($params); $json = file_get_contents($query); $data = json_decode($json, true); $properties = $data['branches'][0]['properties']; foreach $properties as $property { echo $property['address']['road_name']; }

    Sample libraries

    We have written sample libraries to handle generation of an authentication token and submission to our API. If your language is not included, please feel free to suggest it to our API team via email

    Our API is rate limited for identical requests, if you are constantly receiving an error code 429, please reduce the frequency of your requests. Identical requests are those with the exact same query parameter values. We strongly encourage that if you are encountering this issue during local development you cache/save the response from the API.

    We have a support email for developers if you have any questions or encounter problems whilst using the API.