Bridge API Documentation

The Bridge API Platform

Formerly known as Retsly, The Bridge API 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. The Bridge API also facilitates managing the necessary data licenses for you and data providers with a standardized approval process.

By enabling simple 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 take your product further, we provide a variety of integrated services, including a Push API, secure OAuth user authentication and usage analytics.

Signing up with Bridge API

The Bridge API is currently live, but accessible by invite only. To request an invite contact us through our support channel.

Support

If you have any questions, feel free to contact us:

The Bridge API 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 to us for a quick review.
  • Apply for access to datasets.

Registering an application

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 Bridge API test datasets.
  • You can begin using Bridge API dashboard to track API usage and data analytics.
  • You can integrate user authentication on multiple platforms, using the Bridge API Secure Sign-in OAuth flow.
  • You can set up webhooks to test push functionality using our dynamic test datasets.

IP and Domains whitelisting

Authorization tokens will only work on the HTTP referrer domains and IP addresses you have specified for your application. You may specify multiple domains, but no wildcards. If no domains or IPs have been set, this validation is skipped.

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 Bridge 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 Server token, open the API Explorer for any MLS listing data resource, and paste the token into the access_token parameter. As long as the dataset 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:

curl https://rets.io/api/v1/test/listings?access_token={your_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.

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

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

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 Bridge 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, Bridge API 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 the Bridge API 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 the Bridge API will attempt to contact you to resolve the issue.

Analytics

One of the strengths of the Bridge API 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 Bridge API through an application token or a user token, Bridge API 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.

The Bridge API

Formerly known as the Retsly API, the Bridge 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 (although in most cases you shouldn't need the). HTTPS is required; Bridge 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 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).

Querying the API

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

Authentication

Every request to the Bridge API must supply a valid API token. You can get an API token through the OAuth flow, or in the Bridge API 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:

GET https://rets.io/api/v1/test/listings?access_token={your_server_token}

Operators

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:

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

Parameters

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
NameTypeDescription
access_token stringToken to identify the application. This is always required.Example request: return all datasets approved for an applicationhttps://rets.io/api/v1/datasets?access_token=6baca547742c6f96a6ff71b138424f21
datasetID stringSpecifies the dataset to get the data from.Example: return all listings from the Test datasethttps://rets.io/api/v1/test/listings?access_token=6baca547742c6f96a6ff71b138424f21
listingId stringThe listing ID, available on the /listings resource.Example: return data relating to a specific listinghttps://rets.io/api/v1/test/listings/e98b11e1c2d285e4e72d90715cce4eda?access_token=6baca547742c6f96a6ff71b138424f21
agentId stringThe Agent ID, available on the /agents resource.Example: Return data relating to a specific agenthttps://rets.io/api/v1/test/agents/12cb9f9379896c2a2c24ba3c0fb22a67?access_token=6baca547742c6f96a6ff71b138424f21
officeId stringThe office ID, available on the /offices resource.Example: Return data relating to a specific officehttps://rets.io/api/v1/test/offices/e15b3d8c09e583a04d123872318096c8?access_token=6baca547742c6f96a6ff71b138424f21
openhouseId stringThe openhouse ID, available on the /openhouses resource.Example: Return data relating to a specific openhousehttps://rets.io/api/v1/test/openhouses/92b4e7e697e0fb0e2e3732aa701ffa13?access_token=6baca547742c6f96a6ff71b138424f21
summary stringSummary endpoint, currently only available for MLS listings data.Example: Return summary data for the Test datasethttps://rets.io/api/v1/test/listings/summary?access_token=6baca547742c6f96a6ff71b138424f21
Query parameters
NameTypeDescription
offset numberSkips this number of results.Example: Skip the first 10 listings of the Test datasethttps://rets.io/api/v1/test/listings?access_token=6baca547742c6f96a6ff71b138424f21&offset=10
limit numberLimits the size of the result set. Default is 10.Example: Limit results from the Test dataset to only 2https://rets.io/api/v1/test/listings?access_token=6baca547742c6f96a6ff71b138424f21&limit=2
sortBy stringResponse field to sort query by.Example: Sort order by pricehttps://rets.io/api/v1/test/listings?access_token=6baca547742c6f96a6ff71b138424f21&sortBy=price
order stringOrder of responses: "asc/desc".Example: Sort order by descending pricehttps://rets.io/api/v1/test/listings?access_token=6baca547742c6f96a6ff71b138424f21&sortBy=price&order=asc
near stringCoord or location e.g. near={Lng},{Lat} or near=San DiegoExample: Return listings that are near specific co-ordinateshttps://rets.io/api/v1/test/listings?access_token=6baca547742c6f96a6ff71b138424f21&limit=2&near=-122.395743,37.793662
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 mileshttps://rets.io/api/v1/test/listings?access_token=6baca547742c6f96a6ff71b138424f21&limit=2&near=-122.395743,37.793662&radius=5mi
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 boxhttps://rets.io/api/v1/test/listings?access_token=6baca547742c6f96a6ff71b138424f21&box=-122.435676,37.781368,-122.415764,37.799580
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-shapehttps://rets.io/api/v1/test/listings?access_token=6baca547742c6f96a6ff71b138424f21&poly=-122.435676,37.781368,-122.415764,37.799580,-122.447092,37.796291
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 builthttps://rets.io/api/v1/test/listings/summary?access_token=6baca547742c6f96a6ff71b138424f21&price.gt=500000&groupBy=yearBuilt

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 in the API Explorer.

Multi-MLS development

The Bridge 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

/datasets

Retrieve a group of datasets.

Example: Get a list of all datasets approved for an applicationhttps://rets.io/api/v1/datasets?access_token=6baca547742c6f96a6ff71b138424f21
/listings

Retrieves a set of listings.

Example: Get listings in the Test dataset where price is greater than $500,000https://rets.io/api/v1/test/listings?access_token=6baca547742c6f96a6ff71b138424f21&price.gt=500000
/agents

Retrieves a set of agents.

Example: Get a set of agents in the Test dataset whose name is not 'Ursula'https://rets.io/api/v1/test/agents?access_token=6baca547742c6f96a6ff71b138424f21&firstName.ne=Ursula
/offices

Retrieves a set of offices.

Example: Get a set of offices in the Test dataset that are located in Vermont https://rets.io/api/v1/test/offices?access_token=6baca547742c6f96a6ff71b138424f21&state=VT
/maps

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 1970https://rets.io/api/v1/test/listings/maps?access_token=6baca547742c6f96a6ff71b138424f21&limit=10
/summary

Retrieves aggregate summary data for a given query.

Example: Get summary data for houses built in 1970https://rets.io/api/v1/test/listings/summary?access_token=6baca547742c6f96a6ff71b138424f21&yearBuilt.gt=1970

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

Parcels

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.

Assessments

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.

Transactions

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.

Comparables

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
CPCooperative
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
RCRecreational
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)

SDKs

To help integrate with the Bridge 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:

RESO OData API

The Bridge platform also allows you to query MLS data using the RESO OData Web API spec.

Operators

You can constrain the result set of a resource by passing additional operators with your request. Valid operators include:

OperatorDescription
eq Equal
ne Not equal
gt Greater than
lt Less than
ge Greater than or equal
le Less than or equal
and Logical and
or Logical or
not Logical not

Parameters

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
NameTypeDescription
access_token stringToken to identify the application. This is always required.Example request: return all datasets approved for an applicationhttps://rets.io/api/v1/OData/DataSystem?access_token=Access Token
ListingKey stringThe listing key, available on the /Properties resource.Example: return data relating to a specific listinghttps://rets.io/api/v1/OData/test/Properties('ListingKey')?access_token=Access Token
MemberKey stringThe member key, available on the /Members resource.Example: Return data relating to a specific agenthttps://rets.io/api/v1/OData/test/Members('MemberKey')?access_token=Access Token
OfficeKey stringThe office key, available on the /Offices resource.Example: Return data relating to a specific officehttps://rets.io/api/v1/OData/test/Offices('OfficeKey')?access_token=Access Token
OpenHouseKey stringThe openhouse key, available on the /OpenHouses resource.Example: Return data relating to a specific openhousehttps://rets.io/api/v1/OData/test/OpenHouses('OpenHouseKey')?access_token=Access Token
Query parameters
NameTypeDescription
$skip numberSkips this number of results.Example: Skip the first 10 listings of the Test datasethttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$skip=10
$select numberSelect the fields to be returnedExample: Only return the LivingArea fieldhttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$select=LivingArea
$filter numberFilter the results to be returnedExample: Only return the listings where the ListPrice is greater than $100000https://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=ListPrice gt 100000
$top numberLimits the size of the result set. Default is 10.Example: Limit results from the Test dataset to only 2https://rets.io/api/v1/OData/test/Properties?access_token=access_token&$top=2
$orderBy stringResponse field to sort query by.Example: Sort order by descending pricehttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$orderBy=ListPrice desc
Query Functions
FunctionDescription
geo.distance Search by coordinatesExample: Return listings that are near specific co-ordinates, to a radius of 0.5 mileshttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=geo.distance(Coordinates, POINT(-118.62 34.22)) gt 0.5
geo.intersects If you know the extents of a polygonal region, you can provide the each point as co-ordinatesExample: Return listings within a shapehttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=geo.intersects(Coordinates, POLYGON((-127.02 45.08,-127.02 45.38,-127.32 45.38,-127.32 45.08,-127.02 45.08)))
tolower Search fields with lowercase queriesExample: Return listings using a lowercase queryhttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=tolower(StandardStatus) eq 'active'
toupper Search fields with uppercase queriesExample: Return listings using a uppercase queryhttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=toupper(StandardStatus) eq 'ACTIVE'
date Search fields by dateExample: Return listings with a specific datehttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=date(ModificationTimestamp) eq 2017-08-29
time Search fields by timeExample: Return listings with a specific timehttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=time(ModificationTimestamp) eq 17:03:04
year Search fields by yearExample: Return listings with a specific yearhttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=year(ModificationTimestamp) eq 2017
month Search fields by monthExample: Return listings with a specific monthhttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=month(ModificationTimestamp) eq 12
day Search fields by dayExample: Return listings with a specific dayhttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=day(ModificationTimestamp) eq 23
hour Search fields by hourExample: Return listings with a specific hourhttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=hour(ModificationTimestamp) eq 17
minute Search fields by minuteExample: Return listings with a specific minutehttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=minute(ModificationTimestamp) eq 50
second Search fields by secondExample: Return listings with a specific secondhttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=second(ModificationTimestamp) eq 12
fractionalseconds Search fields by fractionals of secondsExample: Return listings within a specific fraction of a secondhttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=fractionalseconds(ModificationTimestamp) eq 123
now() Search fields by current timestampeExample: Return listings within the current timestamphttps://rets.io/api/v1/OData/test/Properties?access_token=access_token&$filter=ModificationTimestamp eq now()

Bridge API Secure Sign-in OAuth Flow

Bridge API 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 Bridge API Secure Sign-In OAuth flow is designed to facilitate authenticating Agents against MLS datasets by allowing them to create and sign-in to a Bridge API account and authorize your application.

Setting up an OAuth flow

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

Once a flow has been setup, a user will be able to sign in to their Bridge API account to authorize data access. If they have not previously setup a Bridge API 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

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:
https://rets.io/oauth/authorize
  ?client_id={client_id}
  &redirect_uri={redirect_uri}
  &response_type=code
  &scope=offline pub
  &state=hardToGuessNonce
  &dialog=true
  &reprompt=true
  &dataset={test test_sf test_sd}

Required parameters

ParameterTypeDescription
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

ParameterTypeDescription
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 Bridge API 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.

Authorization

Once a user has signed in to their Bridge API 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.

Return

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

Initialization responses

ResponseDescription
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

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

Post authorization responses

ResponseDescription
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, Bridge API 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
ParameterTypeDescription
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 Bridge API
Optional parameters
ParameterTypeDescription
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

POST https://rets.io/oauth/tokenRequest Body
{
  "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
ParameterTypeDescription
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 Bridge API
Optional parameters
ParameterTypeDescription
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

POST https://rets.io/oauth/tokenRequest Body
{
  "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}
}

Push

Bridge API's Push functionality 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.

Currently only MLS listing data is supported for push notifications.

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: listing, agent, and office.

Create a webhook

POST https://rets.io/api/v1/{datasetID}/hooks?access_token={server token}Request body
{
  "resource": {resource},
  "query": {query},
  "url": {your server url}
}
Response
{
  "success": true,
  "status": 201,
  "bundle": {
    "id": {id},
    "resource": {listings},
    "url": {your server url},
    "query": {query},
    "user": {user},
    "app": {app},
    "datasetID": {datasetID},
    "status": {webhook status},
    "type": "POST"
  }
}

Get a webhook

GET https://rets.io/api/v1/{datasetID}/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},
    "datasetID": {datasetID},
    "status": {webhook status},
    "type": "POST"
  }
}

Test a webhook

GET https://rets.io/api/v1/{datasetID}/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},
      "datasetID": {datasetID},
      "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 https://rets.io/api/v1/{datasetID}/hooks/{hook ID}?access_token={server token}Request body
{
  "query": {query}
}
Response
{
  "success": true,
  "status": 200,
  "bundle": {
    "id": {id},
    "resource": {listings},
    "url": {your server url},
    "query": {query},
    "user": {user},
    "app": {app},
    "datasetID": {datasetID},
    "status": {webhook status},
    "type": "POST"
  }
}

Delete a webhook

DEL https://rets.io/api/v1/{datasetID}/hooks/{hook ID}?access_token={server token}Response
{
  "success": true,
  "status": 200,
  "bundle": "OK"
}

Get a list of webhooks for application

GET https://rets.io/api/v1/{datasetID}/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},
      "datasetID": {datasetID},
      "status": {webhook status},
      "type": "GET"
    }
  ],
  "total": 1
}