API Documentation v4.0 - Buy MLS Data

Quick Start

Get started with our API in minutes. All you need is an API key.

Obtain your API key from the provider
Make requests to our endpoints with your API key
Use filters to get the exact data you need

GET /v4/get_property_list

Example Request

GET /v4/get_property_list?state_code=PA&api_key=YOUR_API_KEY

Authentication

All API requests require an API key passed as a query parameter or X-API-KEY header.

API Key

Include your API key in every request:

Query Parameter

?api_key=YOUR_API_KEY_HERE

Header

X-API-KEY: YOUR_API_KEY_HERE

Important: Never share your API key publicly or commit it to version control.

API Endpoints

Explore our available endpoints and their capabilities.

GET /v4/get_property_list

Get Property List

Search and filter properties with pagination. Results are returned in pages of 10 items per page, with a maximum limit of 200.

Parameters

Parameter	Type	Description	Required
api_key	string	Your API key	Required
state_code	string	Filter by state code (e.g., PA, CA, NY)	Optional
state	string	Filter by state name (e.g., Pennsylvania, California, New York)	Optional
city	string	Filter by city name	Optional
address	string	Filter by street address	Optional
postal_code	string	Filter by ZIP code	Optional
status	string	Property status: `for_sale`, `for_rent`, `sold`, `fsbo`	Optional
beds	integer	Filter by number of bedrooms: `beds=2/beds=2,3`- returns all properties in range of 2 and 3 bedrooms	Optional
beds_min / beds_max	integer	Bedroom range filters: `beds_min=2/beds_max=4`- returns property that explicitly has beds_min=2 and beds_max=4	Optional
baths_consolidated	decimal	Filter by bathrooms	Optional
baths_min / baths_max	decimal	Bathroom range filters: `baths_min=2/baths_max=4`- returns property that explicitly has baths_min=2 and baths_max=4	Optional
sqft	integer	Filter by square footage	Optional
sqft_min / sqft_max	integer	Square footage range filters: `sqft_min=2000/sqft_max=4000`- returns property that explicitly has sqft_min=2000 and sqft_max=4000	Optional
lot_sqft	integer	Filter by lot square footage	Optional
year_built	integer	Filter by year built	Optional
list_price	integer	Filter by exact list price	Optional
list_price_min / list_price_max	integer	List price range filters	Optional
last_sold_price	integer	Filter by last sold price	Optional
sort_by	string	Sort results. Accepted values: `newest_listed` (newest list date first), `oldest_listed` (oldest list date first), `price_high_to_low`, `price_low_to_high`, `recently_updated` (most recently updated first). Default: sorted by property_id	Optional
limit	integer	Results per page (10-200, default: 10)	Optional
has_hoa	boolean	Homeowners Association param. If true then returns properties with Homeowners Association fee and other if false	Optional

Example Requests

Get All Properties by State

GET /v4/get_property_list?state_code=PA&api_key=YOUR_API_KEY

Filter by City & Price Range

GET /v4/get_property_list?city=Philadelphia&state_code=PA&list_price_min=250000&list_price_max=750000&api_key=YOUR_API_KEY

Filter by Beds & Baths

GET /v4/get_property_list?state_code=CA&beds=3&baths_consolidated=2&api_key=YOUR_API_KEY

Sort by Newest Listed (FSBO in California)

GET /v4/get_property_list?status=fsbo&state_code=CA&sort_by=newest_listed&api_key=YOUR_API_KEY

Sort by Price High to Low

GET /v4/get_property_list?state_code=TX&sort_by=price_high_to_low&api_key=YOUR_API_KEY

Example Response

JSON

{
  {
  "data": [
    {
      "address": "2590 State Highway 140",
      "baths_consolidated": 3.5,
      "beds": 4,
      "city": "Catheys Valley",
      "county_code": "06043",
      "county_name": "Mariposa",
      "garage": 3,
      "last_sold_date": "2019-12-04",
      "last_sold_price": 1100000,
      "last_update_date": "2025-12-27",
      "lat": 37.427328,
      "list_date": "2025-10-29",
      "list_price": 875000,
      "lon": -120.102907,
      "lot_sqft": 838530,
      "p_type": "single_family",
      "postal_code": "95306",
      "property_id": "1000005047",
      "state": "California",
      "state_code": "CA",
      "status": "for_sale",
      "sqft": 3177,
      "year_built": 2025
    }
    ....
  ],
  "page_no": 1,
  "per_page": 10,
  "total_result_count": 199159,
  "execution_time": 1.124
}
}

GET /v4/get_property_details

Get Property Details

Retrieve complete property details including listings, flags, advertiser information, lead attributes, and photos.

Parameters

Parameter	Type	Description	Required
api_key	string	Your API key	Required
property_id	string	The property ID to retrieve details for	Required

Example Request

cURL

GET /v4/get_property_details?property_id=3077408827&api_key=YOUR_API_KEY

GET /v4/get_agents_list

Get Agents List

Search and filter real estate agents/advertisers with pagination support. Each agent also includes listing-stats fields (for-sale and recently-sold counts, price ranges, and last dates) which can be filtered and sorted on — see below.

Parameters

Parameter	Type	Description	Required
api_key	string	Your API key	Required
property_id	string	Filter by property ID	Optional
name	string	Filter by agent name (partial, case-insensitive match)	Optional
email	string	Filter by email address	Optional
phone	string	Filter by phone number	Optional
type	string	Filter by advertiser type (e.g. `seller`, `buyer`)	Optional
state_code	string	Filter by state code	Optional
city	string	Filter by city	Optional
zip_code	string	Filter by ZIP / postal code	Optional
county_name	string	Filter by county name	Optional
office_name	string	Filter by office name	Optional
fulfillment_id	string	Filter by fulfillment ID	Optional
nrds_id	string	Filter by NRDS ID	Optional
Listing-stats filters (exact match)
recently_sold_count	integer	Agents with exactly this many recently-sold listings	Optional
for_sale_count	integer	Agents with exactly this many active for-sale listings	Optional
recently_sold_annual_count	integer	Agents with exactly this annual recently-sold count	Optional
show_additional_sold	boolean	Filter by the show-additional-sold flag (`true`/`false`)	Optional
Range filters (count columns) — use either `min_/max_` prefix or `_min/_max` suffix
min_recently_sold_count max_recently_sold_count	integer	Recently-sold count ≥ / ≤ value. (Aliases: `recently_sold_count_min`, `recently_sold_count_max`)	Optional
min_for_sale_count max_for_sale_count	integer	For-sale count ≥ / ≤ value. (Aliases: `for_sale_count_min`, `for_sale_count_max`)	Optional
min_recently_sold_annual_count max_recently_sold_annual_count	integer	Annual recently-sold count ≥ / ≤ value	Optional
Sorting & pagination
sort_by	string	Sort results by a listing-stats column. Accepted values: `recently_sold_count` (highest first / DESC — the default direction), `recently_sold_count_asc`, `recently_sold_count_desc`, `for_sale_count`, `for_sale_count_asc`, `for_sale_count_desc`, `recently_sold_annual_count`, `recently_sold_annual_count_asc`, `recently_sold_annual_count_desc`. Agents with no stats sort last (NULLS LAST). Unknown values are ignored and fall back to default `property_id` order.	Optional
page	integer	Page number (default: 1)	Optional
per_page	integer	Results per page (10-200, default: 10)	Optional

Filtering vs. sorting: A range filter such as recently_sold_count_min=11 only restricts which agents are returned — it does not sort them. Without sort_by, results come back in default property_id order, so the filtered column looks unordered. Add sort_by=recently_sold_count to order them. Note sort_by=recently_sold is not a valid value (use the full recently_sold_count).

Returned listing-stats fields

Every agent object also includes: for_sale_count, for_sale_last_date, for_sale_price_min, for_sale_price_max, recently_sold_count, recently_sold_last_date, recently_sold_price_min, recently_sold_price_max, recently_sold_annual_count, combined_annual_price_min, combined_annual_price_max, show_additional_sold. These are null for agents not yet enriched.

Example Requests

Get Agents by State

GET /v4/get_agents_list?state_code=PA&api_key=YOUR_API_KEY

Filter by recently-sold count range

GET /v4/get_agents_list?recently_sold_count_min=11&recently_sold_count_max=20&api_key=YOUR_API_KEY

Range filter + sort (busiest agents first)

GET /v4/get_agents_list?recently_sold_count_min=11&sort_by=recently_sold_count&api_key=YOUR_API_KEY

Top agents by for-sale count in a state

GET /v4/get_agents_list?state_code=CA&min_for_sale_count=5&sort_by=for_sale_count&api_key=YOUR_API_KEY

GET /v4/get_agent_details

Get Agent Details

Retrieve detailed information about a real estate agent including bio, contact, ratings, and listings. Provide exactly one of: profile_id, fulfillment_id, or nrds_id.

Parameters

Parameter	Type	Description	Required
api_key	string	Your API key	Required
profile_id	string	Agent profile ID	One Required*
fulfillment_id	string	Agent fulfillment ID	One Required*
nrds_id	string	Agent NRDS ID	One Required*

Important: You must provide exactly one of: profile_id, fulfillment_id, or nrds_id.

Example Requests

By Profile ID

GET /v4/get_agent_details?profile_id=56c9490589a68901006eb677&api_key=YOUR_API_KEY

By Fulfillment ID

GET /v4/get_agent_details?fulfillment_id=1265276&api_key=YOUR_API_KEY

GET /v4/get_property_attribute_lists

Get Property Attributes List

Get paginated property lead attributes and metadata.

Example Request

cURL

GET /v4/get_property_attribute_lists?api_key=YOUR_API_KEY

GET /v4/get_property_attribute_details

Get Property Attribute Details

Get lead attributes for a specific property.

Example Request

cURL

GET /v4/get_property_attribute_details?property_id=3077408827&api_key=YOUR_API_KEY

GET /v4/get_property_photos

Get Property Photos

Get photo URLs for a specific property.

Parameters

Parameter	Type	Description	Required
api_key	string	Your API key	Required
property_id	string	The property ID	Required

Example Request

cURL

GET /v4/get_property_photos?property_id=3077408827&api_key=YOUR_API_KEY

GET /v4/get_property_flag_list

Get Property Flags List

Get paginated property flags (contingent, new construction, foreclosure, etc.).

Example Request

cURL

GET /v4/get_property_flag_list?api_key=YOUR_API_KEY

GET /v4/get_property_flag_details

Get Property Flag Details

Get all flags for a specific property.

Example Request

cURL

GET /v4/get_property_flag_details?property_id=3077408827&api_key=YOUR_API_KEY

Error Handling

Understanding API errors and HTTP status codes.

HTTP Status Codes

Status Code	Description
200	Success - Request completed successfully
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource not found
500	Server Error - Internal server error

Error Response Format

JSON

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key."
}