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.
To connect your user, use the following steps:
PartnerToken
, using your account credentials:
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.
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"
}
]
}
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.
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.
https://12345678.homesconnect.com/system/partnerconnect.aspx?pdata=123&partnertoken=<partner_token>&redirecturl=https%3A%2F%2Fwww.partnerdomain.com%2Fhcauthhandler¶m1=a¶m2=b¶m3=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.
https://www.partnerdomain.com/hcauthhandler?usertoken=<user_token>>¶m1=a¶m2=b¶m3=c&result=success
The possible values of result
are:
If the user cancelled, the url would be:
https://www.partnerdomain.com/hcauthhandler?param1=a¶m2=b¶m3=c&result=cancel
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 tokenRedirectURL
- required the url Homes.com Connect will redirect your user to when they authenticateUInfo
- 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
.
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.
https://profile.homes.com?pdata=123&PartnerToken=<partner_token>&RedirectURL=https%3A%2F%2Fwww.partnerdomain.com%2Fhcauthhandler¶m1=a¶m2=b¶m3=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.
https://www.partnerdomain.com/hcauthhandler?usertoken=<user_token>>¶m1=a¶m2=b¶m3=c&result=success
The possible values of result
are:
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¶m2=b¶m3=c&result=cancel
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.
{
"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.
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
.
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¶m1=a¶m2=b¶m3=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
.
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¶m1=a¶m2=b¶m3=c&uinfo=eyJmaXJzdE5hbWUiOiAiZmlyc3ROYW1lUGFydG5lcjEiLCJsYXN0TmFtZSI6ICJsYXN0TmFtZVBhcnRuZXIxIiwiZW1haWwiOiAicGFydG5lci50ZXN0MUBlbWFpbC5jb20iLCJlbWFpbDIiOiAicGFydG5lci50ZXN0MUBlbWFpbDIuY29tIiwiYWRkcmVzczEiOiAiYWRkcmVzczExMTEgMTExMSIsImNpdHkiOiAiWW91ciBIb21ldG93biIsInN0YXRlIjogIkZMIiwiemlwIjogIjMzMzMzIiwib2ZmaWNlUGhvbmUiOiAiMTExMTExMTExMiIsImNlbGxQaG9uZSI6ICIyMjIyMjIyMjIzIiwiaG9tZVBob25lIjogIjMzMzMzMzMzMzQiLCJvZmZpY2VOYW1lIjogIm9mZmljZU5hbWUiLCJhZ2VudE1MU0lEIjogImFnZW50SURYQ29kZVBhcnRuZXIxIiwiYnJva2VyTUxTSUQiOiAiYnJva2VySURYQ29kZVBhcnRuZXIxIiwibWxzTnVtYmVycyI6ICAibWxzTnVtYmVycyIsInVzZXJMZXZlbCI6ICAiMTAwIn0=