Last update 26-July DR

Basic flow

Each MLS organization will stand up its own instance of the showing hub, to manage showing interop traffic within their own market. The hubs will follow a common interface for standard access by vendors.

Applying to Use a Hub

Signing up your organization and creating your application records is a manual task that will be handled by hub staff. Ultimately you'll be given an Organization ID and one or more Application IDs. Each application has its own webhook, access key, and provides an overall data context.

New vendors will be set up on a testing instance of the hub, and their interactions will be vetted for compliance before their production credentials are delivered.

Listing Registration

When a showing platform wishes to advertise that it is the showing manager for a particular listing, that application registers the listing on the Hub. This will associate the listing ID uniquely on the hub with the showing platform that has authority over it. The registrationId that is returned is how you will interact with that registration from then on.

This is done by issuing a registrationRequest, and is subject to the MLS's approval. The Hub informs the MLS of the registration ID that the listing has been given via webhook. The MLS adds the Registration ID and the URL of the Hub into the listing data, which will replicate out into the vendors' systems.

This model enables the concept of listing transfer. When an agent switches from one showing vendor to another, the hub can switch ownership of their listings without a lot of re-entry.

The listing platform can enter time restrictions into the Hub--time periods to advertise that the property is not available to be shown. These can be one-time or recurring time ranges.

Time Restrictions

The Showing Hub provides an endpoint for buyer's apps to get the time periods available for a listing to be shown. The hub makes no assumptions about times of day a showing might happen--if you want to meet at midnight, that's fine with the hub.

A seller's app can set one-time or recurring restrictions, to block out times in the day

Request Creation

When a buyer's agent uses their showing service to request an appointment for a property, the showing service will get the Hub URL and Registration ID from the MLS data, and query the hub for that property's availability for a given day.

The hub will return a data object saying the open time ranges for a showing. This object includes time ranges that are entirely open, and time ranges that have an existing appointment but would allow multiple bookings.

The buyer's system creates a request on that registration ID for a given time range, and the seller's system is notified.

Responding to a Request

The seller's system is notified of a new request, and can respond to accept or decline it. Notification of this response is sent to the buyer's system.

Acknowledging the accepted appointment

When the buyer's application is notified of the accepted request, it should automatically send a confirmation, to register with the hub that both systems are in agreement. This isn't meant to be a human re-confirm; it's about acknowledging via the hub to the showing system on the other side that you've received and processed the appointment, and that both systems are in sync.

The idea is, before we put agents and consumers in cars driving to houses, we want to exhaust every opportunity to make sure no technical glitches caused miscommunication. We want a positive confirmation on the buying side that they received the acceptance of their request and everything's good to go.

Cancelling an Appointment

An appointment can be cancelled by either party. A notification is sent to the other side of the appointment.

Changing an Appointment

Appointments are immutable. If you need to make a change to data on an Appointment, cancel it and create a new one.

Communication between Agents

A simple process exists to send messages between the selling and buying agents, including the initial use cases of inter-app chat and post-showing feedback. See here for details.

MVP Release and the Future

As with any MVP, we made hard decisions about what functionality is need-to-have right now, and what good ideas can be saved for later. Following are plans for future enhancements.

Availability and Request Blocking

For the MVP release, the Availability endpoint is entirely advisory. The hub does nothing to prevent a buyer's system from submiting a request for a "blocked-out" time.

In future versions, we'll add a feature whereby the Listing system can optional configure the hub to auto-decline requests that fall outside the listing's availability.

In addition, we will likely expand the availability endpoint to enable vendors to query multiple listings and/or dates at a time. In MVP, it's explicitly a single property and single date interface.

Webhooks

We'd like the ability for users to configure multiple webhooks, and "subscribe" them to the varius message types. Organizations might choose to do this so they can land messages on certain topics with code handling that topic, or to add geographic redundancy to their webhook infrastructure.

In the API design, this is likely to be handled by adding a POST endpoint to the /webhook/subscription route and opening up the webhookMessageTypes field to be written/updated.

Child Pages