Cloud CMA Developers Page

Topics:

Cloud CMA API

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.

Create a new report

Use case:

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 to our RESTful API from a text or image link.

Parameter notes:

mlsnums - 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.

Create a new CMA
http://cloudcma.com/cmas/new?mlsnums=12345,12346,12347&title=The+Smith+Family&notes=Initiated+from+your+MLS
http://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
Examples - text and image links: Create CMA
Create a new Buyer Tour
http://cloudcma.com/tours/new?mlsnums=12345,12346,12347&title=The+Smith+Family&notes=Initiated+from+your+MLS
Examples - text and image links: Create Buyer Tour
Create a new Property Report
http://cloudcma.com/properties/new?mlsnums=12345&title=The+Smith+Family&notes=Initiated+from+your+MLS
http://cloudcma.com/properties/new?address=123+Main+Street,+Costa+Mesa,+CA+92626&title=The+Smith+Family&notes=Initiated+from+your+MLS
Examples - text and image links: Create Property Report
Create a new Flyer
http://cloudcma.com/flyers/new?mlsnums=12345&title=The+Smith+Family&notes=Initiated+from+your+MLS
http://cloudcma.com/flyers/new?address=123+Main+Street,+Costa+Mesa,+CA+92626&title=The+Smith+Family&notes=Initiated+from+your+MLS
Examples - text and image links: Create Property Report

Create and deliver a Quick CMA

Use case:

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.

Parameter notes:

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

email_to - Consumer email address where the report will be delivered.

address - Consumers subject property address.

title - (Optional) Title for report. If not present, will use the consumers name or email address.

name - (Optional) Consumers full name which will appear in the notes of the CMA.

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.

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 as you wish.

Create and deliver a Quick CMA
http://cloudcma.com/cmas/widget?api_key=xxxx&name=Joe+Buyer&email_to=joe_buyer@example.com&address=123+Main+St,+Huntington+Beach,+CA+92648

Questions or suggestions?

E-mail questions to dan at cloudcma dot com



Cloud CMA and MLS Security

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 do not aggregate listing data ahead of time and keep a duplicate copy of MLS data on our servers. We feel that this model is a waste of resources, creates synchronization issues, and is a security risk. For these reasons, 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.

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 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 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.


Questions or suggestions?

E-mail questions to dan at cloudcma dot com



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:

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.


Questions or suggestions?

E-mail questions to dan at cloudcma dot com



Cloud CMA Broker Web Site Widgets

Cloud CMA creates custom 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. The listing data used for the reports is gathered from the brokers web site itself - not the MLS - using Dwellicious.

Request a Property Report for email delivery

Use case:

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.

Parameter notes:

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 - The MLS number of the subject property.

address - 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:
http://cloudcma.com/properties/widget?api_key=xxxx&mlsnum=123456&email_to=danwoolley@gmail.com
POST:
curl -d "api_key=xxxx&mlsnum=123456&email_to=danwoolley@gmail.com" http://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

Use case:

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.

Parameter notes:

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 - The MLS number of the subject property.

address - 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 with a callback
GET:
http://cloudcma.com/properties/widget?api_key=xxxx&mlsnum=123456&callback_url=<your_callback_url>&job_id=12345
POST:
curl -d "api_key=xxxx&mlsnum=123456&callback_url=<your_callback_url>&job_id=12345" http://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.


Questions or suggestions?

E-mail questions to dan@cloudcma.com.