Guide Topics
Listing Registration

A workflow for showing services to securely claim calendar authority over a listing.

Last update Nov 1, 2022 DR

STATUS: Stable

Overview

When a showing service's customer "activates" showings on a listing, the service will issue a Registration Request to the hub. This request will be forwarded to the MLS who owns that listing, along with a provisional Registration ID. The MLS will confirm that this vendor has the user's permission to manage their listings' showing schedules, and replies to the hub with a yes or no.

If no, the MLS also provides an explanation string, suitable to show the member. Often this will be instructions to the member for how to come set their showing app permissions on the MLS's portal. The hub relays this to the requesting application who interacts with their member as appropriate.

If yes, the MLS records the Registration ID in the showingHubRegistrationId field of the listing, and the hub relays this along to the requesting application. At this point the listing is live in the hub. Other vendors will get this listing's hub registration ID in their replicated listing data, and can make requests for appointments.

Step 1: Vendor Request

POST /api/v1/registrationRequests/create

{
  "listingId": "string",
  "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "universalPropertyId": "string",
  "address1": "string",
  "address2": "string",
  "city": "string",
  "state": "string",
  "zipCode": "string",
  "listAgentMlsId": "string",
  "listAgentName": "string",
  "listAgentLicenseStateAffirmation": true,
  "listAgentLicenseNumber": "string",
  "listingAgentLicenseState": "string",
  "showableStartDate": "2022-11-01T19:26:09.035Z",
  "showableEndDate": "2022-11-01T19:26:09.035Z",
  "showingInstructions": "string",
  "comments": "string",
  "requiredParticipants": "ListingAgent",
  "showingMethod": "InPersonOnly",
  "confirmationType": "AutoApprove",
  "dateTimeRestrictionsList": [
    {
      "restrictionId": 0,
      "startDatetime": "2022-11-01T19:26:09.035Z",
      "endDatetime": "2022-11-01T19:26:09.035Z"
    }
  ],
  "dateTimeRecurringRestrictionsList": [
    {
      "recurringId": 0,
      "daysOfWeek": "Sunday",
      "numberOfWeeks": 0,
      "effectiveBeginDate": "2022-11-01T19:26:09.035Z",
      "effectiveEndDate": "2022-11-01T19:26:09.035Z",
      "startTime": 0,
      "endTime": 0
    }
  ]
}

A showing app uses the above endpoint to request calendar authority rights on a particular listing. They should then listen on their webhook for an asynchronous response. There are no human factors in this process, so the response should come fairly promptly.

Step 2: MLS Confirmation

POST /api/v1/registrationRequests/{registrationRequestId}/approve
POST /api/v1/registrationRequests/{registrationRequestId}/disapprove

The MLS responds with approve/disapprove of the registration request.

What logic or process the MLS uses to determine whether an application is eligible to manage showings for a given listing is up to the MLS itself. It's not up to the Hub to dictate.

The original three MLSs plan to stand up pages on their portals where members can authorize one or more showing applications--basically a place to say which tool they'll be using. If a request for listing control comes from some other application, it's declined.

But this is one possible implementation. Other MLSs might have other ways of doing things, or might just always say "yes", or whatever.

Step 3: Application Webhook Notification

The application's webhook will be notified with the MLS's approval or disapproval.

In the event of disapproval, the MLS may provide a message to show the user (e.g. "Please come to this URL to record your showing choice with your MLS...").

Notes, Details, Future plans

"Transfer"

Notice that the above process did not check to see if a listing is already registered. If it is, and if the MLS authorizes it, the Hub will cheerfully stomp any existing registration for this listing.

This is how an application will "transfer" control of a listing away from another vendor. The use case here is if a member changes which app they use, or want to do a trial period on a new app. They'll go to the MLS and set their preference to use the new app, and then that app will be authorized to claim control of their listings, including transferring control away from another app.

The new application could be used just to register new listings, or could prompt the user to migrate any or all of their registered listings to the new application. (Existing listings for this user are identifiable from the replicated listing data, by the presence of a showingHubRegistrationId value.)

BRMLS | CRMLS | MRED