swagger: '2.0'
info:
  version: '1.4'
  title: Student.com public API
  termsOfService: 'https://www.student.com/terms/terms-of-use'
  description: >
    The Student.com API is organised around
    [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)

    and uses HTTP response codes to indicate API errors. We use built-in HTTP
    features, like HTTP authentication

    and HTTP verbs, which are understood by off-the-shelf HTTP clients.

    You can find the swagger definition of the API
    [here](https://docs.student.com/swagger.yaml)
  contact:
    name: Student.com API support
    email: tech+api+support@student.com
host: api.student.com
basePath: /v1.4
schemes:
  - https
paths:
  /cities:
    get:
      tags:
        - Cities
      summary: Get city feed
      produces:
        - application/json
      parameters:
        - name: slugs
          in: query
          description: >-
            Filter results by city slugs, query string with comma separated
            values.
          required: false
          type: string
        - name: page_size
          in: query
          description: 'Size of each page in the response(maximum:20).'
          required: false
          type: string
        - name: country_slug
          in: query
          description: Filter results by country slug.
          required: false
          type: string
        - name: page_number
          in: query
          description: Page number to request.
          required: false
          type: string
      responses:
        '200':
          description: 200 response
          schema:
            $ref: '#/definitions/CitiesResponse'
        '400':
          description: 400 response
          schema:
            $ref: '#/definitions/ErrorResponse'
  /countries:
    get:
      tags:
        - Countries
      summary: Get country feed
      produces:
        - application/json
      parameters:
        - name: page_size
          in: query
          description: 'Size of each page in the response(maximum:20).'
          required: false
          type: string
        - name: page_number
          in: query
          description: Page number to request.
          required: false
          type: string
      responses:
        '200':
          description: 200 response
          schema:
            $ref: '#/definitions/CountriesResponse'
        '400':
          description: 400 response
          schema:
            $ref: '#/definitions/ErrorResponse'
  /leads:
    get:
      tags:
        - Leads
      summary: Get lead feed
      produces:
        - application/json
      parameters:
        - name: lead_ids
          in: query
          description: >-
            Filter results by lead ids, query string with comma separated
            values.
          required: false
          type: string
        - name: page_size
          in: query
          description: 'Size of each page in the response(maximum:20).'
          required: false
          type: string
        - name: page_number
          in: query
          description: Page number to request.
          required: false
          type: string
        - name: student_email
          in: query
          description: Leads owned by this student email.
          required: false
          type: string
        - name: created_before
          in: query
          description: Leads created before this date(YYYY-MM-DD).
          required: false
          type: string
        - name: created_after
          in: query
          description: Leads created after this date(YYYY-MM-DD).
          required: false
          type: string
        - name: stage
          in: query
          description: >-
            Leads stage to request, stage is enum values
            ```new,application_processing,in_consultation,
            completed,cancellation,lost,pay_through_scom```
          required: false
          type: string
      responses:
        '200':
          description: 200 response
          schema:
            $ref: '#/definitions/LeadsResponse'
        '400':
          description: 400 response
          schema:
            $ref: '#/definitions/ErrorResponse'
    post:
      tags:
        - Leads
      summary: Add a new lead
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: CreateLeadInput
          description: >-
            Lead object to submit. Requires Student details - `email_address`,
            `first_name`, `last_name`. Please also provide either `city_id` OR
            `property_id`
          required: true
          schema:
            $ref: '#/definitions/CreateLeadInput'
      responses:
        '200':
          description: 200 response
          schema:
            $ref: '#/definitions/CreateLeadResponse'
        '400':
          description: 400 response
          schema:
            $ref: '#/definitions/ErrorResponse'
  /properties:
    get:
      tags:
        - Properties
      summary: Get property feed
      produces:
        - application/json
      parameters:
        - name: city_slug
          in: query
          description: Filter results by city slug.
          required: false
          type: string
        - name: slugs
          in: query
          description: >-
            Filter results by property slugs, query string with comma separated
            values.
          required: false
          type: string
        - name: page_size
          in: query
          description: 'Size of each page in the response(maximum:20).'
          required: false
          type: string
        - name: country_slug
          in: query
          description: Filter results by country slug.
          required: false
          type: string
        - name: page_number
          in: query
          description: Page number to request
          required: false
          type: string
      responses:
        '200':
          description: 200 response
          schema:
            $ref: '#/definitions/PropertiesResponse'
        '400':
          description: 400 response
          schema:
            $ref: '#/definitions/ErrorResponse'
  /universities:
    get:
      tags:
        - Universities
      summary: Get university feed
      produces:
        - application/json
      parameters:
        - name: city_slug
          in: query
          description: Filter results by city slug.
          required: false
          type: string
        - name: slugs
          in: query
          description: >-
            Filter results by university slugs, query string with comma
            separated values.
          required: false
          type: string
        - name: page_size
          in: query
          description: 'Size of each page in the response(maximum:20).'
          required: false
          type: string
        - name: page_number
          in: query
          description: Page number to request.
          required: false
          type: string
      responses:
        '200':
          description: 200 response
          schema:
            $ref: '#/definitions/UniversitiesResponse'
        '400':
          description: 400 response
          schema:
            $ref: '#/definitions/ErrorResponse'
definitions:
  Tracking:
    type: object
    properties:
      utm_term:
        type: string
        example: term_x
      gclid:
        type: string
        example: je12uFzkX7142
      utm_campaign:
        type: string
        example: promotion123
      source_details:
        type: string
        example: api
      utm_medium:
        type: string
        example: SocialMedia
      source:
        type: string
        example: agent_or_partner
      ip_address:
        type: string
        example: 192.169.1.1
      source_device:
        type: string
        example: browser
      utm_source:
        type: string
        example: Weibo
      utm_content:
        type: string
        example: content_y
  UniversitiesResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          universities:
            type: array
            items:
              $ref: '#/definitions/University'
          page_info:
            $ref: '#/definitions/PageInfo'
  City:
    type: object
    properties:
      country:
        $ref: '#/definitions/Country'
      name:
        type: string
        example: London
      id:
        $ref: '#/definitions/Id'
        example: eyJ0eXBlIjoiQ2l0eSIsImlkIjo0MTd9
      slug:
        type: string
        example: london
  CountriesResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          page_info:
            $ref: '#/definitions/PageInfo'
          countries:
            type: array
            items:
              $ref: '#/definitions/City'
  Image:
    type: object
    properties:
      is_hero_image:
        type: boolean
        example: true
      url:
        type: string
        example: >-
          https://image.student.com/max_1280x1280/property-64469-630eac2146fbe7995d1fb7d09eb23444.jpeg
  Student:
    type: object
    required:
      - email_address
      - first_name
      - last_name
    properties:
      email_address:
        type: string
        example: ann.smith@example.com
      last_name:
        type: string
        example: Smith
      phone_number:
        type: string
        example: '+4407457123123'
      language:
        type: string
        example: zh-cn
      other_preferences:
        type: string
        example: >-
          I want a single room in a shared apartment. I would like to share my
          apartment mostly with girls.
      first_name:
        type: string
        example: Ann
      marketing_consent:
        type: boolean
        example: true
      wechat_id:
        example: yi_long_2016
  ErrorResponse:
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/ErrorMessage'
      status:
        type: string
        example: invalid request
  PageInfo:
    type: object
    properties:
      has_previous_page:
        type: boolean
        example: true
      has_next_page:
        type: boolean
        example: false
      num_pages:
        type: integer
        example: 10
  PropertiesResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          total_count:
            type: integer
          page_info:
            $ref: '#/definitions/PageInfo'
          properties:
            type: array
            items:
              $ref: '#/definitions/Property'
  CitiesResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          cities:
            type: array
            items:
              $ref: '#/definitions/City'
          page_info:
            $ref: '#/definitions/PageInfo'
  PointOfContact:
    type: object
    properties:
      email_address:
        type: string
        example: john.smith@example.com
      last_name:
        type: string
        example: Smith
      phone_number:
        type: string
        example: '+4407457123124'
      first_name:
        type: string
        example: John
  University:
    type: object
    properties:
      country:
        $ref: '#/definitions/Country'
      address:
        type: string
        example: Sussex Place
      city:
        $ref: '#/definitions/City'
      latitude:
        type: string
        example: 51.5263
      name:
        type: string
        example: London Business School
      id:
        $ref: '#/definitions/Id'
        example: eyJ0eXBlIjoiVW5pdmVyc2l0eSIsImlkIjo0MTR9
      slug:
        type: string
        example: london-business-school
      longitude:
        type: string
        example: -0.160998
  CreateLeadResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          lead:
            $ref: '#/definitions/Lead'
      status:
        type: string
  Listing:
    type: object
    properties:
      move_out_type:
        type: string
        enum:
          - exactly_match
          - before
          - anytime
        example: anytime
      tenancy_length_value:
        type: string
        format: (^\d+-\d+$)|(^\d+\+?$)
        example: 24-25
      available_to:
        type: string
        format: date
        example: '2019-01-01'
      tenancy_length_type:
        type: string
        enum:
          - equal
          - no_less_than
          - no_more_than
          - between
          - not_specific
        example: 'between,'
      discount_value:
        type: number
        example: 5
      move_out:
        type: string
        format: date
        example: null
      availability:
        type: string
        enum:
          - good
          - limited
          - sold_out
        example: good
      move_in:
        type: string
        format: date
        example: '2018-01-01'
      price_min:
        type: number
        example: 400.5
      discount_type:
        type: string
        enum:
          - absolute
          - percentage
        example: percentage
      move_in_type:
        type: string
        enum:
          - exactly_match
          - after
          - anytime
        example: after
      available_from:
        type: string
        format: date
        example: '2018-01-01'
      id:
        $ref: '#/definitions/Id'
        example: eyJ0eXBlIjoiTGlzdGluZyIsImlkIjo0NDc3OX0==
      price_max:
        type: number
        example: 400.5
  UnitType:
    type: object
    properties:
      images:
        type: array
        items:
          $ref: '#/definitions/Image'
      bedroom_count_min:
        type: integer
        example: 1
      max_occupancy:
        type: integer
        example: 5
      room_size:
        type: string
        example: 100-120
      room_size_unit:
        type: string
        enum:
          - sqft
          - sqm
        example: sqft
      kitchen_count:
        type: number
        example: 1
      bedroom_count_max:
        type: integer
        example: 3
      bed_count:
        type: integer
        example: 1
      bed_sizes:
        type: array
        items:
          $ref: '#/definitions/BedSize'
      listings:
        type: array
        items:
          $ref: '#/definitions/Listing'
      floors:
        type: array
        items:
          type: integer
        example:
          - 0
          - 1
          - 2
      room_arrangement:
        type: string
        enum:
          - cluster
          - apartment
          - hotel_style
        example: cluster
      gender_mix:
        type: string
        enum:
          - mixed
          - male_only
          - female_only
        example: mixed
      name:
        type: string
        example: deluxe suite
      id:
        $ref: '#/definitions/Id'
        example: eyJ0eXBlIjoiVW5pdFR5cGUiLCJpZCI6MTY3NzN9
      bathroom_type:
        type: string
        enum:
          - private_ensuite
          - private_non_ensuite
          - shared_ensuite
          - shared_non_ensuite
          - mixed
        example: private_ensuite
      category:
        type: string
        enum:
          - entire_place
          - private_room
          - shared_room
        example: shared_room
      bathroom_count:
        type: number
        example: 1
      facilities:
        type: array
        items:
          $ref: '#/definitions/Facility'
  Lead:
    type: object
    properties:
      stage:
        type: string
        description: lead status
        enum:
          - new
          - application_processing
          - in_consultation
          - completed
          - cancellation
          - lost
          - pay_through_scom
        example: new
      updated_at:
        type: string
        format: dateTime
        example: 2021-02-24T00:00:00.000Z
      move_out_month:
        type: string
        example: 2019-01
      student:
        type: object
        properties:
          email_address:
            type: string
            example: ann.smith@example.com
          last_name:
            type: string
            example: smith
          first_name:
            type: string
            example: john
      budget_value:
        type: string
        example: '500.50'
      budget_frequency:
        type: string
        enum:
          - per-week
          - per-month
        example: per-week
      move_in_month:
        type: string
        example: 2018-01
      created_at:
        type: string
        format: dateTime
        example: 2021-02-24T00:00:00.000Z
      destination_university_name:
        type: string
        example: University Collage London
      id:
        $ref: '#/definitions/Id'
        example: eyJ0eXBlIjoiUHJvcGVydHkiLCJpZCI6Mjc2fQ==
      budget_currency:
        type: string
        example: gbp
      point_of_contact:
        type: object
        properties:
          email_address:
            type: string
            example: john.smith@example.com
  Country:
    type: object
    properties:
      name:
        type: string
        example: United Kingdom
      id:
        $ref: '#/definitions/Id'
        example: eyJ0eXBlIjoiQ291bnRyeSIsImlkIjozfQ==
      slug:
        type: string
        example: uk
  Id:
    type: string
    example: eyJ0eXBlIjoiUHJvcGVydHkiLCJpZCI6Mjc2fQ==
  LeadsResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          leads:
            type: array
            items:
              $ref: '#/definitions/Lead'
          page_info:
            $ref: '#/definitions/PageInfo'
  Facility:
    type: object
    properties:
      name:
        type: string
        example: Wifi
      label:
        type: string
        example: Free
      slug:
        type: string
        example: wifi_free
      tags:
        type: array
        items:
          type: string
          enum:
            - amenity
            - security
            - rule
            - bills
            - include
            - not_include
            - no_service
          example:
            - bills
            - include
  ErrorMessage:
    type: object
    properties:
      code:
        type: string
        example: parameter_missing
      message:
        type: string
        example: required field missing
  Property:
    type: object
    properties:
      unit_types:
        type: array
        items:
          $ref: '#/definitions/UnitType'
      total_beds:
        type: integer
        example: 100
      country:
        $ref: '#/definitions/Country'
      images:
        type: array
        items:
          $ref: '#/definitions/Image'
      address:
        type: string
        example: 'Canal Reach, Kings Cross, London'
      city:
        $ref: '#/definitions/City'
      latitude:
        type: string
        example: '38.396'
      description:
        type: string
        example: >-
          Grab a luxe pad in up-and-coming trendy hotspot Kings Cross a perfect
          entry point for experiencing London
      booking_journey:
        type: string
        enum:
          - manual
          - semi_automatic
          - full_automatic
        example: manual
      no_place_no_pay:
        type: boolean
        description: >-
          A booking can be cancelled for free if you have failed to obtain the
          required qualifications to get info you university of choice
        example: true
      post_code:
        type: string
        example: N1C 4BE
      name:
        type: string
        example: Urbanest King's Cross
      property_type:
        type: string
        description: >

          - co-living: Co-living is a modern form of communal living in which
          residents get a private apartment in a furnished property with shared
          facilities and common areas. Co-living is popular in major cities as a
          means of affordable living for students and young professionals.

          - apartments: A suite of rooms forming one residence; a flat.

          - hmo: UK only - house in Multiple Occupation, a house or other
          dwelling in which several different households are living, sharing
          facilities such as a kitchen or bathroom.

          - house-share: Two or more people living in accommodation together.
          Often large house or apartment. Usually each person will have their
          own bedroom and typically they will share certain communal areas such
          as kitchens, bathrooms or living rooms.

          - home-stay: A room in the family host home.

          - student-residence-halls: A college or university building containing
          living quarters for students.

          - dormitory: A large bedroom for a number of people in a school or
          institution.

          - purpose-built-student-accommodation: Housing specifically built for
          university students by private developers. Properties usually take one
          of two forms: 1. Self contained studio or “cluster” flats with private
          kitchens but shared living space.

          - house: A building for human habitation, especially one that consists
          of a ground floor and one or more upper storeys.

          - hostel: Student hostel, Youth Hostel, backpackers, often sharing a
          room with multiple people, also has option to have private room with
          ensuite or shared bathroom, can be mixed gender or gender specific
          room types, not restricted to only student residents, can be offered
          with or without breakfast.

          - hotel: Hotel (can have local star rating), can be offered with or
          without breakfast or dinner, not restricted to only student residents.

          - apart-hotel: Serviced apartment (self contained hotel rooms),
          professional short stay apartments to be rented by apartment not room,
          not exclusive to only student residents, have facilities and services
          such as a reception desk and restaurant.

          - multifamily: Classification of housing where multiple separate
          housing units for residential inhabitants are contained within one
          building or several buildings within one complex, mostly common within
          United States. Not restricted to only student residents.

          - lodge: An often rustic building used as a short term accomodation
          much like a hotel but of older style - a lodge may have communal
          facilities,can be offered with or without breakfast.

          - condos: An apartment building in which each apartment is owned
          separately by the people living in it, but also containing shared
          areas.

          - townhouse-home: A townhouse is a type of terraced housing, one of a
          row of similar houses that are usually joined by a shared wall. A
          modern townhouse is often one with a small footprint on multiple
          floors.

          - bungalow: Free standing small house that is either single-storey or
          has a second storey built into a sloping roof, and may be surrounded
          by wide verandas.

          - terrace: One property in a row of houses that are joined together.
          Commonly found in inner city locations

          - villa: A house, usually in the countryside or near the sea,
          especially in southern Europe, and often one that people can rent for
          a holiday.

          - serviced-apartment: A serviced apartment is a fully furnished
          apartment available for short-term or long-term stay, providing
          hotel-like amenities such as room service, and professional house
          keeping services.

          - duplex: A residential building divided into two apartments, each
          with its own entrance.
        enum:
          - co-living
          - apartments
          - hmo
          - house-share
          - home-stay
          - student-residence-halls
          - dormitory
          - purpose-built-student-accommodation
          - house
          - hostel
          - hotel
          - apart-hotel
          - multifamily
          - lodge
          - condos
          - townhouse-home
          - bungalow
          - terrace
          - villa
          - serviced-apartment
          - duplex
        example: apartments
      no_visa_no_pay:
        type: boolean
        description: >-
          Your booking can be cancelled for free if the Visa application has
          been denied
        example: true
      currency:
        type: string
        format: '^[a-z]{3}$'
        example: gbp
      id:
        $ref: '#/definitions/Id'
      billing_cycle:
        type: string
        enum:
          - weekly
          - monthly
        example: weekly
      state:
        type: string
        enum:
          - available_with_price
          - available
          - coming_soon
          - sold_out
          - inactive
        example: available_with_price
      facilities:
        type: array
        items:
          $ref: '#/definitions/Facility'
      headline:
        type: string
        example: This is a property headline
      slug:
        type: string
        example: modern-house
      longitude:
        type: string
        example: '104.04'
  CreateLeadInput:
    type: object
    required:
      - student
    properties:
      listing_id:
        type: string
        example: eyJ0eXBlIjoiTGlzdGluZyIsImlkIjozNTUyMH0==
      student:
        $ref: '#/definitions/Student'
      budget_value:
        type: string
        example: '500.50'
      budget_frequency:
        type: string
        enum:
          - per-week
          - per-month
        example: per-week
      move_in_month:
        type: string
        example: 2018-01
      destination_university_name:
        type: string
        example: University Collage London
      tracking:
        $ref: '#/definitions/Tracking'
      property_id:
        type: string
        example: eyJ0eXBlIjoiUHJvcGVydHkiLCJpZCI6Mjc2fQ==
      move_out_month:
        type: string
        example: 2019-01
      referrer_name:
        type: string
        example: Jack Ma
      budget_currency:
        type: string
        example: gbp
      referrer_email:
        type: string
        example: jack.ma@example.com
      point_of_contact:
        $ref: '#/definitions/PointOfContact'
      city_id:
        type: string
        example: eyJ0eXBlIjoiQ2l0eSIsImlkIjo0MTJ9
  BedSize:
    type: object
    properties:
      bed_type:
        type: string
        enum:
          - single_bed
          - double_bed
          - small_double_bed
          - king_bed
          - king_single_bed
          - california_king_bed
          - grand_king_bed
          - queen_bed
          - twin_bed
          - bunk_bed
          - king_size_bed
        example: double_bed
      length:
        type: number
        example: 203
      width:
        type: number
        example: 107
      bed_count:
        type: number
        example: 10
consumes:
  - application/json
produces:
  - application/json