Retsly API Documentation

The Retsly Platform

The Retsly platform is middleware that helps you access multiple MLS listing datasets and real estate public records. The data is all delivered in a normalized way through an elegant and familiar RESTful API. Retsly also facilitates managing the necessary data licenses for you and data providers with a standardized approval process. At Retsly we're hoping to spur innovation in real estate, by helping developers build the tools for realtors, brokerages, MLSs and consumers that will revolutionize the industry!

By enabling simpler access to an array of datasets in a consistent format, you are ready to scale. Integrate with API once, and as soon as data licenses are approved, they are instantly available. To help push your product further, we provide a variety of integrated services, including a Push API, secure OAuth user authentication and comprehensive analytics.

Signing up with Retsly

Retsly is currently live, but by invite only. To request an invite or if you have any specific questions, contact us through our support channel.


There are several support channels available if you want to contact us:

The Retsly Dashboard

We've endeavored to make the process of applying for and managing data licenses as straightforward as possible, for both developers and data providers. To this end, we've designed a simple workflow made up of three steps:

  • Register your application to get API access tokens.
  • Complete your application's profile and submit it for a quick review with Retsly.
  • Apply for access to datasets.

Registering an application

The Retsly platform is primarily intended for agent-facing and IDX applications. Retsly supports developers that create applications for MLSs, brokers, and agents. If you can provide a beneficial service to these user groups in the real estate industry, your application is a good candidate for license approval.

Immediately after creating your account and registering an application, you will receive your Client ID, Client Secret, Browser and Server tokens. These will all be used in integrating your application with the API. Additionally:

  • You can start integrating with the Retsly test datasets.
  • You can integrate user authentication on multiple platforms, using the Retsly Secure Sign-in OAuth flow.
  • You can begin using Retsly dashboard to track API usage and data analytics.
  • You can set up webhooks to test push functionality using our dynamic test datasets.


Authorization tokens will only work on the HTTP refferer domains you have specified for your application. These domains are required when initially registering the application, and can be updated on the settings page. You may specify multiple domains, but no wildcards.

Authorization Tokens

Your Client ID is your application's unique identifier. Your Client Secret is an additional token used for authenticating your application and should only be used in server to server exchanges. Browser and Server tokens are used to identify and authorize your application to get data using the Retsly API. Generally you would use the Server token for most exchanges.

Testing if your application works

The easiest way to check if you application has been correctly registered is to use our API Explorer. Simply copy your Browser token, open the API Explorer for any MLS listing data resource, and paste the token into the access_token parameter. As long as the datasetID parameter is one of the Test datasets, you should receive a Successful (200) response.

Alternatively, use this simple cURL request, using your application's Server token:


Configuring OAuth

If you intend on using our authentication flow, you will need to specify the callback URI. The callback URI should match the HTTP referrer domain. Read more about integrating oAuth below.

Regenerating your Client Secret

You're able to regenerate your Client Secret at any time. It's important to note that the Client Secret is used in the generation of both Server and Browser tokens, and when regenerating you are effectively expiring all tokens that were generated off that Client Secret. It may be useful to regenerate your Client Secret if your Client Secret or any of the subsequent tokens have been compromised.

Data Licenses

The datasets are accessed with the datasets resource on the API, each corresponding to a data provider (such as an MLS).

Pre-approved Test datasets

As soon as your application has been registered, you are able to access our Test datasets. Sample data has no correlation to real MLS data. The machine-generated test data represents available datasets to allow you to develop a proof of concept that shows how your application will integrate with real data providers. It is recommended that you integrate your application using these datasets before applying for data licenses.

  • Static MLS test dataset: This simulates the listing data you would receive from an MLS. This simple dataset will not update. The dataset ID is test. This is the default on the API Explorer.
  • Dynamic test datasets: There are two dynamic test datasets available. These also simulate MLS listing data, but the data is updated every 15 minutes to mimic the regular data updates you'd commonly see on an actual MLS dataset (e.g. listing status, price updates, photo updates, etc). The dataset IDs are test_sf and test_sd.
  • Public Records test data: A small sample of the Public Records data is available to test integration with the Public Data dataset provider. The Public Data resources are accessible using the two dynamic test datasets: test_sf/parcels, test_sf/assessments, test_sf/transactions and test_sd/parcels, test_sd/assessments, test_sd/transactions.

Licensed datasets

All other datasets besides Test datasets require approval from their respective providers. Access to the data remains at the discretion of the data provider. The time it takes each data provider to review and approve your application for a data license will vary, as will the specific usage requirements. The data provider has the right to flag your application for compliance review, and revoke your license if there is a breach of usage regulations. The available data providers are updated as they come onto the Retsly platform.

Completing your application's profile

Your application's profile is used by the MLSs and other data providers to approve you for data access. Is is extremely important that the profile is fleshed out as much as possible to facilitate a positive outcome. Previously, a developer would have needed to go through many different application procedures to get access to various datasets. On the Retsly platform, you're able to apply for multiple data providers with the same one. You are able to update the profile at any time.

The information required includes information such as a complete application description, website URL, support information, and screenshots. The icon is used only within the Retsly platform. Adding a link to a working demo would be beneficial.

The license questionnaire is important as it will be used by the data providers to decide if your application will make suitable use of their data. Fill out these answers with as much detail as possible.

Retsly application review

Prior to applying for datasets, we request that you first get it quickly reviewed by us. This only needs to be done once. This quick once-over by our team helps both parties: it ensures that the data providers are not getting spammed with unsuitable applications, and that developers don't waste valuable time sending license requests that are doomed to fail because of recognizable errors or ommissions. These reviews are done during business hours, PST.

Managing data licenses

Once your application has been successfully reviewed, you can begin applying for data access. Simply go into your application's settings, choose the dataset you'd like access to, and click apply. Your application profile will then be sent to the relevant data provider for approval. If you want to withdraw your application, you can recall it at any time.

Should you choose to remove an application's data license once it's been approved, please note you will need to begin the application process again.

The following statuses are applied to your data license:

  • Pending: Your application has been submitted to the data provider, and is pending approval.
  • Approved: Your application has been approved by the data provider, and the data is available through the Retsly API.
  • Denied: Your application has been denied for a data license. A reason will be supplied when you are notified of this status change. You may apply again if desired.
  • Under compliance review: Your application has been flagged for compliance review. The data feed is still active.
  • Revoked: Your compliance review and resolution was not successful, and the data provider has revoked your access to their data. The data feed for this resource is no longer available. You will need to reapply to regain access.

Data provider feedback

During and after the license approval process, communication between yourself, Retsly and the data providers can be managed using the integrated feedback widget.

Compliance review

An application's access to a dataset may be flagged for compliance review by either Retsly or the data provider. This will likely be the result of a breach in usage regulations. While under compliance review you will still have access to the data feed. An engineer from Retsly will attempt to contact you to resolve the issue.

Permission scopes

Individual datasets may have associated scopes. For example, an MLS data provider may grant your application access to only 'Active listings', but not 'Off-market listings'. Each dataset has it's own scopes, set by the data provider.

The permission level your application has is determined by the data provider at the time of approval, and can be amended later. If you have specific requirements for the level of access, be sure to request it when requesting the data license. The scope permissions are surfaced in the API datasets endpoint, and on your application's Settings page.

The data provider may also require that your end-users must be authenticated against their Agent roster. If this specific scope is set, your application will need to make use of the Retsly Secure Sign-In OAuth service. Permissions for each datasets' scopes would then be approved by the end-user.


One of the strengths of the Retsly platform is our analytics. You can view aggregate data from all your applications, as well as data analytics for individual applications.

Any time an application makes a request to the Retsly API through an application token or a user token, Retsly tracks the requested data and stores the information.

During application development, you can view the data analytics for your application using the sample Test data we have provided. Once you have received approval for your application to access and interact with data providers, and your application begins to receive traffic from users, you can view analytics for live data. Additionally, we will soon be releasing analytic data through the API, to you to develop your own applications using your analytic data.

Examples of use cases for data analytics:

  • MLSs can oversee compliance by viewing how applications use the Retsly API.
  • MLSs can track how people search for data in the MLS and gain a competitive advantage through making data more accessible.
  • Developers can create new types of applications for agents based on their leads' search activity. For example, based on the types of search traffic (such as types of homes, regions the user is looking in, average price, or square footage) the developer can deliver customized information about a lead's preferences to an agent.
  • Brokerages can use search data to compare demand with supply, to assist in long-range planning such as office space and number of agents on staff.

The Retsly API

Our API is the portal through which you access normalized data. You can integrate your application with our RESTful API using HTTPS requests or with the help of the opensource SDKs. HTTPS is required; Retsly only responds to encrypted traffic so that the data remains safe.

Exploring the API

API status

Our system status is available here.

API Explorer

Our API Explorer is the simplest way to query the API. Using your application's Browser token, you can get a response from any of the Test datasets, as well as any datasets that have been approved for that application. Paste in your token, enter the desired dataset ID as the datasetID and build your query.

By default, the static Test dataset is used in the API Explorer (and in the examples in this documentation).


Another great way to quickly use the API is using Postman. We have a schema available for import here.

Querying the API

For a complete list of available resources and parameters, please see the Retsly API Reference. Results are limited to 10 by default.


Every request to the Retsly API must supply a valid API token. You can get an API token through the OAuth flow, or in the Retsly Dashboard.

Your application should send an Authorization header with every HTTP request to the API:

Authorization: Bearer {token}

If you can't set headers (such as in an XHR request from a browser), or at your option, you can send the token in the access_token parameter in the query string of your request:



You can constrain the result set of a resource by passing additional operators with your request. The format is as follows:

{parameter}[{operator}] = {value}

Alternatively, dot notation is also available if preferred:

{parameter}.{operator} = {value}

Valid operators include:

eq equal
ne not equal
gt greater than
lt less than
gte greater than or equal
lte less than or equal
in comma-separated list, equal only

If the operator is omitted, the eq operator is assumed.


The following query parameters may be passed to narrow down your results. Over time, more fields and aggregation options will be added and more resources will be supported. Depending on the resource, some parameters may be required or unavailable.

Note that geographic coordinates should be ordered {Lng},{Lat} and contain a decimal.

Path Parameters
access_token stringToken to identify the application. This is always required.Example request: return all datasets approved for an application RESPONSE
datasetID stringSpecifies the dataset to get the data from.Example: return all listings from the Test dataset RESPONSE
listingId stringThe listing ID, available on the /listings resource.Example: return data relating to a specific listing RESPONSE
agentId stringThe Agent ID, available on the /agents resource.Example: Return data relating to a specific agent RESPONSE
officeId stringThe office ID, available on the /offices resource.Example: Return data relating to a specific office RESPONSE
openhouseId stringThe openhouse ID, available on the /openhouses resource.Example: Return data relating to a specific openhouse RESPONSE
summary stringSummary endpoint, currently only available for MLS listings data.Example: Return summary data for the Test dataset RESPONSE
Query parameters
offset numberSkips this number of results.Example: Skip the first 10 listings of the Test dataset RESPONSE
limit numberLimits the size of the result set. Default is 10.Example: Limit results from the Test dataset to only 2 RESPONSE
sortBy stringResponse field to sort query by.Example: Sort order by price RESPONSE
order stringOrder of responses: "asc/desc".Example: Sort order by descending price RESPONSE
near stringCoord or location e.g. near={Lng},{Lat} or near=San DiegoExample: Return listings that are near specific co-ordinates,37.793662GET RESPONSE
radius stringRadius to search within. Can be suffixed with units mi(miles) or km(kilometer). Miles are default.Example: Return listings that near to specific co-ordinants, constrained 5 miles,37.793662&radius=5miGET RESPONSE
box stringIf you know the extents of a box-shaped region, you can provide the lower-left and upper-right co-ordinates "{lng1},{lat1},{lng2},{lat2}" as a string or you can provide them as an array [[{lng1},{lat1}],[{lng2},{lat2}]] box parameter.Example: Return listings within a box,37.781368,-122.415764,37.799580GET RESPONSE
poly stringIf you know the extents of a polygonal region, you can provide the each point as co-ordinates "{lng-1},{lat-1},{lng-2},{lat-2}...{lng-n},{lat-n}" as a string or you can provide them as an array [[{lgn-1},{lat-2}],[{lng-2},{lat-2}]]....,[{lng-n},{lat-n}]] poly parameter.Example: Return listings within a box-shape,37.781368,-122.415764,37.799580,-122.447092,37.796291GET RESPONSE
groupBy stringThis is only available for summary data (see the /summary parameter).Example: Return summary data for houses with a price greater than $500,000, grouped by year built RESPONSE

MLS data

These resources relate to listing data, directly from the MLS. This data is updated as often as each MLS allows. The response schema returns normalized data from all available datasets. For a full list of response fields, please see the Reference section for each resource.

Multi-MLS development

The Retsly API organizes resources within individual datasets. Should you require data from multiple MLSs, you will need to make separate calls for each dataset.

MLS data resources


Retrieve a group of datasets.

Example: Get a list of all datasets approved for an application RESPONSE

Retrieves a set of listings.

Example: Get listings in the Test dataset where price is greater than $500,000 RESPONSE

Retrieves a set of agents.

Example: Get a set of agents in the Test dataset whose name is not 'Ursula' RESPONSE

Retrieves a set of offices.

Example: Get a set of offices in the Test dataset that are located in Vermont RESPONSE

With a high query limit of 10,000 items, /maps provides a more performant and efficient query method if coordinates are all you need

Example: Get summary data for houses built in 1970 RESPONSE

Retrieves aggregate summary data for a given query.

Example: Get summary data for houses built in 1970 RESPONSE

Public Records Data

This includes property records, tax assessments, and transaction records for approximately 148,000,000 properties across 3,200 counties throughout the United States. The Public Records dataset retains the same response format and query capabilities as the MLS Data datasets. The full feed of Public Records is available using the pub dataset, which requires access approval by Retsly.


The Parcels resource includes a document for each property in our dataset, whether it's a detached home, a strata lot, a business, a bare land property, or any other kind of property. The Parcels data represents the current state of properties in the United States and doesn't contain historical data.


The Assessments resource includes present and historical property tax assessments. This includes estimated market and taxable values, tax amounts, and information about the property itself. This is updated annually.


The Transactions resource includes present and historical property transactions. Any type of change to a property's ownership is reflected in the transactions data set, including sale of new and existing properties, title transfers within families, and finance changes (such as a home loan refinance). Transaction coverage varies by county. Our data set includes historical transactions as far back as 1995, and is updated weekly.


The comparables endpoint allows you to access a list of parcels that have similar characteristics (e.g. distance, land use code, lot size, recent sales price) to the parcel specified in the query.

Data Quality

To deliver our Public Data API, we weave together data from thousands of local and regional partners. Because of this, you might notice some typographic errors, unfilled fields, and conflicting notation styles (such as for legal descriptions) from one region to another. We strive to maintain the highest standard for data quality, so if you encounter a discrepancy, please contact us and we'll do our best to help.

Property Land Use Code

land Use CodesDescription
AG Agricultural
AP Apartment Building
CD Condominium
CI Commercial & Industrial
CM Commercial
EX Exempt
GV Government
IM Improved Land
IN Industrial
MBMobile Home
MF Multi-Family Dwelling (2-4 Units)
MH Manufactured Home
MX Mixed Use
NWNew Construction
PD Planned Unit Development
RR Residential
SR Single Family Residence
UL Unimproved Land/Lot
VL Vacant Land/Lot

Document Type Code Values For Transaction

Document Type CodeDescriptionNotes
1 Administrator's Deed
2 Affidavit - Death of Tenant by Entirety
3 Affidavit - Death of Life Tenant
4 Affidavit - Death of Trustee/Successor Trustee (Los Angeles County only)
5 Affidavit - Death of Joint Tenant
6 Affidavit
7 Affidavit of Publication of Notice of Sale
8 Affidavit - Surviving Joint Tenant
9 Affidavit - Surviving Spouse
10 Affidavit - Survivorship
11 Affidavit - Transfer on Death
12 Affidavit of Trust or Trust Agreement (Los Angeles County only)
13 Agreement of Sale (Agreement for Deed)Also contains seller financing information, in addition to the transfer information.
14 Assumption Deed/Agreement
15 Assignment of Commercial Lease
16 Assignment of Certificate of Purchase
17 Assignment of Certificate of Sale
18 Assignment of Contract of Sale
19 Assignment Deed
20 Assignment of Land Contract
21 Assignment of Lease (Leasehold Sale)This is different than the "Assignment of Lease" for collateral on a loan (similar to Assignment of Rents, both of which are invalid).
22 Assignment of Sub Agreement of Sale
23 Assignment of Sub Lease
24 Assignment of Sub Commercial Lease
25 Assignment of Agreement of Sale
26 Beneficiary Deed
27 Bargain & Sale Deed
28 Condominium Deed
29 Certificate of Purchase (Public Trustee's Certificate of Purchase)
30 Certificate of Redemption
31 Certificate of Sale
32 Certificate of Title
33 Certificate of Transfer
34 Cash Sale Deed
35 Commissioner's Assignment of Lease
36 Commissioners Deed
37 Commercial Lease
38 Cancellation of Agreement of Sale
39 Cancellation of Contract of Sale
40 Cancellation of Notice of DefaultRescission of/Withdrawal of/Release of/Termination
41 Cancellation of Land Contract
42 Cancellation of Lis PendensRescission of/Withdrawal of/Release of/Termination
43 Cancellation of Notice of Sale
44 Cancellation of Notice of Sale (Trustee Sale, Sheriff Sale or Foreclosure Sale)
45 Cancellation of Trustees Deed
46 Court Order/Action
47 Confirmation Deed
48 Corporation Deed
49 Correction DeedCode only used if no other applicable document type. For example, a Correction Warranty Deed, is coded as WRDE.
50 Contract of SaleAlso contains seller financing information, in addition to the transfer information.
51 Conservator's Deed
52 Declaration
53 Deed of Distribution
54 DeedDefault code for all transfer documents, if no document type given.
55 Deed in Lieu of Foreclosure
56 Deed Under Power of Sale
57 Distress Sale
58 Estoppel Deed
59 Exchange
60 Executor's Deed/Executrixs Deed
61 Foreclosure Auction - Status Sold
62 Foreclosure Deed/Certificate
63 Fiduciary Deed
64 Guardians Deed
65 Gift Deed
66 Grant Deed
67 Ground Lease A lease where the lessee is given the right to use the land for a long period of time and is permitted to develop the land.
68 Gift Warranty Deed
69 Satisfaction of Agreement of Sale (Hawaii - Leasehold)
70 Satisfaction of Agreement of Sale (Hawaii - Fee property)
71 Individual Deed
72 Intrafamily Transfer & Dissolution
73 Interspousal Transfer Deed
74 Judgment of Foreclosure
75 Judgment
76 Joint Tenancy Deed
77 Leasehold Conversion with Agreement of Sale (Fee Purchase)
78 Leasehold Conversion with Agreement of Sale
79 Land Court (Massachusetts)
80 Land Contract
81 Lease
82 Life Estate Deed/Deed Reserving Life Estate
83 Life Estate Quitclaim Deed
84 Life Estate Warranty Deed
85 Leasehold
86 Limited Warranty Deed
87 Limited Warranty Deed with Vendors Lien
88 Mobile Home Title
89 Marshall's Deed
90 Deed of Trust/MortgageDefault code for all mortgage documents.
91 Newly Filed Complaint/Petition to Foreclose
92 Non-Warranty Deed
93 Notice of DefaultNotice of Default and Election to Sell
94 Notice of Lis Pendens
95 Notice of Sale (Trustee Sale, Sheriff Sale or Foreclosure Sale)
96 Order of Dismissal
97 Other
98 Power of Attorney to Foreclose Mortgage
99 Partial Cancellation of Notice of Default
100 Partial Cancellation of Lis Pendens
101 Personal Representative's Deed
102 Partnership Deed
103 Public Auction
104 Quitclaim Deed
105 Receiver's Deed
106 Redemption Deed
107 REO Sale (REO Out)
108 Referee's Deed
109 Re-Recorded Deed
110 Revocation of Beneficiary Deed
111 Revocation of Transfer on Death
112 Sub Agreement of Sale
113 Sub Commercial Lease
114 Sub Lease
115 Satisfaction of Agreement of Sale
116 Satisfaction of Contract of Sale
117 Satisfaction of Land Contract
118 Sheriff's Certificate of Sale
119 Sheriff's Deed
120 Sheriff's Tax Deed
121 Sale Change (Rescheduled or Postponed)
122 Sale Cancelled
123 Special Limited Warranty Deed with Vendor's Lien
124 Special Limited Warranty Deed
125 Special Joint Tenancy Warranty Deed
126 Special Masters Deed
127 Special Warranty Deed with Vendor's Lien
128 Special Warranty Deed
129 Survivorship Deed
130 Termination of Decedent's Property Interest
131 Transfer on Death Deed
132 Trustee's Deed (non-foreclosure)
133 Trustee's Deed (foreclosure sale transfer)
134 Transaction History Record
135 Treasurer's Deed
136 Tax Deed
137 Vendor's Lien Deed
138 Warranty Deed
139 Warranty Leasehold Estate Deed
140 Warranty Deed with Vendor's Lien
141 Assessor Sales History Document
142 Assumption Warranty Deed
143 Conservator's Warranty Deed
144 Gift Grant Deed
145 Gift Warranty Deed
146 Master in Equity's Deed
147 Redemption Quit Claim Deed
148 Special Referee's Deed
149 Survivorship Warranty Deed
150 Divorce Deed (Deed Pursuant to Divorce)
151 Mortgagee's Deed
152 Act of Donation (Donation)
153 Co-Op Transaction (RPTT&RET)


To help integrate with the Retsly API, various SDKs are available. They are all hosted on GitHub and are open source. If you'd like to contribute, we welcome pull-requests! Currently available SDKs:


Retsly offers support for the Real Estate Standards Organization (RESO), specifically Web API (v1.0.1) and Data Dictionary (v1.4). This facilitates integration with Retsly for developers that may already be working with the Data Dictionary Standard or valid Web API clients. For a complete reference please use the following resources:

Return a list of properties with a list price greater than $100,000$filter=ListPrice gt 100000&format=xml

Retsly Secure Sign-in OAuth Flow

Retsly uses the OAuth2 protocol for authorization. OAuth provides client applications a 'secure delegated access' to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.

In some cases, MLSs may require that your application authenticates your user as an active member of that organization. The Retsly Secure Sign-In OAuth flow is designed to facilitate authenticating Agents against MLS datasets by allowing them to create and sign-in to a Retsly account and authorize your application.

Setting up an OAuth flow

The OAuth domain and redirect URI must be specified on the Retsly platform (found on your application's setup page).

Once a flow has been setup, a user will be able to sign in to their Retsly account to authorize data access. If they have not previously setup a Retsly account, they can do so via the flow dialog. To setup an account your user must first validate their email address (by selecting their MLS, and enter the email used on that database), entering the validation code that is emailed to them, and selecting a password. After the account has been created, they can sign in.

Once signed in, the user will be prompted to authorize data access on their behalf for your application, and if scope permissions have been set by the data provider, they will need to approve each scope.

Setting up the OAuth flow is best understood as being comprised of three steps:

  • Initialization: The application making the request is verified, initial conditions are set.

  • Authorization: A decision is (or is not) displayed to the user, who then decides whether or not to authorize the OAuth Client.

  • Return: OAuth credential is (or is not) returned to the OAuth Client with accompanying information (state, expiry, etc).


Initialization determines what is displayed to the user, the type of credential (authorization token) returned, and the way in which that credential is returned.

Note If you provide invalid values for initialization parameters other than those detailed below, the values will be stripped and ignored.

An example OAuth initialization request:
  &scope=offline pub
  &dataset={test test_sf test_sd}

Required parameters

client_idstringYour application's unique identifier, and can be found on your application's details and settings pages. Your application has to be approved for any datasets that you are attempting to authorize against.
redirect_uristringDesignates where the result (credential or error) is sent after the completion of the flow. This must match the Redirect URL specified in your application settings.
response_typestringAccepts either token or code. Determines whether a simple authorization token is returned, or a validation code. For additional security, we recommend using code, as authorization tokens will not be exposed. If code is specified, you will need to do a code exchange to receive the token (see Code Exchange below).

Optional parameters

scopestringAccepts offline. The offline scope, which is only effective during response_type=code flow, grants a long-lived token and a refresh token, giving the application access to the dataset on behalf of the user beyond the lifetime of a normal session (a normal session is 3 hours).
statestringA single-use string that you may implement, and will be passed back at the end of the flow. The state parameter can help you secure against the possibility of cross-site request forgery.
dialogbooleanIndicates the manner in which credentials should be returned. If set to true, the result will be an object passed via postMessage to the redirect_uri. This will open a new window in which the Retsly Secure Sign-In OAuth flow will be displayed. Unless set to true the resultant credential is passed back to the redirect_uri via the address.
repromptbooleanDefines whether the user is reprompted for previously unauthorized scopes.
datasetstringAccepts code separated datasetIDs. This parameter is used to control the MLS datasets that are displayed in the Secure Sign-In's user registration process. If no dataset is specified, the dropdown will populate with all the MLS datasets currently approved for your application. This parameter will also pre-populate the flow dialog with the MLS's logo, which is helpful in establishing user trust. Only MLS datasets that have been approved for your application are available.
iconbooleanIndicates whether the app icon should appear on each page of the OAuth flow.
autoPopulatestringAccepts space separated field names. Indicates whether the user registration page should auto fill-in the specified fields based on MLS agent data. The options for field names are: firstName, lastName, office, and email.


Once a user has signed in to their Retsly account, they are required to authorize data access. This part of the flow determines whether your user needs to be prompted with a decision.

There are several scenarios where a user will be prompted for authorization confirmation:

Initial authorization:

  • If the user has not previously authorized the OAuth client.

When initialized with reprompt = true:

  • If, during a previous decision, the user decided to not grant all requested permissions.
  • If the requesting OAuth Client has gained access to new datasets.
  • If the user has different associations since they last authorized.

Subsequent to the initial authorization, the user will only be reprompted to authorize additional scopes if the OAuth Client has passed the reprompt option during the initialization phase and if there is any difference between previously authorized and currently requested scopes. If the OAuth Client did not include reprompt=true, if there is no difference in granted and requested scope or if none of the above reprompt scenarios apply, the decision prompt is not seen by the user and the OAuth Client is sent appropriate credentials.

Displayed scopes

The scopes that are displayed to your user for authorization are dependent on the datasets the application has been approved for, and the scopes that have been approved by the data provider for each of those datasets.


The final step in the flow returns authorization credentials, taking into account the initialization parameters response_type, state and dialog.

Initialization responses

401 Invalid ClientThe specified Client ID is not correct. Check your application's Client ID, available on your application's detail and settings pages.
400 Redirect URI requiredThe Redirect URL is missing.
400 Redirect URI mismatchThe Redirect URI does not match the URL specified in your application's settings page.
400 Invalid response_typeResponse type can only be token or code.

Authorization responses

401 The user denied authorizationYour user has denied your application access to the dataset during their OAuth flow.

Post authorization responses

200 SuccessSuccessful reponse.
401 Invalid Access TokenApplication token is incorrect. Ensure your are using the Server token, available on your application's detail and settings pages.
401 Invalid token context. Please use a HTTP token for this requestApplication token is incorrect. Ensure your are using the Server token, available on your application's detail and settings pages.
401 Request Origin does not match token DomainThe request is not coming from the domain specified in your application's settings page.

Code exchange

If you have initialized with response_type=code and the user accepts your request, Retsly responds to your callback with a temporary validation code as well as the state specified in the initialization step (if provided). If the states don't match, the request has been created by a third party and the process should be aborted.

Exchange the validation code immediately for an access token. The validation code expires within a few minutes. Ensure the code exchange is done using a POST request to avoid exposing your client_secret.

Parameters for code exchange request

Required parameters
client_idstringYour application's unique identifier, and can be found on your application's details and settings pages.
client_secretstringYour application's secret token, and can be found on your application's details and settings pages.
redirect_uristringDesignates where the result (credential or error) is sent after the completion of the flow. This must match the Redirect URL specified in your application settings.
codestringThis is the validation code sent back by Retsly
Optional parameters
statestringA single-use string that you may implement, and will passed back at the end of the flow. The state parameter can help you secure against the possibility of cross-site request forgery.

Example code exchange

  "client_id": {client_id},
  "client_secret": {client_secret},
  "redirect_uri": {redirect_uri},
  "grant_type": "authorization_code",
  "code": {code},
  "state": {state}
Example response
  "access_token": {access_token},
  "expiry": {expiry},
  "token_type": {token_type}

Refresh token exchange

If you requested and received authorization for an offline scope from the user, the code exchage above will return a refresh_token in addition to the access_token. This refresh token can be used to generate a new access token once the original one expires.

Ensure the code exchange is done using a POST request to avoid exposing your client_secret.

Parameters for refresh token exchange request

Required parameters
client_idstringYour application's unique identifier, and can be found on your application's details and settings pages.
client_secretstringYour application's secret token, and can be found on your application's details and settings pages.
redirect_uristringDesignates where the result (credential or error) is sent after the completion of the flow. This must match the Redirect URL specified in your application settings.
refresh_tokenstringThis is the refresh token sent back by Retsly
Optional parameters
statestringA single-use string that you may implement, and will passed back at the end of the flow. The state parameter can help you secure against the possibility of cross-site request forgery.

Example code exchange

  "client_id": {client_id},
  "client_secret": {client_secret},
  "redirect_uri": {redirect_uri},
  "grant_type": "refresh_token",
  "refresh_token": {refresh_token},
  "state": {state}
Example response
  "access_token": {access_token},
  "token_type": {token_type}


Retsly's Push API allows you listen for changes in the datasets, and trigger events based on chosen criteria. This may include criteria such as price and status changes of a listing, or new listings becoming available on a specific dataset.

Push events can be setup using the Retsly dashboard, or programatically using the API. Currently only MLS listing data is supported for push notifications.

Using the Retsly dashboard

Using the Retsly dashboard you're able to setup webhooks that will listen for dataset changes, and send notifications directly to your server. Setup is as simple as selecting your application, the dataset you'd like to watch and the trigger criteria. If you are developing against Retsly Test data, remember to use the Dynamic Test datasets, as they receive regular updates.

Using the Push API

The Push API will POST to the supplied URL with resources that satisfy the specified criteria. The API expects endpoints to return POST requests with a HTTP response code 200. Webhooks are tied to your application's Server token, and will only return results for datasets that have been approved for that application. The push event will trigger when any resource that match your query is added to the dataset, or changes to meet the specified criteria.

The following MLS dataset resources are available: listings, agents, and offices.

Create a webhook

POST{vendorID}/hooks?access_token={server token}Request body
  "resource": {resource},
  "query": {query},
  "url": {your server url}
  "success": true,
  "status": 201,
  "bundle": {
    "id": {id},
    "resource": {listings},
    "url": {your server url},
    "query": {query},
    "user": {user},
    "app": {app},
    "vendorID": {vendorID},
    "status": {webhook status},
    "type": "POST"

Get a webhook

GET{vendorID}/hooks/{hook ID}?access_token={server token}Response
  "success": true,
  "status": 200,
  "bundle": {
    "id": {id},
    "resource": {listings},
    "url": {your server url},
    "query": {query},
    "user": {user},
    "app": {app},
    "vendorID": {vendorID},
    "status": {webhook status},
    "type": "POST"

Test a webhook

GET{vendorID}/hooks/{hook ID}/test?access_token={server token}Response
  "success": true,
  "status": 200,
  "bundle": {
    "hook": {
      "id": {id},
      "_id": {_id},
      "resource": {listings},
      "url": {your server url},
      "query": {query},
      "user": {user},
      "app": {app},
      "vendorID": {vendorID},
      "status": {webhook status},
      "type": "GET",
      "__v": 0
    "data": [
        "_id": {_id},
        "id": {id},
        "mlsListingID": {mlsListingID},
        "address": {address},
        "unitNumber": {unitNumber},
        "streetName": {streetName},
        "streetNumber": {streetNumber},
        "city": {city},
        "state": {state},
        "county": {county},
        "country": {country},
        "zipCode": {zipCode},
        "subdivision": {subdivision}

Edit a webhook

POST{vendorID}/hooks/{hook ID}?access_token={server token}Request body
  "query": {query}
  "success": true,
  "status": 200,
  "bundle": {
    "id": {id},
    "resource": {listings},
    "url": {your server url},
    "query": {query},
    "user": {user},
    "app": {app},
    "vendorID": {vendorID},
    "status": {webhook status},
    "type": "POST"

Delete a webhook

DEL{vendorID}/hooks/{hook ID}?access_token={server token}Response
  "success": true,
  "status": 200,
  "bundle": "OK"

Get a list of webhooks for application

GET{vendorID}/hooks?access_token={server token}Response
  "success": true,
  "status": 200,
  "bundle": [
      "id": {id},
      "resource": {listings},
      "url": {your server url},
      "query": {query},
      "user": {user},
      "app": {app},
      "vendorID": {vendorID},
      "status": {webhook status},
      "type": "GET"
  "total": 1
  • API RESPONSE TIME:loading...
  • API ERROR RATE:loading...