Cloud CMA API

Introduction

Cloud CMA allows real estate agents to easily create custom CMA, Buyer Tour, and Property Reports. In order to enable this functionality to be embedded in other web sites, especially MLS sites, we have made an API publicly available. Using the simple links and images below, you can send the listings your user has currently selected, in the form of their MLS numbers, to Cloud CMA and kick off the desired report. You can also use AJAX techniques below to send the desired MLS numbers over, update the user on the success or failure of that post, and allow the user to continue on your site without interruption.

Cloud CMA is a subscription-based service and requires an id and password to use. All uses of the API will work immediately if the user is already logged into a session. If a current session does not exist, Cloud CMA will handle the authentication by requesting the user log in first, then automatically route them to the requested page from there. Developers who need a trial id and password can request one from the e-mail at the bottom of the page.

More functionality of Cloud CMA can be exposed pretty easily using standard RESTful web services - send over your suggestions.

Creating Reports

Your user has selected one or more listings on your site and you provide them a one-click solution to send those listings to Cloud CMA and start the report creation process.

Method:

Just do a very simple GET or POST to our RESTful API from a text or image link.

Parameters

mlsnums (Optional)

List of one or more MLS numbers representing the users selected listings, comma-separated. Property Reports only contain one listing, so send only one mlsnum for that report type. CMA and Buyer Tour reports can handle as many mlsnums as you wish.

address (Optional)

A single address for the selected listing. This param provides the address to search for in the Property Report and Flyer, or the subject property address in the CMA.

title (Optional)

Title for the report. Most of the time you'll leave this param out and the user will fill in their desired title in Cloud CMA.

notes (Optional)

Notes for the report. Most of the time you'll leave this param out and the user will fill in their desired notes in Cloud CMA.

beds (Optional)

Beds of the subject property. Only applies to the CMA Report.

baths (Optional)

Baths of the subject property. Only applies to the CMA Report.

sqft (Optional)

Square feet of the subject property. Only applies to the CMA Report.

prop_type (Optional)

Property type filter for proximity search. Only applies to the CMA Report.

min_listings (Optional)

Minimum listings to fetch for proximity search. Only applies to the CMA Report.

lat (Optional)

Force the latitude of the subject property for proximity search. Normally the subject property address is geo-coded, but this over-rides that. Only applies to the CMA Report.

lon (Optional)

Force the longitude of the subject property for proximity search. Normally the subject property address is geo-coded, but this over-rides that. Only applies to the CMA Report.

callback_url (Optional)

Webhook callback url on the callers side. See webhook section below.

Examples

Create a new CMA

get
https://tomferry.cloudcma.com/cmas/new?mlsnums=12345,12346,12347&title=The+Smith+Family&notes=Initiated+from+your+MLS
get
https://tomferry.cloudcma.com/cmas/new?mlsnums=12345,12346,12347&title=The+Smith+Family&notes=Initiated+from+your+MLS&address=123+Main+St,+Huntington+Beach,+CA&prop_type=RES

Create a new Buyer Tour

get
https://tomferry.cloudcma.com/tours/new?mlsnums=12345,12346,12347&title=The+Smith+Family&notes=Initiated+from+your+MLS

Create a new Property Report

get
https://tomferry.cloudcma.com/properties/new?mlsnums=12345&title=The+Smith+Family&notes=Initiated+from+your+MLS
get
https://tomferry.cloudcma.com/properties/new?address=123+Main+Street,+Costa+Mesa,+CA+92626&title=The+Smith+Family&notes=Initiated+from+your+MLS

Create a new Flyer

get
https://tomferry.cloudcma.com/flyers/new?mlsnums=12345&title=The+Smith+Family&notes=Initiated+from+your+MLS
get
https://tomferry.cloudcma.com/flyers/new?address=123+Main+Street,+Costa+Mesa,+CA+92626&title=The+Smith+Family&notes=Initiated+from+your+MLS

Using Webhooks

A webhook is a user-defined HTTP callback that is triggered by an event. We allow you to optionally include a webhook callback_url parameter in your API calls to start a new report. If present, we will POST details about this report whenever it is created, updated, or destroyed. Details are sent in JSON format and include the report id, user_id, type, title, notes, mls_code, created_at, updated_at, deleted_at, edit_url, pdf_url, and action. POSTs are queued and automatically re-tried several times upon failure.

The use case for this would be a broker intranet site that initiates creating a report using our API, then wants to keep track of that report in their own UI, including status updates and deep-linking for editing and PDF generation. The callback side would want to include things like their unique user id and maybe a report id in the callback url so that events can be tied back into their system.

Sample webhook payload

{
  id: 12345,
  user_id: 67890,
  type: 'Cma',
  title: 'The Robertsons',
  notes: '',
  mls_code: 'crmls',
  created_at: '2015-07-21T18:04:24Z',
  updated_at: '2015-07-21T18:04:24Z',
  deleted_at: nil,
  edit_url: 'http://cloudcma.com/cmas/12345/edit',
  pdf_url: 'http://cloudcma.com/pdf/f6f280a379b61c88e9bb68c6f996d501',
  action: 'update'
}

Broker Web Site Widgets

Cloud CMA creates custom CMAs and Property Reports utilizing the best sources of property, school, neighborhood, and other information it can find on the internet. Brokers can make these reports available to consumers on their web sites where they act as a great lead capture tool.

Create and deliver a Quick CMA

Embed a lead generation widget on your blog or web site with the headline "What is your home worth?" or similar. The form will capture the consumers name, email, and subject property address, automatically generate a Quick CMA that is fully branded to the agent, and email that report to the consumer within a minute.

Method:

Just do a GET or POST to our RESTful API with data collected from your lead form.

Parameters

api_key (Required)

API key for the Cloud CMA user. Users can obtain their unique key by choosing the Settings link, then API in Cloud CMA.

address (Required)

Consumers subject property address.

sqft (Optional)

Square feet of the subject property.

beds (Optional)

Beds of the subject property.

baths (Optional)

Baths of the subject property.

prop_type (Optional)

Restrict comparables to a specific property type. The value of this parameter must match a valid property type used in this MLSs RETS metadata.

title (Optional)

Title for report. If not present, will use the consumers name or email address.

headline (Optional)

Headline to use on the cover page. Default is 'Quick CMA'.

name (Optional)

Consumers full name which will appear in the notes of the CMA.

min_listings (Optional)

Minimum number of listings to include in report. Default is 10.

months_back (Optional)

Maximum number of months back to go for listings. Default is 12.

email_subject (Optional)

Subject line for email. Default will be used if not present.

email_msg (Optional)

Message body for email. The email will only include the report link if not present.

template (Optional)

Template name of pages to include in report. Uses default 'Web Leads' template if undefined or if the specified template cannot be found.

job_id (Optional)

Unique id from the requester to be used in the callback.

callback_url (Optional)

Callback URL we will POST to when the report is finished publishing. The POST will include the pdf_url and job_id (from above) parameters. You can then use this information to send a custom formatted email from your system.

Create and deliver a Quick CMA

get
https://tomferry.cloudcma.com/cmas/widget?api_key=your-api-key&name=Joe+Buyer&email_to=joe_buyer@example.com&address=123+Main+St,+Huntington+Beach,+CA+92648

Suppressing emails from Cloud CMA

We will not send emails about this CMA to consumers if the email_to param is empty or missing. Additionally, we will not send emails about this CMA to the agent if the callback_url is a valid url and the job_id param has a value.

Request a Property Report for email delivery

Consumer has requested a property report for the property they are currently viewing be created and emailed back to them.

Method:

Just do a very simple GET from a link or a POST from a form to our RESTful API.

The process breaks down to these steps:

  1. Consumer clicks on a call to action button for "Free Property Report" on a brokers web site.
  2. Consumer gets marketing information about the Property Report and is asked for their e-mail address.
  3. The url of the property detail report on this brokers web site, the brokers Cloud CMA id, the consumers email address, and other optional parameters are sent to Cloud CMA.
  4. Cloud CMA gathers the all the data, publishes the report, and e-mails the url of the PDF report to the consumer.

Parameters

api_key (Required)

The Cloud CMA API key for the user. Users can find their API key in the app by choosing Settings and API.

email_to (Required)

The email address of the consumer where the final report will be delivered.

mlsnum (Required)

The MLS number of the subject property.

address (Required)

The address of the subject property. Address is less accurate than MLS number due to the mis-typing of some addresses in the MLS.

email_subject (Optional)

The subject line for the email. Default is "Your Cloud CMA Property Report".

email_msg (Optional)

Message to include in the body of the email. Default is no message, just the url of the PDF report.

theme (Optional)

The theme to use when creating the report. Default is the last theme the broker used when creating a Cloud CMA Property Report.

title (Optional)

The title of the Property Report in Cloud CMA. Default is the email_to param. Consumer sees this on the cover page of the report under "Prepared for".

notes (Optional)

The notes for the Property Report in Cloud CMA. Default is nothing. Consumer never sees this.

Request a Property Report for email delivery

get
https://tomferry.cloudcma.com/properties/widget?api_key=your-api-key&mlsnum=123456&email_to=example@example.com
post
curl -d "api_key=your-api-key&mlsnum=123456&email_to=example@example.com" https://tomferry.cloudcma.com/properties/widget

Request a Property Report for email delivery

get
https://tomferry.cloudcma.com/properties/widget?api_key=your-api-key&mlsnum=123456&email_to=example@example.com
post
curl -d "api_key=your-api-key&mlsnum=123456&email_to=example@example.com" https://tomferry.cloudcma.com/properties/widget

Notes:

Either the mlsnum or the address param must exist and reference a property that is available on the MLS.

The api_key param must represent a valid, registered user of Cloud CMA. Users can obtain their unique key by choosing the Settings link, then API in Cloud CMA.

Request a Property Report with a callback

Consumer has requested a property report for the property they are currently viewing be created, but you want to handle the delivery of the final email. You may also want to write to a CRM system, track deliverability of the email, verify the output of the PDF report before delivery, or just have more control of the process in general. We will also never see the consumers email address with this method, so it's better if you need to ensure the consumers privacy.

Method:

Just do a very simple GET from a link or a POST from a form to our RESTful API.

The process breaks down to these steps:

  1. Consumer clicks on a call to action button for "Free Property Report" on a brokers web site.
  2. Consumer gets marketing information about the Property Report and is asked for their e-mail address.
  3. The url of the property detail report on this brokers web site, the brokers Cloud CMA id, the callback url, a unique job id, and other optional parameters are sent to Cloud CMA.
  4. Cloud CMA gathers the all the data, publishes the report, and POSTs the PDF information back to the calling party.
  5. The calling party knows the job_id and can use that to lookup the consumers email address, does whatever CRM entries or logging they need, and delivers the report url themselves.

Parameters

api_key (Required)

The Cloud CMA API key for the user. Users can find their API key in the app by choosing Settings and API.

email_to (Required)

The email address of the consumer where the final report will be delivered.

mlsnum (Required)

The MLS number of the subject property.

address (Required)

The address of the subject property. Address is less accurate than MLS number due to the mis-typing of some addresses in the MLS.

email_subject (Options)

The subject line for the email. Default is "Your Cloud CMA Property Report".

email_msg (Options)

Message to include in the body of the email. Default is no message, just the url of the PDF report.

theme (Options)

The theme to use when creating the report. Default is the last theme the broker used when creating a Cloud CMA Property Report.

title (Options)

The title of the Property Report in Cloud CMA. Default is the email_to param. Consumer sees this on the cover page of the report under "Prepared for".

notes (Options)

The notes for the Property Report in Cloud CMA. Default is nothing. Consumer never sees this.

Request a Property Report with a callback

get
https://tomferry.cloudcma.com/properties/widget?api_key=your-api-key&mlsnum=123456&callback_url=your-callback-url&job_id=12345
post
curl -d "api_key=your-api-key&mlsnum=123456&callback_url=your-callback-url&job_id=12345" https://tomferry.cloudcma.com/properties/widget

Notes:

Either the mlsnum or the address param must exist and reference a property that is available on the MLS.

The api_key param must represent a valid, registered user of Cloud CMA. Users can obtain their unique key by choosing the Settings link, then API in Cloud CMA.

The callback_url param will be used to POST information to when the report is complete. The two params passed in the POST will be job_id and pdf_url. You can then take that information, make whatever entries in your CRM need to be made, and deliver an e-mail to the consumer yourself.

Homebeat Widgets

Create and deliver new Homebeats. These functions require an API key from a current Cloud CMA user. You can find that by logging into Cloud CMA, then choosing the users avatar in the upper right corner, 'Account Settings', and 'Integrations'. Copy the string under 'Your API Key'.

Homebeat Widget Metadata

Before creating a new Homebeat, it's helpful to know if the user has the Homebeat add-on and what property types are available in this users MLS system.

Get metadata

get
https://tomferry.cloudcma.com/homebeats/widget?api_key=your-api-key

Set the Accept header to application/json and you'll get back a response body that looks something like this:

{
  "user": {
    "id": 1,
    "api_key": "06a9edb52479118ee5db0f8e4830989e"
  },
  "mls": {
    "code": "crmls_crib",
    "title": "California Regional MLS/CRISNet",
    "prop_types": [
      "Business Opportunity",
      "Commercial Lease",
      "Commercial Sale",
      "Land",
      "Manufactured In Park",
      "Residential",
      "Residential Income",
      "Residential Lease"
    ],
    "default_prop_type": "Residential"
  },
  "homebeat": {
    "has_feature": true,
    "frequencies": ["monthly", "quarterly", "semi-annually", "annually", "never"]
  }
}

The most important item to dig out is the has_feature attribute under homebeat. Not all Cloud CMA users have the Homebeat feature turned on - it is an add-on feature that is not available in all MLSs. Attempting to create a Homebeat for a user that does not have the feature will always fail.

The next important items to dig out are the prop_types and the default_prop_type attributes under mls. These values can be different for every MLS and thus every user.

You may also be interested in the frequencies attribute under homebeat. These are the current frequencies we support for sending Homebeat updates to clients. These are not different for every user and we do not expect them to change very often.

Any errors in this request will return a 4xx http status code and JSON with an error message in an error attribute.

Error Example

{
  "error": "User with api_key 'foo' not found."
}

Common errors:

  • "User with api_key not found." because of an invalid api_key param.

Create a new Homebeat

post
https://tomferry.cloudcma.com/homebeats/widget

Set both your Accept and ContentType headers to application/json and include JSON in your request body that looks like this:

{
  "automation": {
    "api_key": "your-api-key",
    "frequency": "monthly",
    "welcome_email": "true",
    "report": {
      "prop_type": "Residential",
      "callback_url": null
    },
    "subject_property": {
      "address": "123 Main St, Huntington Beach, CA 92648",
      "geo_lat": null,
      "geo_lon": null,
      "sqft": "2000",
      "beds": "3",
      "baths": "3",
      "garages": "2",
      "lot_size": null,
      "taxes": null
    },
    "lead": {
      "name": "Joe Smith",
      "email_address": "joe@example.com",
      "phone": "855-977-8834"
    }
  }
}

Parameters

api_key (Required)

The users Cloud CMA api key.

frequency (Required)

How often the lead is updated with a new Homebeat. List of valid frequency values can be found in the metadata above.

welcome_email (Optional)

By default, a welcome email is sent to the lead as a form of double opt-in email best practice. Set this to 'false' if you want us to skip the sending of the welcome email because you are sending your own. Default is 'true' if you leave this attribute out.

prop_type (Optional)

The property type of the subject property, used to restrict the search for comparables to ensure similarity to the subject property. If not defined, we'll use the default property type for this users MLS.

callback_url (Optional)

A unique url on your server that acts as a webhook where we can send Homebeat updates at the defined frequency. This is most useful in two ways:

  • If you want to be notified every time we send a Homebeat update to the lead, provide a callback_url and a lead email. According to the defined frequency, we'll send the email to the lead and POST information to your callback_url.
  • If you want to send updates to the leads instead of us, leave the leads email blank and provide a callback_url for us to notify you. According to the defined frequency, we will not email the lead, but we will POST information to your callback_url and you can take the desired action.

address (Optional)

The subject property address.

geo_lat (Optional)

The subject property latitude. If not defined, we'll geo-code the subject property address.

geo_lon (Optional)

The subject property longitude. If not defined, we'll geo-code the subject property address.

sqft (Optional)

Square feet of the subject property, which helps find accurate comparables and appears in the Homebeat as a comparable feature. If not defined, we will try to establish this based on tax parcel data.

beds (Optional)

Number of bedrooms in the subject property, which helps find accurate comparables and appears in the Homebeat as a comparable feature. If not defined, we will try to establish this based on tax parcel data.

baths (Optional)

Number of bathrooms in the subject property, which helps find accurate comparables and appears in the Homebeat as a comparable feature. If not defined, we will try to establish this based on tax parcel data.

garages (Optional)

Number of garage spaces in the subject property, which appears in the Homebeat report as a comparable feature. If not defined, we will try to establish this based on tax parcel data.

lot_size (Optional)

Lot size in square feet of the subject property, which appears in the Homebeat report as a comparable feature. If not defined, we will try to establish this based on tax parcel data.

taxes (Optional)

Yearly tax amount of the subject property, which appears in the Homebeat report as a comparable feature. If not defined, we will try to establish this based on tax parcel data.

name (Optional)

The leads full name. Appears on the Homebeat and in update emails.

email_address (Optional)

The leads email address. If defined, we will use this to send Homebeat welcome email and Homebeat updates based on the defined frequency.

phone (Optional)

The leads phone number.

This API call mimics what happens when a user creates a new Homebeat in the Cloud CMA UI. The parameters above match the fields in our new Homebeat form. Upon the creation of a new Homebeat, we will send a welcome email, followed immediately by the first Homebeat update, to the leads email address if that was provided.

Any errors in this request will return a 4xx http status code and JSON with an error message in an error attribute.

Error Example

{
  "error": "No matching listings were found on the MLS."
}

Common errors:

  • "You need to sign in or sign up before continuing." because api_key param is missing.
  • "This user does not have the Homebeat feature." because this user does not have the Homebeat add-on.
  • "No matching listings were found on the MLS." happens when you provide a subject property address that is outside the current MLSs operating boundary. Example the user is part of an MLS in California, but the subject property address is in Florida.
  • "Frequency is not a valid option." because of a bad value for the frequency attribute.

Homebeat Report

You can download a report of all your Homebeats, along with current view counts, in either CSV or JSON format.

Get report

get
https://tomferry.cloudcma.com/homebeats/report?api_key=your-api-key

Set the Accept header to application/csvor application/json and you'll get back a response body that contains data about all created Homebeats in the requested format. Alternatively, you can make your get request to reports.csv or reports.json to force the format returned.

If the api_key param is not included, you'll get data back for the currently logged in user.

MLS Security Methods

Cloud CMA allows real estate agents to easily create custom CMA, Buyer Tour, and Property Reports. It utilizes the best sources of property, school, neighborhood, and other information it can find on the internet to create these reports. The best source of listing data is the MLS, so it interfaces with the MLSs RETS server to acquire listing data for sold, pending, expired, and active properties.

We handle MLS data aggregation in two ways:

Ad hoc queries

Using this method we query the MLSs RETS server only at the time the user requests a report to be created. Users are typically only requesting 10-30 listings per CMA or Buyer Tour, and only one listing per Property Report, so these queries are very small and efficient.

Traditional data duplication

We aggregate a subset of the MLS database and synchronize the listing data at set intervals.

Since MLS listing data can only be accessed by licensed members of the MLS, Cloud CMA utilizes one of the following three security methods to ensure that only valid, active members have access.

Method 1

When a new user sets up their profile in Cloud CMA, they are asked to choose their MLS, then they are prompted for their MLS credentials. The MLS password is stored in our system using RSA public key encryption, and any time it's transmitted, it is done so in that encrypted form. Whenever the user performs a query for property data, we use their MLS credentials to log into the RETS server. If the users MLS credentials are invalid, the login to the RETS server will fail, and the corresponding error message will be relayed to the user. The user can then check their credentials and try again, but they will never successfully get listing data from the RETS server without the proper credentials.

Pro:

The MLS has complete control over this user being able to utilize MLS data in Cloud CMA, and the user can be cut off at any time using the normal deactivation process built into the MLS workflow.

Con:

The MLS may not have RETS credentials set up for each and every member. Many MLSs manually set up RETS credentials on an as needed basis, so each member may not already have RETS access.

Method 2

The MLS provides us (W+R Studios) with specific RETS credentials and instructs us to use those every time we query the RETS server for all of our users. When a new user sets up their profile in Cloud CMA, they are still asked to choose their MLS, then they are prompted for their MLS credentials. The MLS credentials are stored in our system using RSA public key encryption, and any time it's transmitted, it is done so in that encrypted form. Whenever the user performs a query for property data, we use our MLS credentials to log into the RETS server. Upon successful login, we query the Agent or User table of the RETS server with the agents id and password, then look at the resulting data to make sure this user exists and is an active member. If our query returns no results or an indication that the member is no longer active, the corresponding error message will be relayed to the user. The user can then check their credentials and try again, but they will never successfully get listing data from the RETS server without the proper credentials.

Pro:

The MLS has complete control over this user being able to utilize MLS data in Cloud CMA, and the user can be cut off at any time using the normal deactivation process built into the MLS workflow.

Con:

The MLS may not allow querying on the password field in the Agent table, or may not return that field in the dataset for use in a post query comparison. As a less secure alternative, it's possible to query the Agent table for the id and an indication that this user is an active member, essentially ignoring the password.

Method 3

We offer two 'Single Sign On' methods, which are especially good for MLSs that have a site license where every member has free access to Cloud CMA. In this scenario, users cannot log in directly at cloudcma.com, but instead must first log into their MLS system and click on a button or link to access Cloud CMA.

We have our own 'homebrew' form of SSO where parameters are passed in the url - the MLS code, the users id, a secure hash, and a timestamp. Details of this algorithm can be provided on request. We have several MLSs using this method, it works well, and it's simple to implement.

We also support the SAML standard for SSO and are currently SAML certified with one of the major MLS vendors. We are set up to easily add other SAML providers.

SSO works especially well when the MLS implements the API for passing listing numbers to automatically create reports for listings the user has currently selected. This allows for a deep integration between MLS system and Cloud CMA, requiring no additional login by the user and making it seem like one seamless system.

Pro:

The MLS has complete control over this user not only being able to utilize MLS data in Cloud CMA, but even having rights to access Cloud CMA at all. The user can be cut off at any time using the normal deactivation process built into the MLS workflow - if they can't access the MLS system, they can't access Cloud CMA.

Con:

The MLS needs to set up the link to Cloud CMA within the MLS system.

Method 4

When a new user sets up their profile in Cloud CMA, they are still asked to choose their MLS, then they are prompted for their MLS credentials. The MLS credentials are stored in our system using RSA public key encryption, and any time it's transmitted, it is done so in that encrypted form. Whenever the user performs a query for property data, we verify their credentials against our synchronized table of currently active agents to ensure they are an active member. If our query returns no results or an indication that the member is no longer active, the corresponding error message will be relayed to the user. The user can then check their credentials and try again, but they will never successfully get listing data from us without the proper credentials.

Pro:

The MLS has complete control over this user being able to utilize MLS data in Cloud CMA, and the user can be cut off at any time using the normal deactivation process built into the MLS workflow.

Cloud CMA RETS Queries

Cloud CMA allows agents to create CMA, Buyer Tour, and Property reports. We DO NOT download the entire MLS and keep it synced in servers on our site. The agents enter criteria and we do real-time RETS searches to download data from the MLS at that moment in time.

We basically do three types of searches in Cloud CMA:

  1. Mls nums search - single or multiple mls nums at a time. Very straightforward, simple search.
  2. Address search - usually we have to break an address down into street num, street name, city, state, zip and do the search. Also very straightforward.
  3. Lat/Lon range search - basically a Latitude range and a Longitude range forming a rectangular proximity search area around a given subject property. This is a more complex query, and I've seen it trip up RETS servers in two ways:
    • The latitude and longitude fields on some servers are not indexed, even though these are simple decimal values and are very useful search fields.
    • Because the longitude in the US is a negative number, to search a range you end up with this funky double negative DMQL syntax that looks like this:

      (LONGITUDE=-92.590--92.588),(LATITUDE=44.866-44.868)

      That can break the parser on some RETS servers. We have come up with a fairly simple way around this on RETS servers in the past. Assuming that the RETS parser is simply querying a View in your database, create a new field called "ABSLONGITUDE" in your View which contains the absolute value of the longitude. On our side, we just set a flag to query that new field instead and the query above becomes:

      (ABSLONGITUDE=92.588-92.590),(LATITUDE=44.866-44.868)

      That works for us and is typically pretty easy to implement on the server side.

This method of real-time searches is more secure, since we do not have all the MLS data replicated on our servers, and provides less load on the RETS server, since we are only searching an extremely small subset of the MLS daily.