Registrations & Transfers

Creating new Registrations

Miscellaneous Registration Notes:

  • When a registration is first created, it will be “Not Showable” until the listing applicatioin activates it using the {{showinghubBaseUrl}}/api/v1/registrations/{{registrationId}}/activate API
  • The exception is if a registration is transferred to a new showing provider.

There are 2 ways a Listing Showing Provider knows they will be the appointment scheduler for a new listing.

  • The agent will publish a listing through Listing Management and indicate the listing is for a particular showing provider. Once published, a link appears on the Listing Management page that will navigate the agent to the Showing Provider. The querystring of the URL will contain any necessary data that the showing provider may need. (Plus, the same data will be in the RETS/RESO WebApi feed they receive)
  • The showing provider periodically checks their RETS/RESO WebAPI feed with any new or removed listings. If it finds something new with the “ShowinghubApplicationId” field to be their unique id, they know it’s theirs.

Once the listing application sees they will be the appointment scheduler for a new listing, they need to register it to the MLS. There are two methods by which a Listing Showing Provider sets up themself as the appointment scheduler for a new listing:

  • Listing Publication via Listing Management: When an agent publishes a listing through the Listing Management system, they specify the designated showing provider. Once published, a “Managed Showing” link is generated on the Listing Management page that redirects the agent to the showing provider’s platform. This link includes a query string containing data required by the showing provider.

  • Polling RETS/RESO Web API Feed: The showing provider routinely polls their RETS/RESO Web API feed to check for any newly added or removed listings. When a new listing is created, the ShowingHubApplicationId field will match the showing provider's unique identifier. That is the indication that the registration is managed by them.

Once the showing provider confirms they are assigned as the appointment scheduler for a new listing, they must register the listing with the MLS to complete the process.

image.png

The Diagram above indicates the path of creating a new registration in the ShowingHub and the MLS to approve or disapprove it. The numbers below correspond to the circled numbers in the diagram.

  1. The agent publishes a new listing to the MLS.
  2. The Listing Application pulls the new data periodically and receives the new listing.
    1. (2) alternate – It’s possible the agentcan click the “Manage Showing” link which will navigate the agent to the Showing Provider. At that time, the Showing Provider has the option to register the listing then or wait for it to appear on the RETS/WebAPI feed.
  3. The Listing Application sends an API request to the Hub, indicating they are the appointment scheduler for the listing as requested by the agent.
    1. API: {{showinghubBaseUrl}}/api/v1/registrationRequests/create
    2. Request body:

.
3. Response:

  1. The ShowingHub will forward the listing to the MLS

  2. The MLS is responsible for ensuring that the listing registration from the Showing Provider is for the correct one. It will validate the ListingId and the ShowingHubApplicationId of the registrationrequest. Based on the whether it’s approved or disapproved, then one of two things happen:

    1. The MLS disapprove it. It will
      1. API: to the ShowingHub: {{showinghubBaseUrl}}/api/v1/registrationRequests/{registrationRequest}/disapprove
    2. The MLS approves it
      1. API: to the ShowingHub: {{showinghubBaseUrl}}/api/v1/registrationRequests/{registrationRequest}/approve

  3. The Showinghub will forward that request back to the Listing Application using the webhook Url that’s on their subscription

    1. If Disapproved, the Request body of the webhook looks like this:

    2. WebhookEvent Name: RegistrationRequestDisapproved

    3. If Approved, the Request body of the webhook looks like this:

    4. WebhookEvent Name: RegistrationRequestApproved

      {
        "organizationId": "cc6dcf40-c4ac-4302-01ed-08dca1ef3a2c",
        "applicationId": "ee93abeb-4073-4e0f-52b4-08dca1eff065",
        "subscriptionId": "e124c6b1-bab8-48b4-5efd-08dcc86ab94e",
        "webhookEvent": "RegistrationRequestApproved",
        "attempt": 1,
        "data": {
          "upi": "GB",
          "timeZone": "Eastern",
          "address1": "100 Apple Street",
          "address2": "",
          "city": "RandomCity",
          "stateOrProvince": "PA",
          "zipCode": "45662",
          "listAgentMlsId": "5056675",
          "listAgentName": "Emmy",
          "listAgentLicenseNumber": "HTTP",
          "listingAgentLicenseState": "PA",
          "showingInstructions": "use the left door to enter the house",
          "comments": null,
          "showingMethod": "InPersonOnly",
          "advanceNoticeHours": 4,
          "leaveCalendarOpen": null,
          "confirmationType": "ConfirmationRequired",
          "listingId": "ABCD1234",
          "applicationId": "ee93abeb-4073-4e0f-52b4-08dca1eff065",
          "application": null,
          "status": "Approved",
          "mlsId": "4f1460f6-843f-46e5-97d3-08dc912fe76b",
          "statusModifiedOn": "2024-10-22T18:26:41.6344474+00:00",
          "registrationId": "033d4f0f-44e6-4a5c-a32a-c4ec137d0444",
          "createdBy": "ee93abeb-4073-4e0f-52b4-08dca1eff065",
          "createdOn": "2024-10-22T18:26:41.6864802+00:00",
          "id": "949d3fa2-da00-4896-a7c9-08dcf2c71355",
          "modifiedBy": "4f1460f6-843f-46e5-97d3-08dc912fe76b",
          "modifiedOn": "2024-10-22T19:18:40.8198574+00:00"
        },
        "creationTimeUtc": "2024-10-22 07:18:40"
      }

Registration Availability

This API returns a list of available times when the property can be shown, considering any restrictions and pre-existing appointments. If the AdvanceNoticeHours field is specified during registration, it will also be factored in. If the LeaveCalendar field is set to true during registration, pre-existing appointments will be excluded from the results. Please note, this API supports only one registration and one day at a time.

Notes:

  1. The “showDate” returned in the response is a date/time offset in the timezone of the registration.
  2. The startTime and endTime are always in military format.

API: {{showinghubBaseUrl}}/api/v1/registrations/{{registrationId}}/availability?showDate=YYYY-MM-DD

  1. Response body:

Restrictions

There are times where a property owner may not want their property being showing by other listing agents. There are 2 types: Single Restrictions and Recurring Restrictions

For both types, dates are always entered in the same time zone as the registration using a datetime offset. The request is an array of as many as needed. Each item is for one day of the week.

Create Single Restriction

API: {{showinghubBaseUrl}}/api/v1/registrations/{{registrationId}}/createRestriction

  1. Request Body:
  1. Response Body:

Create Recurring Restrictions

API: {{showinghubBaseUrl}}/api/v1/registrations/{{registrationId}}/createRecurringRestriction

  1. Request Body:
  1. Response Body: