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

Examples

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: 'https://cloudcma.com/cmas/12345/edit',
  pdf_url: 'https://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

Create and deliver a Quick CMA

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

Request a Property Report for email delivery

Request a Property Report for email delivery

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

Request a Property Report with a callback

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

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

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: null,
      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

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

Set the Accept header to text/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.

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.

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.

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.

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.