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.

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
  • ActiveListingMLSNumber
  • ActiveListingZip
Combination 2: Name and address information

For an Agent

  • FirstName
  • LastName
  • Address
  • Zip
  • State

For an Office

  • OfficeName
  • Address
  • Zip
  • State

Example API Call

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

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

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

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 - your API token
  • Redirect URL - the url Homes.com Connect will redirect your user to when they authenticate

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

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