Developer Documentation
Platform Overview
Authentication
API Services
Overview Accounts Accounts: Associations Accounts: Metadata Accounts: Profile Appstore: Users Broker Distributions Broker Tours Consumers Consumers: Linked Agents Contacts Contacts: Activity Contacts: Export Contacts: Tags Contacts: Portal Accounts Developers: Identities Developers: Keys Developers: Authorizations Developers: Billing Summary Developers: Change History Developers: Domains Developers: News Feed Webhooks Developers: Roles Developers: Syndications Developers: Templates Developers: Usage Detail Developers: Usage Summary Devices Flexmls: Email Links Flexmls: Listing Meta Origins Flexmls: Listing Meta Translations Flexmls: Listing Meta Field List Translations Flexmls: Listing Reports Flexmls: Mapping Layers Flexmls: Mapping Shapegen IDX IDX Links Listing Carts Listing Carts: Portal/VOW Carts Incomplete Listings Incomplete Listings: Documents Incomplete Listings: Documents Metadata Incomplete Listings: Document Uploads Incomplete Listings: Floor Plans Incomplete Listings: FloPlans Incomplete Listings: Photos Incomplete Listings: Photos Metadata Incomplete Listings: Photo Uploads Incomplete Listings: Rooms Incomplete Listings: Tickets Incomplete Listings: Units Incomplete Listings: Videos Incomplete Listings: Videos Metadata Incomplete Listings: Virtual Tours Incomplete Listings: Virtual Tours Metadata Listings Listings: Clusters Listings: Documents Listings: Documents Metadata Listings: Floor Plans Listings: FloPlans Listings: Historical Listings: History Listings: Notes Listings: Search Parameters Listings: Open Houses Listings: Photos Listings: Photos Metadata Listings: Photo Uploads Listings: Document Uploads Listings: Rental Calendar Listings: Rooms Listings: Rules Listings: Tour of Homes Listings: Tickets Listings: Units Listings: Validation Listings: Videos Listings: Videos Metadata Listings: Virtual Tours Listings: Virtual Tours Metadata Listing Meta: Custom Fields Listing Meta: Custom Field Groups Listing Meta: Field Order Listing Meta: Field Relations Listing Meta: Property Types Listing Meta: Rooms Listing Meta: Standard Fields Listing Meta: Units Registered Listings Market Statistics News Feed News Feed: Curation News Feed: Events News Feed: Metadata News Feed: Restrictions News Feed: Schedule News Feed: Settings News Feed: Templates Open Houses Overlays Overlays: Shapes Portals Preferences Saved Searches Saved Searches: Provided Saved Searches: Restrictions Saved Searches: Tags Search Templates: Quick Searches Search Templates: Views Search Templates: Sorts Shared Links System Info System Info: Languages System Info: Search Templates
Supporting Documentation
Examples
RESO Web API
RETS
FloPlan
Terms of Use

Example RETS Session

Access to the various parts of a RETS server is handled using HTTP requests to different URLs. The server's responses to those requests are delivered back in the standardized format described in the RETS specification (available at www.rets.org).

Note: There are several free and open source tools that are available that handle the technical aspects of issuing requests and reading responses to and from a RETS server, so many of the more specific details mentioned here are handled automatically behind-the-scenes within most of those tools.

 

Terminology

Class – Best thought of as a sub category. Examples: The "Property" Resource may have Classes such as "A" for Residential, "B" for Lots and Land, "C" for Residential Rentals, etc. while the "Agent" Resource may have a class such as "Agent". Each Class represents a different fieldset, allowing (for example) Residential to include fields that Land may not need.

Lookup – When a specific field is described as having Lookup values, the content of that field can only contain a pre-determined set of values. To learn what those values are and what they stand for, a request can be made that returns a list of all possible values within that field. An example would be the Listing Status field to learn that the possible values are Active, Pending, Expired, Cancelled, Deleted, etc.

COMPACT – This is one format responses can be returned as (you'll see it used often in the examples below). The contents of these responses are returned back in a tab delimited format. COMPACT-DECODED is a very similar format except that fields containing Lookup values have their codes replaced with their human-readable meanings.

For a full glossary of commonly used terms related to RETS, see www.rets.org/glossary.

 

Example Session

Below is a sample session which can be run through your web browser to make understanding what's available easier. Viewing the page's source code (from your browser's 'View' menu) will show all characters from the returned response which often times makes more sense than what's displayed to you visually.

  1. Successfully login
  2. Discover what Resources are available on the server
  3. Discover specific Classes for each Resource
  4. Retrieve detailed field definitions for each of those Classes
  5. Learn all possible values for the Listing Status field
  6. Perform a query to retrieve all Residential properties where the Listing Status field shows as Active
  7. Retrieve the main photo for a returned property
  8. Retrieve all photos for a returned property
  9. Logout
 

(1) Successfully login:

http://retsgw.flexmls.com/rets2_3/Login

You'll be prompted for your username and password. The RETS login URL, username and password were initially provided to you by the MLS. A successful login will establish a cookie which is used to keep your session alive between requests.

(2) Discover Resources available:

http://retsgw.flexmls.com/rets2_3/GetMetadata?Type=METADATA-RESOURCE&ID=0&Format=COMPACT

The response from this RETS request contains information about all of the Resources available on the RETS server. Note the KeyField for the "Property" Resource (assuming "LIST_1" for the rest of these examples).

 

(3) Discover specific Classes available:

http://retsgw.flexmls.com/rets2_3/GetMetadata?Type=METADATA-CLASS&ID=Property&Format=COMPACT

The response contains DATA lines for each Class within the "Property" Resource (see the ID= parameter in the URL). Any future request we're interested in for Residential properties will need to be done using Residential's SystemName (assuming "A").

(4) Retrieve detailed field information:

http://retsgw.flexmls.com/rets2_3/GetMetadata?Type=METADATA-TABLE&ID=Property:A&Format=COMPACT

The response will contain many DATA entries. Each of those entries represents a single field available in that Class. Columns such as DataType and MaximumLength provide details about the specific type of data you can expect to receive in that field. Find the field that represents the Listing Status (assuming "LIST_15"). The "Interpretation" column should indicate that this is a 'Lookup'. Note the LookupName for that field (assuming "20070913202543158090000000").

 

(5) Learn all possible values for Listing Status:

http://retsgw.flexmls.com/rets2_3/GetMetadata?Type=METADATA-LOOKUP_TYPE&ID=Property:20070913202543158090000000&Format=COMPACT

The response will contain multiple DATA entries, each representing a possible value within the LIST_15 field. Since we're interested in Active listings, note the contents of that row's Value column (assuming "OV61GOJ13C0"). This value is used in the query.

 

(6) Perform a query:

http://retsgw.flexmls.com/rets2_3/Search?SearchType=Property&Class=A&QueryType=DMQL2&Query=%28LIST_15=%7COV61GOJ13C0%29&Count=0&Format=COMPACT-DECODED&StandardNames=0&RestrictedIndicator=****&Limit=50

The response will contain the records you requested (limited to 50 due to the Limit argument given at the end). The COLUMNS line indicates the field names of the records returned and all DATA rows represent the records with field values in the same order as shown by the COLUMN row. If you're only interested in receiving certain fields back, you can add a "&Select=" parameter to the end of the URL. For example, if you only want to retrieve back the KeyName field (noted as "LIST_1") and the Listing Status field (noted as "LIST_15"), add "&Select=LIST_1,LIST_15" to the end of that URL. Note a few 'LIST_1' values for the next example.

 

(7) Retrieve the main photo:

http://retsgw.flexmls.com/rets2_3/GetObject?Type=Photo&Resource=Property&ID=20080112084722814782000000:0

The ID value in this URL is made up of the value of the KeyField ("LIST_1") associated with your desired record, followed by a colon, followed by a zero (note: the KeyField cannot be assumed to be the MLS# for the property). The final "0" indicates that you'd like the main property photo. The response will contain one of 2 things. If the main photo does not exist, the response will be in XML format as a RETS error. If the main photo does exist, the raw photo data will be returned back (which your web browser should display as the actual photo to you).

 

(8) Retrieve multiple photos:

http://retsgw.flexmls.com/rets2_3/GetObject?Type=Photo&Resource=Property&ID=20080112084722814782000000:*

This is the same request as the single photo, except that instead of requesting a specific photo for the property (such as "2" for the second photo in the order displayed in the MLS), it's replaced with an * (asterisk). This instructs the RETS server to return all available photos for the given record. This response comes back in a multi-part (MIME) format which allows photo data from multiple images to be returned in a single response. These types of responses aren't usually handled well automatically by a web browser but are very easy for tools that are built to expect them. Those tools generally read the multiple images in the single response and save them in separate image files to be used later.

 

(9) Logout:

http://retsgw.flexmls.com/rets2_3/Logout