openapi: 3.0.3
info:
  title: MLS Grid RESO Web Lookup Property API
  description: 'The MLS Grid RESO Web API is a normalized, RESO Data Dictionary–compliant OData v4 Web API for replicating

    Multiple Listing Service (MLS) data across the dozens of participating boards on the MLS Grid network. The

    API is optimized for incremental replication using `ModificationTimestamp`, supports `$select`, `$filter`,

    and `$expand` for related resources (Media, Rooms, UnitTypes), and applies a single license agreement across

    all participating MLSs.


    Authentication uses long-lived OAuth 2.0 bearer tokens issued through the MLS Grid web application.

    '
  version: 2.0.0
  contact:
    name: MLS Grid Support
    email: support@mlsgrid.com
    url: https://www.mlsgrid.com
  license:
    name: MLS Grid Master Data License Agreement
    url: https://www.mlsgrid.com
  x-logo:
    url: https://www.mlsgrid.com
servers:
- url: https://api.mlsgrid.com/v2
  description: MLS Grid Web API v2 (production)
security:
- bearerAuth: []
tags:
- name: Property
  description: Property listings (RESO Data Dictionary Property resource).
paths:
  /Property:
    get:
      tags:
      - Property
      summary: List Properties
      description: Replicate Property listings filtered by `OriginatingSystemName` and `ModificationTimestamp`. Use `$expand=Media,Rooms,UnitTypes` to include nested resources and `@odata.nextLink` for pagination.
      operationId: listProperties
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Expand'
      - $ref: '#/components/parameters/Top'
      - $ref: '#/components/parameters/Count'
      responses:
        '200':
          description: Collection of Property records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /Property('{ListingKey}'):
    get:
      tags:
      - Property
      summary: Get Property by Key
      description: Retrieve a single Property record by its prefixed `ListingKey` (e.g. `actris-1234567`).
      operationId: getProperty
      parameters:
      - name: ListingKey
        in: path
        required: true
        schema:
          type: string
        description: Prefixed MLS Grid listing key.
      - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: A single Property record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Property'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Property not found.
components:
  parameters:
    Select:
      name: $select
      in: query
      description: Comma-separated list of fields to return. Reduces payload size.
      schema:
        type: string
      example: ListingKey,StandardStatus,ListPrice,ModificationTimestamp
    Count:
      name: $count
      in: query
      description: When `true`, includes `@odata.count` in the response.
      schema:
        type: boolean
    Filter:
      name: $filter
      in: query
      description: 'OData `$filter` expression. Required pattern uses `OriginatingSystemName eq ''<system>''` combined with

        `ModificationTimestamp gt <UTC datetime>` for incremental replication. Replication queries are

        restricted to a limited set of searchable fields documented per resource.

        '
      schema:
        type: string
      example: OriginatingSystemName eq 'actris' and ModificationTimestamp gt 2026-01-01T00:00:00Z
    Top:
      name: $top
      in: query
      description: Maximum number of records to return per page.
      schema:
        type: integer
        maximum: 1000
    Expand:
      name: $expand
      in: query
      description: Comma-separated list of related resources to expand inline. Common values for Property are `Media`, `Rooms`, and `UnitTypes`.
      schema:
        type: string
      example: Media,Rooms,UnitTypes
  schemas:
    Property:
      type: object
      description: RESO Data Dictionary Property resource. Only fields present in the originating MLS are populated.
      properties:
        ListingKey:
          type: string
          description: Prefixed MLS Grid listing key (e.g. `actris-1234567`).
        OriginatingSystemName:
          type: string
          description: Source MLS identifier (e.g. `actris`, `mred`, `nwmls`).
        StandardStatus:
          type: string
          description: RESO StandardStatus enumeration.
          enum:
          - Active
          - ActiveUnderContract
          - Pending
          - Hold
          - Withdrawn
          - Expired
          - Closed
          - Canceled
          - ComingSoon
          - Delete
          - Incomplete
        PropertyType:
          type: string
          description: RESO PropertyType enumeration.
          enum:
          - Residential
          - ResidentialIncome
          - ResidentialLease
          - CommercialSale
          - CommercialLease
          - BusinessOpportunity
          - Farm
          - Land
          - ManufacturedInPark
        ListPrice:
          type: number
        ModificationTimestamp:
          type: string
          format: date-time
        PhotosChangeTimestamp:
          type: string
          format: date-time
        MlgCanView:
          type: boolean
          description: Indicates whether the listing may currently be viewed under license terms.
        MlgCanUse:
          type: array
          description: Allowed use cases for the listing (e.g. `IDX`, `VOW`, `BO`, `PT`).
          items:
            type: string
        Media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        Rooms:
          type: array
          items:
            $ref: '#/components/schemas/Room'
        UnitTypes:
          type: array
          items:
            $ref: '#/components/schemas/UnitType'
    Media:
      type: object
      properties:
        MediaKey:
          type: string
        ResourceRecordKey:
          type: string
          description: Foreign key back to Property (or other resource).
        OriginatingSystemName:
          type: string
        MediaURL:
          type: string
          description: URL for downloading a local copy. Direct hot-linking is not permitted.
        MediaCategory:
          type: string
        Order:
          type: integer
        MediaModificationTimestamp:
          type: string
          format: date-time
    UnitType:
      type: object
      properties:
        UnitTypeKey:
          type: string
        UnitTypeType:
          type: string
        UnitTypeBedsTotal:
          type: integer
        UnitTypeBathsTotal:
          type: number
    Room:
      type: object
      properties:
        RoomKey:
          type: string
        RoomType:
          type: string
        RoomLevel:
          type: string
        RoomLength:
          type: number
        RoomWidth:
          type: number
    PropertyCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Property'
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
    RateLimited:
      description: Rate limit exceeded. The MLS Grid Web API enforces 2 RPS, 7,200 requests/hour, 40,000 requests/24h, and 4 GB/hour download caps. Repeated violations may suspend the token.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the client may retry.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2
      description: Long-lived OAuth 2.0 bearer token issued via the MLS Grid web application token tab.