Street.co.uk Lettings API

openapi: 3.2.0
info:
  version: '1.0'
  title: Property Feed Lettings API
  description: The Street.co.uk Property Feed API is designed to power your agency's website and property search functionality.
  summary: The Street.co.uk Property Feed API is designed to power your agency's website and property search functionality.
  contact:
    name: Street API Development Team
    url: street.co.uk
    email: apis@street.co.uk
servers:
- url: https://street.co.uk/api/property-feed/v1
  description: The live/production API. Tokens for this can self generated via the settings area of the CRM.
- url: https://demo.street.co.uk/api/property-feed/v1
  description: The demo API. Tokens can be requested from the support team at Street.co.uk.
security:
- your_api_token: []
tags:
- name: Lettings
  description: These are the lettings specific API Endpoints.
paths:
  /lettings/search:
    get:
      summary: Search for Lettings Properties
      tags:
      - Lettings
      responses:
        '200':
          description: The API endpoint responds with a JSON object containing a list of lettings properties matching the specified criteria. Each property object within the response typically includes information such as property ID, address, description, rental price, number of bedrooms, and other relevant details. The response also includes pagination metadata, such as the total number of properties, the current page number, and the number of properties per page.
          content:
            application/vnd.api+json:
              schema:
                allOf:
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Property'
                    included:
                      $ref: '#/components/schemas/PropertyIncludes'
                    meta:
                      $ref: '#/components/schemas/Pagination'
                    links:
                      $ref: '#/components/schemas/Links'
                type: object
              examples:
                Example 1:
                  value:
                    data:
                    - type: property
                      id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                      attributes:
                        branch_uuid: b8e564e2-b92d-49d7-8331-85bb2766d8f8
                        inline_address: Rivendell, Main Street
                        public_address: Main Street, Follifoot, HG3
                        postcode: HG3 1DU
                        bedrooms: 3
                        bathrooms: 1
                        receptions: 2
                        floor_area: null
                        plot_area: null
                        land_area: null
                        property_type: House
                        property_style: None
                        is_commercial: true
                        property_age_bracket: 1970 - 1990
                        construction_year: null
                        status: Sold STC
                        sale_status: Sold STC
                        letting_status: For Sale and To Let
                        dual_listing: false
                        owner_label: Owner
                        tenure: Freehold
                        tenure_notes: null
                        lease_expiry_year: '2022'
                        lease_expiry_date: null
                        public_url: https://street.co.uk/platform/properties/0ed2e2f4-b697-4c78-a801-d805b75a75aa
                        viewing_booking_url: null
                        created_at: '2022-02-28T11:46:20+00:00'
                        updated_at: '2022-06-20T13:30:25+01:00'
                        custom_meta_data:
                        - meta_name: meta value
                        property_urls:
                        - media_type: audio_tour
                          media_url: string
                        last_instructed_sales_at: '2022-02-28T11:46:20+00:00'
                        last_instructed_lettings_at: '2022-02-28T11:46:20+00:00'
                        last_exchanged_at: '2022-02-28T11:46:20+00:00'
                        last_completed_at: '2022-02-28T11:46:20+00:00'
                      relationships:
                        address:
                          data:
                            type: address
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        details:
                          data:
                            type: details
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        salesListing:
                          data:
                            type: sales_listing
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        lettingsListing:
                          data:
                            type: lettings_listing
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        primaryImage:
                          data:
                            type: primary_image
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        rooms:
                          data:
                          - type: room
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        images:
                          data:
                          - type: media
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        floorplans:
                          data:
                          - type: floorplan
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        features:
                          data:
                          - type: feature
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        outsideSpaces:
                          data:
                          - type: outsideSpace
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        parkingSpaces:
                          data:
                          - type: parkingSpace
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        epc:
                          data:
                            type: epc
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        additionalMedia:
                          data:
                          - type: media
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        tags:
                          data:
                          - type: tag
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        brochure:
                          data:
                            type: brochure
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                        development:
                          data:
                            type: development
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                    included:
                    - type: address
                      id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                      attributes:
                        anon_address: Beattock, Moffat, DG10
                        line_1: Telford Manor House
                        line_2: Beattock
                        line_3: Moffat
                        line_4: null
                        line_5: null
                        town: Moffat
                        country: United Kingdom
                        postcode: DG10 9SG
                        inline: Telford Manor House, Beattock, Moffat, DG10 9SG
                        longitude: -3.4548511
                        latitude: 55.3109071
                        royal_mail:
                          postcode: string
                          post_town: string
                          thoroughfare: string
                          building_name: string
                          building_number: string
                          department_name: string
                          organisation_name: string
                          sub_building_name: string
                          dependent_locality: string
                          dependent_thoroughfare: string
                          double_dependent_locality: string
                    meta:
                      pagination:
                        total: 226
                        count: 10
                        per_page: 10
                        current_page: 1
                        total_pages: 23
                    links:
                      self: https://street.co.uk/api/property-feed/sales/search?page[number]=2&page[size]=25&page[number]=2
                      first: https://street.co.uk/api/property-feed/sales/search?page[number]=2&page[size]=25&page[number]=1
                      next: https://street.co.uk/api/property-feed/sales/search?page[number]=2&page[size]=25&page[number]=1
                      prev: https://street.co.uk/api/property-feed/sales/search?page[number]=2&page[size]=25&page[number]=3
                      last: https://street.co.uk/api/property-feed/sales/search?page[number]=2&page[size]=25&page[number]=9
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '406':
          $ref: '#/components/responses/notAcceptable'
        '415':
          $ref: '#/components/responses/unsupportedMediaType'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
        '500':
          $ref: '#/components/responses/serverError'
      operationId: get-lettings-search
      description: "This endpoint returns all active lettings properties in your Street account. \n\nBy default it will only return 'active' properties i.e. those with a status of `To Let`, `For Sale and To Let` or `Let Agreed`.\n\nIt will also return properties for **ALL** branches within your Street account, if you wish to limit to a specific branch you can use the `filter[branch]` query param and pass the `UUID` of the desired branch."
      parameters:
      - $ref: '#/components/parameters/filter_areas'
      - $ref: '#/components/parameters/filter_bedrooms'
      - $ref: '#/components/parameters/filter_min_bedrooms'
      - $ref: '#/components/parameters/filter_branch'
      - $ref: '#/components/parameters/filter_features'
      - $ref: '#/components/parameters/filter_include_land'
      - $ref: '#/components/parameters/filter_max_price'
      - $ref: '#/components/parameters/filter_min_price'
      - $ref: '#/components/parameters/filter_postcode'
      - $ref: '#/components/parameters/filter_lettings_status'
      - $ref: '#/components/parameters/filter_tags'
      - $ref: '#/components/parameters/include'
      - $ref: '#/components/parameters/page_number'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/sort'
      - schema:
          type: string
          default: 'false'
        in: query
        name: filter[include_archived]
        description: Include archived properties within the result set
components:
  parameters:
    page_size:
      name: page[size]
      description: Set the number of results per page.
      in: query
      required: false
      schema:
        type: number
        minimum: 1
        maximum: 250
        example: 25
    filter_lettings_status:
      name: filter[status]
      description: Filter by property status. You can use a comma separated list for multiple statuses.
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          enum:
          - to_let
          - for_sale_and_to_let
          - let
          - let_agreed
        uniqueItems: true
        minItems: 1
        maxItems: 4
      explode: false
      style: form
    filter_max_price:
      name: filter[max_price]
      description: Maximum listing price for search results.
      in: query
      required: false
      schema:
        type: string
    filter_branch:
      name: filter[branch]
      description: Filter by network branch. Provide the UUID of a branch to filter properties by a specific branch.
      in: query
      required: false
      schema:
        type: string
    filter_tags:
      name: filter[tags]
      description: Tags are entered by the agent in the Street UI and enable you to filter properties according to custom criteria. This can be used to power featured properties, carousels, hot property lists etc.These tags should be passed to the API in lowercase and urlencoded.You can also enter a comma seperated list to return all properties with any of those tags.
      in: query
      required: false
      schema:
        type: string
    filter_bedrooms:
      name: filter[bedrooms]
      description: The exact number of bedrooms for search results.
      in: query
      required: false
      schema:
        type: string
    filter_min_price:
      name: filter[min_price]
      description: Minimum listing price for search results.
      in: query
      required: false
      schema:
        type: string
    filter_include_land:
      name: filter[include_land]
      description: Filter by property type. Defaults to false. By setting this to true, the feed will also include land-only properties.
      in: query
      required: false
      schema:
        type: string
    filter_features:
      name: filter[features]
      description: 'Features are entered by the agent as part of the Property description - these could be things such as "Garden" or "Off Road Parking".


        These features should be passed to the API in lowercase and urlencoded.


        You can also enter a semi-colon seperated list to return all properties with any of those features.'
      in: query
      required: false
      schema:
        type: string
    include:
      name: include
      description: Optional related entities to include in the results.
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          enum:
          - branch
          - rooms
          - images
          - floorplans
          - featuresForPortals
          - outsideSpaces
          - parkingSpaces
          - epc
          - epc.pdf
          - additionalMedia
          - tags
          - brochure
          - development
          - rooms.media
        uniqueItems: true
        minItems: 1
        maxItems: 12
      explode: false
      style: form
    filter_min_bedrooms:
      name: filter[min_bedrooms]
      description: Minimum number of bedrooms for search results.
      in: query
      required: false
      schema:
        type: string
    filter_postcode:
      name: filter[postcode]
      description: 'This filter will narrow your search results by first or partial postcode.


        A value of `M` will return all properties who''s postcode begins with M, including `M1 1JU` & `M28 2PD`.


        Entering in `M28 2` will return all active properties in that postcode sector.'
      in: query
      required: false
      schema:
        type: string
    sort:
      name: sort
      description: A field by which to sort. Prefixing with a minus symbol denotes a DESC order.
      in: query
      required: false
      schema:
        type: string
        enum:
        - price
        - -price
        - created_at
        - -created_at
    filter_areas:
      name: filter[areas]
      description: 'Areas are entered by the agent in the Street UI and enable you to filter properties according to custom areas. This can be used to power user friendly searches using familiar geographic areas.


        These areas should be passed to the API in lowercase and urlencoded.


        You can also enter a comma seperated list to return all properties within any of those areas.'
      in: query
      required: false
      schema:
        type: string
    page_number:
      name: page[number]
      description: Set the page number.
      in: query
      required: false
      schema:
        type: number
        minimum: 1
        example: 3
  responses:
    serverError:
      description: The HTTP 500 Internal Server Error server error response code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiError'
          examples:
            example-1:
              value:
                errors:
                - title: Internal Server Error
                  detail: There was an internal server error.
                  code: '500'
    unsupportedMediaType:
      description: The HTTP 415 Unsupported Media Type client error response code indicates that the server refuses to accept the request because the payload format is in an unsupported format.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiError'
          examples:
            example-1:
              value:
                errors:
                - title: Unsupported Media Type
                  detail: The request media type is not supported.
                  code: '415'
    notAcceptable:
      description: The HTTP 406 Not Acceptable client error response code indicates that the server cannot produce a response matching the list of acceptable values defined in the request's proactive content negotiation headers, and that the server is unwilling to supply a default representation.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiError'
          examples:
            example-1:
              value:
                errors:
                - title: Not Acceptable
                  detail: The request could not be accepted.
                  code: '406'
    unprocessableEntity:
      description: The HTTP 422 Unprocessable Entity response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiError'
          examples:
            example-1:
              value:
                errors:
                - title: Unprocessable Entity
                  detail: The request could not be processed.
                  code: '422'
    forbidden:
      description: The HTTP 403 Forbidden response status code indicates that the server understands the request but refuses to authorize it.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiError'
          examples:
            example-1:
              value:
                errors:
                - title: Forbidden
                  detail: The user is forbidden from accessing this resource.
                  code: '403'
    unauthorized:
      description: The HTTP 401 Unauthorized response status code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiError'
          examples:
            example-1:
              value:
                errors:
                - title: Unauthorized
                  detail: The request was made by an unauthenticated user.
                  code: '401'
  schemas:
    Development:
      title: Development
      x-stoplight:
        id: 9ocn585rcsdyu
      allOf:
      - $ref: '#/components/schemas/BaseModel'
      - type: object
        properties:
          type:
            type: string
            default: development
          attributes:
            type: object
            properties:
              name:
                type: string
                example: 171 High Street, Rayleigh
              description:
                type: string
                example: A development of 3 apartments. 2 x 1 beds and 1 x 2 bed.
              created_at:
                type: string
                example: '2022-04-27T10:21:56+01:00'
              updated_at:
                type: string
                example: '2022-04-27T10:21:56+01:00'
    Room:
      title: Room
      x-stoplight:
        id: bm7pfyvg2wbf4
      allOf:
      - $ref: '#/components/schemas/BaseModel'
      - type: object
        properties:
          type:
            type: string
            default: room
          attributes:
            type: object
            properties:
              room_type:
                type: string
                example: bedroom
                enum:
                - bedroom
                - bathroom
                - kitchen
                - dining room
                - lounge
                - garage
                - utility room
                - wc
                - en-suite
                - reception
                - landing
                - lounge / diner
                - conservatory
                - hallway
                - basement
                - dressing room
                - office
                - attic / loft space
                - other
              name:
                type: string
                example: Bedroom One
              width:
                type:
                - 'null'
                - integer
                example: 381
              length:
                type:
                - 'null'
                - integer
                example: 361
              formatted_dimensions:
                type:
                - 'null'
                - string
                example: 11′ 10″ x 12′ 6″ (3.61m x 3.81m)
              description:
                type:
                - 'null'
                - string
                example: Front facing double glazed window, radiator, fitted wardrobe, double room, access to the en-suite.
              order:
                type: string
                example: '2'
              created_at:
                type: string
                example: '2022-06-29T21:18:10+01:00'
              updated_at:
                type: string
                example: '2022-06-29T21:18:10+01:00'
    LettingsListing:
      title: Lettings Listing
      x-stoplight:
        id: 0206kq45gvmpa
      allOf:
      - $ref: '#/components/schemas/BaseModel'
      - type: object
        properties:
          type:
            type: string
            default: lettings_listing
          attributes:
            type: object
            properties:
              status:
                type: string
                enum:
                - To Let
                - Let Agreed
                - Let
                - Withdrawn
                example: To Let
                deprecated: true
              price_pcm:
                type:
                - 'null'
                - integer
                example: 850
              deposit:
                type:
                - 'null'
                - integer
                example: 1000
              display_price:
                type: boolean
                default: true
              archived:
                type: boolean
                default: false
              furnished:
                type: string
                enum:
                - Unfurnished
                - Fully Furnished
                - Part Furnished
                example: Unfurnished
              allows_pets:
                type:
                - 'null'
                - boolean
              is_low_profile:
                type: boolean
                default: false
              publish_after:
                type: string
                format: date-time
                example: '2022-09-14T16:26:36+01:00'
              new_home:
                type: boolean
                default: false
              retirement:
                type: boolean
                default: false
              student_rental:
                type: boolean
                default: false
              min_tenancy_period:
                type:
                - 'null'
                - number
                example: 12
              available_from:
                type:
                - string
                - 'null'
                example: '2022-09-14T16:26:36+01:00'
              created_at:
                type: string
                example: '2022-09-14T16:26:36+01:00'
              updated_at:
                type: string
                example: '2022-09-14T17:05:26+01:00'
      examples:
      - type: lettings_listing
        id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
        attributes:
          ? ''
          : string
          status: To Let
          price_pcm: 850
          deposit: 1000
          display_price: true
          archived: false
          furnished: Unfurnished
          is_low_profile: false
          publish_after: '2022-02-28T11:46:44+00:00'
          new_home: false
          retirement: false
          student_rental: false
          min_tenancy_period: 12
          created_at: '2022-09-14T16:26:36+01:00'
          updated_at: '2022-09-14T17:05:26+01:00'
    Details:
      allOf:
      - $ref: '#/components/schemas/BaseModel'
      - type: object
        properties:
          type:
            type: string
            default: details
          attributes:
            type: object
            properties:
              display_property_style:
                type:
                - 'null'
                - string
                enum:
                - None
                - Other
                - Mid-Terraced
                - End of Terrace
                - Town House
                - Mews
                - Barn Conversion
                - Cottage
                - Farm House
                - Maisonette
                - Studio
                - Bungalow
                - Chalet Bungalow
                - Link Detached
                - Ground Floor Flat
                - Castle
                - Park Home
                - Hotel
                - Guest House
                - Dormer
                - Equestrian
                - Penthouse
                example: Maisonette
              work_required:
                type:
                - 'null'
                - boolean
                example: true
              heating_system:
                type:
                - 'null'
                - string
                enum:
                - Electric Boiler
                - Gas Boiler
                - Storage Heaters
                - Oil
                - Gas Tank
                - Air Source
                - Electric Heating
                - Other
                example: Gas Boiler
              council_tax_band:
                type:
                - 'null'
                - string
                example: E
              council_tax_cost:
                type:
                - 'null'
                - integer
                example: 1616
              local_authority:
                type:
                - 'null'
                - string
                example: Harrogate Borough Council
              service_charge:
                type:
                - integer
                - 'null'
                example: 2183
              service_charge_period:
                type:
                - 'null'
                - string
                enum:
                - Month
                - Year
                example: Year
              service_charge_notes:
                type:
                - 'null'
                - string
              ground_rent:
                type:
                - integer
                - 'null'
                example: 250
              ground_rent_period:
                type:
                - 'null'
                - string
                enum:
                - Month
                - Year
                example: Year
              ground_rent_review_period_years:
                type:
                - integer
                - 'null'
                example: 25
              ground_rent_uplift:
                type:
                - integer
                - 'null'
                example: 65
                description: Value is a percentage
                minimum: 0
                maximum: 100
              ground_rent_expiry:
                type:
                - 'null'
                - string
                example: '2035-12-23'
              full_description:
                type:
                - 'null'
                - string
                example: <p><b> A delightful 3 bedroom end town house standing in cottage style private gardens with the advantage of a single garage situated in the heart of the idyllic village of Follifoot. <\/b><\/p>
              full_description_lettings:
                type:
                - 'null'
                - string
                example: <p><b> A delightful 3 bedroom end town house standing in cottage style private gardens with the advantage of a single garage situated in the heart of the idyllic village of Follifoot. <\/b><\/p>
                x-stoplight:
                  id: p7zqgh21p932y
              short_description:
                type:
                - 'null'
                - string
                example: A delightful 3 bedroom end town house standing in cottage style private gardens with the advantage of a single garage situated in the heart of the idyllic village of Follifoot.
              short_description_lettings:
                type:
                - 'null'
                - string
                example: A delightful 3 bedroom end town house standing in cottage style private gardens with the advantage of a single garage situated in the heart of the idyllic village of Follifoot.
                x-stoplight:
                  id: kii42tvwhwo5c
              location_summary:
                type:
                - 'null'
                - string
                example: Follifoot is a highly regarded and pretty village just a couple of miles South of Harrogate's town centre.
              has_parking:
                type:
                - 'null'
                - boolean
                deprecated: true
              has_outdoor_space:
                type:
                - 'null'
                - boolean
              virtual_tour:
                type:
                - 'null'
                - string
              shared_ownership:
                type: boolean
                default: false
              shared_ownership_notes:
                type:
                - 'null'
                - string
              shared_ownership_rent:
                type:
                - integer
                - 'null'
                example: 366
              shared_ownership_rent_frequency:
                type:
                - 'null'
                - string
                example: Month
                enum:
                - Month
                - Year
              shared_ownership_percentage_sold:
                type:
                - integer
                - 'null'
                example: 60
              material_information:
                type: object
                x-stoplight:
                  id: z0hhyiasfu93m
                properties:
                  council_tax_band:
                    type:
                    - string
                    - 'null'
                    example: D
                    maxLength: 1
                  lease_expiry_date:
                    type:
                    - string
                    - 'null'
                    format: date
                  ground_rent_pence:
                    type:
                    - integer
                    - 'null'
                  ground_rent_period:
                    type:
                    - string
                    - 'null'
                  ground_rent_expiry:
                    type:
                    - string
                    - 'null'
                    format: date
                  ground_rent_review_period_years:
                    type:
                    - integer
                    - 'null'
                  ground_rent_uplift:
                    type:
                    - integer
                    - 'null'
                    description: Value is a percentage
      

# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/street-co/refs/heads/main/openapi/street-co-lettings-api-openapi.yml