Homes.com Connect API

Homes.com Connect Partner-Side Authentication Process

Homes.com Connect provides a process for approved Partners to connect their users to Homes.com Connect customers, enabling the Partner to access the agent or broker's listings or other data via the Homes360 APIs.

Connect a User

To connect your user, use the following steps:

Step 1: Obtain an API Token
Call the Token API to obtain your PartnerToken, using your account credentials:
Step 2: Identify the User

Use your API token to call the Homes360 Account Identification API in order to identify if the agent or office is a current Homes.com Connect customer.

If searching for an Agent, pass in AccountType 100. If searching for an Office, pass in AccountType 200.

To attempt to find a match, pass in one or more of the following combinations of parameters to the API:

Combination 1: Listing information of an active listing
  • AccountType (100 = Agent, 200 = Office)
  • ActiveListingMLSNumber
  • ActiveListingZip
Combination 2: Name and address information

For an Agent

  • AccountType (100 = Agent)
  • FirstName
  • LastName
  • Address
  • Zip
  • State

For an Office

  • AccountType (200 = Office)
  • OfficeName
  • Address
  • Zip
  • State

Example API Call

https://api.homesconnect.com/api360/accounts?ActiveListingMLSNumber=MLS12345&ActiveListingZip=33333

This token should be placed in the API request's Authorization header with the scheme homes360: Authorization: home360 PartnerToken

The API can return one or multiple accounts as potential matches. Each potential match will include the following data:

{
    ReturnCount: 2,
    ClaimYourProfileURL: "https://profile.homes.com?pdata=123",
    Accounts: [
        {
            ProfileID: 1234567
            FirstName: "Jane",
            LastName: "Smith", 
            Email: "jsmith@gmail.com",
            Address: "999 Yamato Rd.",
            City: "Boca Raton",
            State: "FL",
            Zip: "33333", 
            AuthURL: "https://12345678.homesconnect.com/system/partnerconnect.aspx?pdata=123"
        },
        {
            ProfileID: 2234567
            FirstName: "Jane",
            LastName: "Smith", 
            Email: "janesmith@gmail.com",
            Address: "999 State Rd.",
            City: "Boca Raton",
            State: "FL",
            Zip: "33334", 
            AuthURL: "https://22345678.homesconnect.com/system/partnerconnect.aspx?pdata=123"
        }
    ]
}

Account Match Found

If an account match or matches are found, your system is responsible for presenting them to user and asking for confirmation.

Once your user identifies the correct account, direct the user to their AuthURL appending the two required parameters:

  • PartnerToken - required this is your API token obtained from Step 1 of Connect a User
  • RedirectURL - required this is the url Homes.com Connect will redirect your user to when they authenticate
  • PartnerBrandID - optional pass this parameter if you wish to implement custom branding (see below for details)

You may append any additional parameters your system needs to handle the redirect back to your system, and Homes.com Connect will append them to your RedirectURL.

NOTE: The RedirectURL must be in your list of approved URL's. Any RedirectURL's you wish to use must be submitted to the Homes.com Connect team.
Example:
https://12345678.homesconnect.com/system/partnerconnect.aspx?pdata=123&partnertoken=<partner_token>&redirecturl=https%3A%2F%2Fwww.partnerdomain.com%2Fhcauthhandler&param1=a&param2=b&param3=c&partnerbrandid=1234

On this page, the user will be required to authorize your application by entering their Homes.com Connect credentials.

After successfully authorizing your application, the Homes.com Connect will redirect the user to your RedirectURL appending the user's API token along with any of the additional parameters you appended to the AuthURL. The user's token will be passed in the UserToken parameter. An additional parameter, result, will also be appended to indicate success or cancellation.

Example:
https://www.partnerdomain.com/hcauthhandler?usertoken=<user_token>>&param1=a&param2=b&param3=c&result=success

The possible values of result are:

  • success
  • cancel

If the user cancelled, the url would be: https://www.partnerdomain.com/hcauthhandler?param1=a&param2=b&param3=c&result=cancel

Account Match Not Found

If a matching Homes.com Connect account is not found, redirect the user to the Homes.com Claim Your Profile page url, which will be returned in the API's ClaimYourProfileURL property.

Append the following parameters to the url:

  • PartnerToken - required your API token
  • RedirectURL - required the url Homes.com Connect will redirect your user to when they authenticate
  • UInfo - optional user data that will pre-populate the form (see below for details)

You may append any additional parameters your system needs to handle the redirect back to your system, and Homes.com Connect will append them to your RedirectURL.

NOTE: The RedirectURL must be in your list of approved URL's. Any RedirectURL's you wish to use must be submitted to the Homes.com Connect team.
Example:
https://profile.homes.com?pdata=123&PartnerToken=<partner_token>&RedirectURL=https%3A%2F%2Fwww.partnerdomain.com%2Fhcauthhandler&param1=a&param2=b&param3=c

On this page, the user will have the opportunity to create a Homes.com Connect profile. On successful creation of a profile, Homes.com Connect will redirect your user to your RedirectURL with the user's API token.

Example:
https://www.partnerdomain.com/hcauthhandler?usertoken=<user_token>>&param1=a&param2=b&param3=c&result=success

The possible values of result are:

  • success
  • cancel
  • account_exists
  • error

If an error occurred, a parameter errorMessage containg the error description will be appended to the RedirectURL.

If the user cancelled, the url would be: https://www.partnerdomain.com/hcauthhandler?param1=a&param2=b&param3=c&result=cancel

Account Status

After the user creates an account via Claim Your Profile, you can check the status of the account with the Homes360 Account Status API. The Account Status API uses the HomesAPI Authentication Scheme, which requires your Partner Token in url parameter "token" and the user token in the Authentication header.

Example Output:

{
    "profileID": 12345678,
    "provisioned": true,
    "onboardingComplete": true,
    "createPasswordURL": "https://login.homesconnect.com/createpassword/12345678/999999",
    "createPasswordURLExpiration": "2019-07-12T15:46:31.5531997-04:00",
    "loginURL": "https://login.homesconnect.com",
    "listingCount": 6,
    "listingSources": [
        {
            "listingSourceID": 10000,
            "listingSourceName": "Any Florida MLS, Anytown, FL",
            "codes": [
                "12356"
            ]
        },
        {
            "listingSourceID": 10001,
            "listingSourceName": "My Florida MLS, Hometown, FL",
            "codes": [
                "234567",
                "888888"
            ]
        }
    ]
}

Explanation of data points:

  • profileID Homes.com Connect ID for the Account.
  • provisioned Will be True if provisioning of the Account is complete. This would only be False between the time the user completes Claim Your Profile and the time Homes.com Connect processes the Account. Normally, this would be a few minutes, but could be up to an hour.
  • onboardingComplete This will be True if the user has clicked the Create Password link from the Welcome Email, logged into Homes.com Connect, and completed the Onboarding process.
  • createPasswordURL A link for the user to reset or create a Homes.com Connect password. After creating the password, the user must login and complete the Onboarding process.
  • createPasswordURLExpiration A datestamp of when the createPasswordURL will expire. If expired, call the Account Status API again to receive a new link.
  • loginURL A link to the Homes.com Connect login. If the user has already created a password, send them to this link to login and complete the Onboarding process if they have not yet done so.
  • listingCount Number of listings that have been associated to the user in the Homes.com Connect system. Listings will usually be associated in a matter of minutes following completion of Onboarding, but could be up to an hour.
  • listingSources During the Onboarding process, the user selects which MLS boards they belong to and enters their agent/office code(s) for each. This property will return a list of those memberships along with their agent/office codes.

Custom Branding

You can optionally customize elements such as the brand name, logo, text and colors of the Partner Connect and Claim Your Profile pages. First you must submit a URL path where you will host the stylesheet and images on your system to the Homes.com team. This will be your approved resource path, and resources not contained in this path will not be allowed.

Then pass a parameter called "PartnerBrandID" to the AuthURL and/or the ClaimYourProfileURL. The value should be a unique ID that identifies a brand on your system. When that parameter is passed, the page will render a link to a stylesheet on your system which can then add images hosted on your system. This stylesheet will be added after the default stylesheet so you can override the default classes.

For example, let's say your approved resource path is https://www.partnerdomain.com/css/brands. if you pass in "partnerbrandid=1234" to the Partner Connect page, it will render a stylesheet link to: https://www.partnerdomain.com/css/brands/1234_connect.css. If you pass this ID to the Claim Your Profile page, it will render a stylesheet link to: https://www.partnerdomain.com/css/brands/1234_create.css.

For details on what elements can be customized and how to customize them, see Custom Partner Branding.

An example of a customized version of the Partner Connect page can be viewed here: https://bluebrokerconfig.enqa-dhmstaging.com/system/partnerconnect.aspx?partnertoken=4j10r7LpUbR3aB2Sq8g88ZG719k9XD1sHXf6Iq3ha6W7nhH2pKA6EQg3FhqVu7gk&redirecturl=https://scottwu-beta.enqa-dhmstaging.com&PartnerBrandID=brand1

An example of a customized version of the Claim Your Profile page can be viewed here: https://register.enqa-dhmstaging.com/?pdata=123&partnertoken=4j10r7LpUbR3aB2Sq8g88ZG719k9XD1sHXf6Iq3ha6W7nhH2pKA6EQg3FhqVu7gk&redirecturl=https://scottwu-beta.enqa-dhmstaging.com&param1=a&param2=b&param3=c&partnerbrandid=brand1

You also have the ability to customize the text on the Parter Connect and Claim Your Profile pages by placing a json file in your approved resource path. The pages will query those files real-time and render any custom text you have added.

For example, let's say your approved resource path is https://www.partnerdomain.com/css/brands. if you pass in "partnerbrandid=1234" to the Partner Connect page, it will query the file at: https://www.partnerdomain.com/css/brands/1234_connect.json. If you pass this ID to the Claim Your Profile page, it will query the at: https://www.partnerdomain.com/css/brands/1234_create.json.

For details on what text can be customized and how to customize it, see Partner Connect Custom Text and Claim Your Profile Custom Text.

Pre-populating the Claim Your Profile Form

You can optionally pre-populate the fields on the Claim You Profile form with you user's data by passing the data in a parameter called "UInfo". The data you pass in this parameter should be Base64 encoded JSON in the following format. All the fields are optional, so only pass the property/values you need. 


{
    "firstName":"firstNamePartner1",
    "lastName":"lastNamePartner1",
    "email":"partner.test1@email.com",
    "email2":"partner.test1@email2.com",
    "address1":"address1111 1111",
    "city":"Your Hometown",
    "state":"FL",
    "zip":"33333",
    "officePhone":"1111111112",
    "cellPhone":"2222222223",
    "homePhone":"3333333334",
    "officeName":"officeName",
    "agentMLSID":"agentIDXCodePartner1",
    "brokerMLSID":"brokerIDXCodePartner1",
    "mlsNumbers":"mlsNumbers",
    "userLevel":"100"
}

The AuthURL would then be in this format: https://profile.homes.com?pdata=123&PartnerToken=<partner_token>&RedirectURL=https%3A%2F%2Fwww.partnerdomain.com%2Fhcauthhandler&param1=a&param2=b&param3=c&uinfo=eyJmaXJzdE5hbWUiOiAiZmlyc3ROYW1lUGFydG5lcjEiLCJsYXN0TmFtZSI6ICJsYXN0TmFtZVBhcnRuZXIxIiwiZW1haWwiOiAicGFydG5lci50ZXN0MUBlbWFpbC5jb20iLCJlbWFpbDIiOiAicGFydG5lci50ZXN0MUBlbWFpbDIuY29tIiwiYWRkcmVzczEiOiAiYWRkcmVzczExMTEgMTExMSIsImNpdHkiOiAiWW91ciBIb21ldG93biIsInN0YXRlIjogIkZMIiwiemlwIjogIjMzMzMzIiwib2ZmaWNlUGhvbmUiOiAiMTExMTExMTExMiIsImNlbGxQaG9uZSI6ICIyMjIyMjIyMjIzIiwiaG9tZVBob25lIjogIjMzMzMzMzMzMzQiLCJvZmZpY2VOYW1lIjogIm9mZmljZU5hbWUiLCJhZ2VudE1MU0lEIjogImFnZW50SURYQ29kZVBhcnRuZXIxIiwiYnJva2VyTUxTSUQiOiAiYnJva2VySURYQ29kZVBhcnRuZXIxIiwibWxzTnVtYmVycyI6ICAibWxzTnVtYmVycyIsInVzZXJMZXZlbCI6ICAiMTAwIn0=