{ "openapi": "3.0.3", "info": { "title": "Agent Winds Customer IDX API", "version": "1.1.0", "description": "Agent Winds server-to-server IDX API for customer-owned websites. Requests are restricted to the MLS sources approved for your account. Obtain your private key and activation confirmation separately from Agent Winds. Store the key only in your backend/serverless secrets; never send it to browser code, URLs, chat prompts or logs. Requests with an Origin header are rejected. The API returns data, not a ready-made website, CRM or map UI. Required MLS/broker approvals, attribution and display rules are supplied during onboarding. This specification describes the implemented customer contract; it does not establish that an individual account has been activated." }, "servers": [ { "url": "https://tophamtechbe.com/api/treas/idx/v1" } ], "security": [ { "CustomerKey": [] } ], "paths": { "/retrieve-property-summary": { "get": { "operationId": "searchProperties", "summary": "Search approved MLS listings, up to 100 rows", "description": "Prefer the paged endpoint for navigation. Omitted source filters search all approved sources. Residential, common residential subtypes and Active defaults apply unless overridden; listingKey searches bypass those defaults.", "parameters": [ { "$ref": "#/components/parameters/State" }, { "$ref": "#/components/parameters/City" }, { "$ref": "#/components/parameters/Source" }, { "$ref": "#/components/parameters/MinPrice" }, { "$ref": "#/components/parameters/MaxPrice" }, { "$ref": "#/components/parameters/Bedrooms" }, { "$ref": "#/components/parameters/FirstPhoto" }, { "$ref": "#/components/parameters/ListingKeys" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "$ref": "#/components/parameters/county" }, { "$ref": "#/components/parameters/status" }, { "$ref": "#/components/parameters/zip" }, { "$ref": "#/components/parameters/address" }, { "$ref": "#/components/parameters/propertyType" }, { "$ref": "#/components/parameters/propertySubType" }, { "$ref": "#/components/parameters/allPropertySubTypes" }, { "$ref": "#/components/parameters/minSqft" }, { "$ref": "#/components/parameters/maxSqft" }, { "$ref": "#/components/parameters/maxBedrooms" }, { "$ref": "#/components/parameters/minBathrooms" }, { "$ref": "#/components/parameters/maxBathrooms" }, { "$ref": "#/components/parameters/minGarageSpaces" }, { "$ref": "#/components/parameters/minYearBuilt" }, { "$ref": "#/components/parameters/maxYearBuilt" }, { "$ref": "#/components/parameters/hasPool" }, { "$ref": "#/components/parameters/hasPrivatePool" }, { "$ref": "#/components/parameters/waterfront" }, { "$ref": "#/components/parameters/hasBasement" }, { "$ref": "#/components/parameters/hasAttachedGarage" }, { "$ref": "#/components/parameters/newConstruction" }, { "$ref": "#/components/parameters/hasMedia" }, { "$ref": "#/components/parameters/priceSort" }, { "$ref": "#/components/parameters/daysonmarketSort" }, { "$ref": "#/components/parameters/listingDateSort" }, { "$ref": "#/components/parameters/minLotSizeAcres" }, { "$ref": "#/components/parameters/maxLotSizeAcres" }, { "$ref": "#/components/parameters/centerLat" }, { "$ref": "#/components/parameters/centerLng" }, { "$ref": "#/components/parameters/radiusMiles" }, { "$ref": "#/components/parameters/minListingDate" } ], "responses": { "200": { "description": "Approved matching listings; total_count is the returned row count, not the entire result-set size. Map results use map.match_count instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "examples": { "illustrative": { "summary": "Illustrative shape only; not a live or available listing", "value": { "total_count": 1, "properties": [ { "id": 12345, "listing_key": "EXAMPLE-LISTING", "current_price": 325000, "city": "Example City", "state": "OK", "bedrooms_total": 3, "bathrooms_full": 2, "first_photo_url": null } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Expired, invalid or scope/query-mismatched cursor. Restart pagination without the cursor." }, "422": { "description": "Requested advanced search capability is not ready." }, "429": { "$ref": "#/components/responses/Limited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/retrieve-property-summary/page": { "get": { "operationId": "pageProperties", "summary": "Page through approved MLS listings", "description": "Use next_cursor with the same filters. Never send limit. Cursors are opaque, expire, and are bound to query and MLS scope. Residential/Active search defaults apply as on searchProperties. An expired or mismatched cursor returns 409; restart without a cursor. Do not infer total inventory size from total_count.", "parameters": [ { "$ref": "#/components/parameters/State" }, { "$ref": "#/components/parameters/City" }, { "$ref": "#/components/parameters/Source" }, { "$ref": "#/components/parameters/MinPrice" }, { "$ref": "#/components/parameters/MaxPrice" }, { "$ref": "#/components/parameters/Bedrooms" }, { "$ref": "#/components/parameters/FirstPhoto" }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 4096 } }, { "$ref": "#/components/parameters/county" }, { "$ref": "#/components/parameters/status" }, { "$ref": "#/components/parameters/zip" }, { "$ref": "#/components/parameters/address" }, { "$ref": "#/components/parameters/propertyType" }, { "$ref": "#/components/parameters/propertySubType" }, { "$ref": "#/components/parameters/allPropertySubTypes" }, { "$ref": "#/components/parameters/minSqft" }, { "$ref": "#/components/parameters/maxSqft" }, { "$ref": "#/components/parameters/maxBedrooms" }, { "$ref": "#/components/parameters/minBathrooms" }, { "$ref": "#/components/parameters/maxBathrooms" }, { "$ref": "#/components/parameters/minGarageSpaces" }, { "$ref": "#/components/parameters/minYearBuilt" }, { "$ref": "#/components/parameters/maxYearBuilt" }, { "$ref": "#/components/parameters/hasPool" }, { "$ref": "#/components/parameters/hasPrivatePool" }, { "$ref": "#/components/parameters/waterfront" }, { "$ref": "#/components/parameters/hasBasement" }, { "$ref": "#/components/parameters/hasAttachedGarage" }, { "$ref": "#/components/parameters/newConstruction" }, { "$ref": "#/components/parameters/hasMedia" }, { "$ref": "#/components/parameters/priceSort" }, { "$ref": "#/components/parameters/daysonmarketSort" }, { "$ref": "#/components/parameters/listingDateSort" }, { "$ref": "#/components/parameters/minLotSizeAcres" }, { "$ref": "#/components/parameters/maxLotSizeAcres" }, { "$ref": "#/components/parameters/centerLat" }, { "$ref": "#/components/parameters/centerLng" }, { "$ref": "#/components/parameters/radiusMiles" }, { "$ref": "#/components/parameters/minListingDate" } ], "responses": { "200": { "description": "Approved matching listings; total_count is the returned row count, not the entire result-set size. Map results use map.match_count instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "examples": { "illustrative": { "summary": "Illustrative shape only; not a live or available listing", "value": { "total_count": 1, "properties": [ { "id": 12345, "listing_key": "EXAMPLE-LISTING", "current_price": 325000, "city": "Example City", "state": "OK", "bedrooms_total": 3, "bathrooms_full": 2, "first_photo_url": null } ], "pagination": { "version": "bounded-search-v1", "page_size": 24, "returned": 1, "has_more": false, "next_cursor": null } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Expired, invalid or scope/query-mismatched cursor. Restart pagination without the cursor." }, "422": { "description": "Requested advanced search capability is not ready." }, "429": { "$ref": "#/components/responses/Limited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/retrieve-property-summary/map": { "get": { "operationId": "mapProperties", "summary": "Bounded map features for approved listings", "description": "Send all four bounds together or omit all four. Do not send pageSize, cursor or limit. Residential/Active defaults apply.", "parameters": [ { "$ref": "#/components/parameters/State" }, { "$ref": "#/components/parameters/City" }, { "$ref": "#/components/parameters/Source" }, { "name": "north", "in": "query", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "south", "in": "query", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "east", "in": "query", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "west", "in": "query", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "zoom", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 22, "default": 4 } }, { "$ref": "#/components/parameters/county" }, { "$ref": "#/components/parameters/status" }, { "$ref": "#/components/parameters/zip" }, { "$ref": "#/components/parameters/address" }, { "$ref": "#/components/parameters/propertyType" }, { "$ref": "#/components/parameters/propertySubType" }, { "$ref": "#/components/parameters/allPropertySubTypes" }, { "$ref": "#/components/parameters/minSqft" }, { "$ref": "#/components/parameters/maxSqft" }, { "$ref": "#/components/parameters/maxBedrooms" }, { "$ref": "#/components/parameters/minBathrooms" }, { "$ref": "#/components/parameters/maxBathrooms" }, { "$ref": "#/components/parameters/minGarageSpaces" }, { "$ref": "#/components/parameters/minYearBuilt" }, { "$ref": "#/components/parameters/maxYearBuilt" }, { "$ref": "#/components/parameters/hasPool" }, { "$ref": "#/components/parameters/hasPrivatePool" }, { "$ref": "#/components/parameters/waterfront" }, { "$ref": "#/components/parameters/hasBasement" }, { "$ref": "#/components/parameters/hasAttachedGarage" }, { "$ref": "#/components/parameters/newConstruction" }, { "$ref": "#/components/parameters/hasMedia" }, { "$ref": "#/components/parameters/priceSort" }, { "$ref": "#/components/parameters/daysonmarketSort" }, { "$ref": "#/components/parameters/listingDateSort" }, { "$ref": "#/components/parameters/minLotSizeAcres" }, { "$ref": "#/components/parameters/maxLotSizeAcres" }, { "$ref": "#/components/parameters/centerLat" }, { "$ref": "#/components/parameters/centerLng" }, { "$ref": "#/components/parameters/radiusMiles" }, { "$ref": "#/components/parameters/minListingDate" }, { "$ref": "#/components/parameters/MinPrice" }, { "$ref": "#/components/parameters/MaxPrice" }, { "$ref": "#/components/parameters/Bedrooms" } ], "responses": { "200": { "description": "Approved matching listings; total_count is the returned row count, not the entire result-set size. Map results use map.match_count instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "examples": { "illustrative": { "summary": "Illustrative empty map response", "value": { "total_count": 0, "properties": [], "map": { "version": "bounded-search-v1", "match_count": 0, "zoom": 4, "features": [], "bounds": null } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Expired, invalid or scope/query-mismatched cursor. Restart pagination without the cursor." }, "422": { "description": "Requested advanced search capability is not ready." }, "429": { "$ref": "#/components/responses/Limited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/retrieve-property-data/{id}": { "get": { "operationId": "getPropertyById", "summary": "Read an approved property by numeric ID", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 1 } } ], "responses": { "200": { "description": "One approved listing, with optional nullable detail groups. Respect MLS display flags and supplied attribution requirements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Listing missing, outside approved scope, or ambiguous." }, "429": { "$ref": "#/components/responses/Limited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/retrieve-property-data": { "get": { "operationId": "getPropertyByListingKey", "summary": "Read an approved property by listing key", "parameters": [ { "name": "listingKey", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "One approved listing, with optional nullable detail groups. Respect MLS display flags and supplied attribution requirements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Listing missing, outside approved scope, or ambiguous." }, "429": { "$ref": "#/components/responses/Limited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/retrieve-property-media/{listingKey}": { "get": { "operationId": "getPropertyPhotos", "summary": "Read photo metadata for an approved listing", "description": "Missing, unauthorized or ambiguous listings return an empty media array. Returned media URLs can be public; fetch them without the private key.", "parameters": [ { "name": "listingKey", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+$" } } ], "responses": { "200": { "description": "Photo metadata; may be empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/Limited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "securitySchemes": { "CustomerKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Private idxc_ customer key provisioned by Agent Winds. Backend/serverless use only." } }, "parameters": { "State": { "name": "state", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, "City": { "name": "city", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "Source": { "name": "originatingSystemName", "in": "query", "description": "Optional exact approved source names. An unapproved name returns 403.", "style": "form", "explode": true, "schema": { "type": "array", "minItems": 1, "items": { "type": "string" } } }, "ListingKeys": { "name": "listingKey", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "MinPrice": { "name": "minPrice", "in": "query", "schema": { "type": "integer" } }, "MaxPrice": { "name": "maxPrice", "in": "query", "schema": { "type": "integer" } }, "Bedrooms": { "name": "minBedrooms", "in": "query", "schema": { "type": "integer" } }, "FirstPhoto": { "name": "firstPhoto", "in": "query", "schema": { "type": "boolean" } }, "county": { "name": "county", "in": "query", "schema": { "type": "string" } }, "status": { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Defaults to Active. All disables the status filter; other values must match the data." }, "zip": { "name": "zip", "in": "query", "schema": { "type": "string" } }, "address": { "name": "address", "in": "query", "schema": { "type": "string" } }, "propertyType": { "name": "propertyType", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, "propertySubType": { "name": "propertySubType", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, "allPropertySubTypes": { "name": "allPropertySubTypes", "in": "query", "schema": { "type": "boolean" }, "description": "Set true to bypass residential subtype defaults. Do not also supply propertySubType." }, "minSqft": { "name": "minSqft", "in": "query", "schema": { "type": "integer" } }, "maxSqft": { "name": "maxSqft", "in": "query", "schema": { "type": "integer" } }, "maxBedrooms": { "name": "maxBedrooms", "in": "query", "schema": { "type": "integer" } }, "minBathrooms": { "name": "minBathrooms", "in": "query", "schema": { "type": "integer" } }, "maxBathrooms": { "name": "maxBathrooms", "in": "query", "schema": { "type": "integer" } }, "minGarageSpaces": { "name": "minGarageSpaces", "in": "query", "schema": { "type": "integer" } }, "minYearBuilt": { "name": "minYearBuilt", "in": "query", "schema": { "type": "integer" } }, "maxYearBuilt": { "name": "maxYearBuilt", "in": "query", "schema": { "type": "integer" } }, "hasPool": { "name": "hasPool", "in": "query", "schema": { "type": "boolean" } }, "hasPrivatePool": { "name": "hasPrivatePool", "in": "query", "schema": { "type": "boolean" } }, "waterfront": { "name": "waterfront", "in": "query", "schema": { "type": "boolean" } }, "hasBasement": { "name": "hasBasement", "in": "query", "schema": { "type": "boolean" } }, "hasAttachedGarage": { "name": "hasAttachedGarage", "in": "query", "schema": { "type": "boolean" } }, "newConstruction": { "name": "newConstruction", "in": "query", "schema": { "type": "boolean" } }, "hasMedia": { "name": "hasMedia", "in": "query", "schema": { "type": "boolean" } }, "priceSort": { "name": "priceSort", "in": "query", "schema": { "type": "string", "enum": [ "lowhigh", "highlow", "balanced" ] } }, "daysonmarketSort": { "name": "daysonmarketSort", "in": "query", "schema": { "type": "string", "enum": [ "newold", "oldnew" ] } }, "listingDateSort": { "name": "listingDateSort", "in": "query", "schema": { "type": "string", "enum": [ "newold", "oldnew" ] } }, "minLotSizeAcres": { "name": "minLotSizeAcres", "in": "query", "schema": { "type": "number" } }, "maxLotSizeAcres": { "name": "maxLotSizeAcres", "in": "query", "schema": { "type": "number" } }, "centerLat": { "name": "centerLat", "in": "query", "schema": { "type": "number" }, "description": "Supply centerLat, centerLng and radiusMiles together." }, "centerLng": { "name": "centerLng", "in": "query", "schema": { "type": "number" }, "description": "Supply centerLat, centerLng and radiusMiles together." }, "radiusMiles": { "name": "radiusMiles", "in": "query", "schema": { "type": "number" }, "description": "Supply centerLat, centerLng and radiusMiles together." }, "minListingDate": { "name": "minListingDate", "in": "query", "schema": { "type": "string", "format": "date" } } }, "schemas": { "DetailResponse": { "type": "object", "additionalProperties": true, "properties": { "properties": { "type": "array", "items": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DetailProperty" } ] }, "nullable": true }, "total_count": { "type": "integer", "format": "int32", "nullable": true } } }, "SearchResponse": { "type": "object", "additionalProperties": true, "properties": { "pagination": { "type": "object", "properties": { "version": { "type": "string" }, "page_size": { "type": "integer" }, "returned": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "map": { "type": "object", "properties": { "version": { "type": "string" }, "match_count": { "type": "integer" }, "zoom": { "type": "integer" }, "bounds": { "type": "object", "nullable": true, "additionalProperties": true }, "features": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "kind": { "type": "string", "enum": [ "property", "cluster" ] }, "count": { "type": "integer" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "bounds": { "type": "object", "additionalProperties": true }, "id": { "type": "integer" }, "listing_key": { "type": "string" }, "current_price": { "type": "number", "nullable": true } }, "description": "Property fields id/listing_key/current_price are present for individual-property features, not clusters." } } } }, "search_meta": { "type": "object", "additionalProperties": true, "nullable": true }, "properties": { "type": "array", "items": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SummaryProperty" } ] }, "nullable": true }, "total_count": { "type": "integer", "format": "int32", "nullable": true } } }, "SummaryProperty": { "type": "object", "additionalProperties": true, "properties": { "search_facts": { "type": "object", "additionalProperties": true, "nullable": true }, "id": { "type": "integer", "format": "int32", "nullable": true }, "listing_key": { "type": "string", "nullable": true }, "mls_number": { "type": "string", "nullable": true }, "current_price": { "type": "number", "nullable": true }, "list_price": { "type": "number", "nullable": true }, "property_type": { "type": "string", "nullable": true }, "property_sub_type": { "type": "string", "nullable": true }, "mls_status": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "street_number": { "type": "string", "nullable": true }, "street_dir_prefix": { "type": "string", "nullable": true }, "street_name": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "standard_status": { "type": "string", "nullable": true }, "stories": { "type": "integer", "format": "int32", "nullable": true }, "levels": { "type": "string", "nullable": true }, "cumulative_days_on_market": { "type": "integer", "format": "int32", "nullable": true }, "first_photo_url": { "type": "string", "nullable": true }, "bedrooms_total": { "type": "integer", "format": "int32", "nullable": true }, "bathrooms_full": { "type": "integer", "format": "int32", "nullable": true }, "garage_spaces": { "type": "number", "nullable": true }, "bathrooms_half": { "type": "integer", "format": "int32", "nullable": true }, "heating": { "type": "string", "nullable": true }, "cooling": { "type": "string", "nullable": true }, "foundation_details": { "type": "string", "nullable": true }, "fencing": { "type": "string", "nullable": true }, "elementary_school": { "type": "string", "nullable": true }, "high_school": { "type": "string", "nullable": true }, "school_district": { "type": "string", "nullable": true }, "lot_size_acres": { "type": "number", "nullable": true }, "list_agent_full_name": { "type": "string", "nullable": true }, "list_agent_email": { "type": "string", "nullable": true }, "list_agent_mls_id": { "type": "string", "nullable": true }, "buyer_agent_full_name": { "type": "string", "nullable": true }, "list_office_key": { "type": "string", "nullable": true }, "list_office_key_numeric": { "type": "integer", "format": "int32", "nullable": true }, "list_office_mls_id": { "type": "string", "nullable": true }, "originating_system_name": { "type": "string", "nullable": true }, "listing_contract_date": { "nullable": true, "description": "Date/time representation from the API; handle ISO text or epoch milliseconds.", "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ] }, "created_at": { "nullable": true, "description": "Date/time representation from the API; handle ISO text or epoch milliseconds.", "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ] }, "new_construction_yn": { "type": "boolean", "nullable": true }, "pool_private_yn": { "type": "boolean", "nullable": true }, "pool_features": { "type": "string", "nullable": true }, "waterfront_yn": { "type": "boolean", "nullable": true }, "basement_yn": { "type": "boolean", "nullable": true }, "attached_garage_yn": { "type": "boolean", "nullable": true } }, "description": "Flattened listing-card fields. Nullable/missing values vary by MLS and availability. first_photo_url is populated when firstPhoto=true." }, "DetailProperty": { "type": "object", "additionalProperties": true, "properties": { "new_construction_yn": { "type": "boolean", "nullable": true }, "internet_entire_listing_display_yn": { "type": "boolean", "nullable": true }, "internet_address_display_yn": { "type": "boolean", "nullable": true }, "internet_consumer_comment_yn": { "type": "boolean", "nullable": true }, "internet_automated_valuation_display_yn": { "type": "boolean", "nullable": true }, "tax_annual_amount": { "type": "number", "nullable": true }, "tax_assessed_value": { "type": "number", "nullable": true }, "security_deposit": { "type": "number", "nullable": true }, "pet_deposit": { "type": "number", "nullable": true }, "close_price": { "type": "number", "nullable": true }, "previous_list_price": { "type": "number", "nullable": true }, "above_grade_finished_area": { "type": "number", "nullable": true }, "below_grade_finished_area": { "type": "number", "nullable": true }, "tax_year": { "type": "integer", "format": "int32", "nullable": true }, "stories_total": { "type": "integer", "format": "int32", "nullable": true }, "number_of_units_total": { "type": "integer", "format": "int32", "nullable": true }, "availability_date": { "type": "string", "nullable": true }, "price_change_timestamp": { "type": "string", "nullable": true }, "status_change_timestamp": { "type": "string", "nullable": true }, "major_change_timestamp": { "type": "string", "nullable": true }, "photos_change_timestamp": { "type": "string", "nullable": true }, "builder_name": { "type": "string", "nullable": true }, "builder_model": { "type": "string", "nullable": true }, "property_condition": { "type": "string", "nullable": true }, "lease_term": { "type": "string", "nullable": true }, "tenant_pays": { "type": "string", "nullable": true }, "owner_pays": { "type": "string", "nullable": true }, "living_area_source": { "type": "string", "nullable": true }, "living_area_units": { "type": "string", "nullable": true }, "building_area_source": { "type": "string", "nullable": true }, "building_area_units": { "type": "string", "nullable": true }, "above_grade_finished_area_source": { "type": "string", "nullable": true }, "above_grade_finished_area_units": { "type": "string", "nullable": true }, "below_grade_finished_area_source": { "type": "string", "nullable": true }, "below_grade_finished_area_units": { "type": "string", "nullable": true }, "year_built_source": { "type": "string", "nullable": true }, "possession": { "type": "string", "nullable": true }, "listing_terms": { "type": "string", "nullable": true }, "special_listing_conditions": { "type": "string", "nullable": true }, "virtual_tour_url_unbranded": { "type": "string", "nullable": true }, "virtual_tour_url_branded": { "type": "string", "nullable": true }, "id": { "type": "integer", "format": "int32", "nullable": true }, "listing_key": { "type": "string", "nullable": true }, "mls_number": { "type": "string", "nullable": true }, "current_price": { "type": "number", "nullable": true }, "list_price": { "type": "number", "nullable": true }, "building_area_total": { "type": "number", "nullable": true }, "living_area": { "type": "number", "nullable": true }, "year_built": { "type": "integer", "format": "int32", "nullable": true }, "property_type": { "type": "string", "nullable": true }, "property_sub_type": { "type": "string", "nullable": true }, "original_list_price": { "type": "number", "nullable": true }, "standard_status": { "type": "string", "nullable": true }, "mls_status": { "type": "string", "nullable": true }, "days_on_market": { "type": "integer", "format": "int32", "nullable": true }, "stories": { "type": "integer", "format": "int32", "nullable": true }, "bathrooms_full": { "type": "integer", "format": "int32", "nullable": true }, "bathrooms_half": { "type": "integer", "format": "int32", "nullable": true }, "fireplaces_total": { "type": "integer", "format": "int32", "nullable": true }, "foundation_details": { "type": "string", "nullable": true }, "roof": { "type": "string", "nullable": true }, "bedrooms_total": { "type": "integer", "format": "int32", "nullable": true }, "sewer": { "type": "string", "nullable": true }, "utilities": { "type": "string", "nullable": true }, "location": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PropertyLocation" } ] }, "features": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PropertyFeatures" } ] }, "association": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PropertyAssociation" } ] }, "schools": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PropertySchools" } ] }, "land": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PropertyLand" } ] }, "listing_contract_date": { "nullable": true, "description": "Date/time representation from the API; handle ISO text or epoch milliseconds.", "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ] }, "list_agent_full_name": { "type": "string", "nullable": true }, "list_agent_mls_id": { "type": "string", "nullable": true }, "list_office_name": { "type": "string", "nullable": true }, "attribution_contact": { "type": "string", "nullable": true }, "prop_sync_last_synced_at": { "type": "string", "nullable": true }, "prop_sync_last_seen_active_at": { "type": "string", "nullable": true }, "virtual_tour_url": { "type": "string", "nullable": true } }, "description": "Listing detail fields with nested location, features, association, schools and land groups. Unknown values must not be treated as false or zero. Respect internet display flags and the MLS requirements provided during onboarding." }, "PropertyLocation": { "type": "object", "additionalProperties": true, "properties": { "mls_area_major": { "type": "string", "nullable": true }, "mls_area_minor": { "type": "string", "nullable": true }, "unparsed_address": { "type": "string", "nullable": true }, "direction_faces": { "type": "string", "nullable": true }, "street_number": { "type": "string", "nullable": true }, "street_dir_prefix": { "type": "string", "nullable": true }, "street_name": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true } } }, "PropertyFeatures": { "type": "object", "additionalProperties": true, "properties": { "pool_private_yn": { "type": "boolean", "nullable": true }, "spa_yn": { "type": "boolean", "nullable": true }, "view_yn": { "type": "boolean", "nullable": true }, "senior_community_yn": { "type": "boolean", "nullable": true }, "garage_yn": { "type": "boolean", "nullable": true }, "attached_garage_yn": { "type": "boolean", "nullable": true }, "carport_yn": { "type": "boolean", "nullable": true }, "basement_yn": { "type": "boolean", "nullable": true }, "fireplace_yn": { "type": "boolean", "nullable": true }, "property_attached_yn": { "type": "boolean", "nullable": true }, "bathrooms_total_decimal": { "type": "number", "nullable": true }, "carport_spaces": { "type": "number", "nullable": true }, "open_parking_spaces": { "type": "number", "nullable": true }, "bathrooms_three_quarter": { "type": "integer", "format": "int32", "nullable": true }, "bathrooms_one_quarter": { "type": "integer", "format": "int32", "nullable": true }, "main_level_bedrooms": { "type": "integer", "format": "int32", "nullable": true }, "main_level_bathrooms": { "type": "integer", "format": "int32", "nullable": true }, "rooms_total": { "type": "integer", "format": "int32", "nullable": true }, "entry_level": { "type": "integer", "format": "int32", "nullable": true }, "pool_features": { "type": "string", "nullable": true }, "spa_features": { "type": "string", "nullable": true }, "view": { "type": "string", "nullable": true }, "flooring": { "type": "string", "nullable": true }, "laundry_features": { "type": "string", "nullable": true }, "basement": { "type": "string", "nullable": true }, "parking_features": { "type": "string", "nullable": true }, "architectural_style": { "type": "string", "nullable": true }, "accessibility_features": { "type": "string", "nullable": true }, "fireplace_features": { "type": "string", "nullable": true }, "window_features": { "type": "string", "nullable": true }, "security_features": { "type": "string", "nullable": true }, "other_structures": { "type": "string", "nullable": true }, "structure_type": { "type": "string", "nullable": true }, "common_walls": { "type": "string", "nullable": true }, "pets_allowed": { "type": "string", "nullable": true }, "pets_comments": { "type": "string", "nullable": true }, "furnished": { "type": "string", "nullable": true }, "bathrooms_total": { "type": "number", "nullable": true }, "garage_spaces": { "type": "number", "nullable": true }, "appliances": { "type": "string", "nullable": true }, "heating": { "type": "string", "nullable": true }, "cooling": { "type": "string", "nullable": true }, "interior_features": { "type": "string", "nullable": true }, "exterior_features": { "type": "string", "nullable": true }, "lots_features": { "type": "string", "nullable": true }, "community_features": { "type": "string", "nullable": true }, "patio_and_porch_features": { "type": "string", "nullable": true }, "water_source": { "type": "string", "nullable": true }, "fencing": { "type": "string", "nullable": true }, "public_remarks": { "type": "string", "nullable": true } } }, "PropertyAssociation": { "type": "object", "additionalProperties": true, "properties": { "association_fee2": { "type": "number", "nullable": true }, "number_of_units_in_community": { "type": "integer", "format": "int32", "nullable": true }, "association_name2": { "type": "string", "nullable": true }, "association_fee2_frequency": { "type": "string", "nullable": true }, "association_phone": { "type": "string", "nullable": true }, "association_name": { "type": "string", "nullable": true }, "association_fee": { "type": "number", "nullable": true }, "fee_frequency": { "type": "string", "nullable": true } } }, "PropertySchools": { "type": "object", "additionalProperties": true, "properties": { "elementary_school": { "type": "string", "nullable": true }, "middle_school": { "type": "string", "nullable": true }, "high_school": { "type": "string", "nullable": true } } }, "PropertyLand": { "type": "object", "additionalProperties": true, "properties": { "waterfront_yn": { "type": "boolean", "nullable": true }, "land_lease_yn": { "type": "boolean", "nullable": true }, "land_lease_amount": { "type": "number", "nullable": true }, "waterfront_features": { "type": "string", "nullable": true }, "water_body_name": { "type": "string", "nullable": true }, "land_lease_amount_frequency": { "type": "string", "nullable": true }, "lot_size_units": { "type": "string", "nullable": true }, "lot_size_source": { "type": "string", "nullable": true }, "lot_size_dimensions": { "type": "string", "nullable": true }, "lot_size_acres": { "type": "number", "nullable": true }, "lot_size_area": { "type": "number", "nullable": true }, "lot_size_square_feet": { "type": "number", "nullable": true }, "lot_dimensions_source": { "type": "string", "nullable": true }, "lot_features": { "type": "string", "nullable": true }, "zoning": { "type": "string", "nullable": true } } }, "MediaResponse": { "type": "object", "additionalProperties": true, "properties": { "media": { "type": "array", "items": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Photo" } ] }, "nullable": true }, "total_count": { "type": "integer", "format": "int32", "nullable": true } } }, "Photo": { "type": "object", "additionalProperties": true, "properties": { "short_description": { "type": "string", "nullable": true }, "long_description": { "type": "string", "nullable": true }, "image_of": { "type": "string", "nullable": true }, "media_modification_timestamp": { "type": "string", "nullable": true }, "image_width": { "type": "integer", "format": "int32", "nullable": true }, "image_height": { "type": "integer", "format": "int32", "nullable": true }, "content_type": { "type": "string", "nullable": true }, "media_category": { "type": "string", "nullable": true }, "content_id": { "type": "string", "nullable": true }, "order_hint": { "type": "string", "nullable": true }, "image_data": { "type": "string", "format": "byte", "nullable": true, "description": "Not populated by this API. Display images using media_url." }, "media_url": { "type": "string", "nullable": true, "description": "Fetch the returned URL without attaching your private API key." }, "s3_link": { "type": "string", "nullable": true } } } }, "responses": { "BadRequest": { "description": "Invalid filters or malformed parameters." }, "Unauthorized": { "description": "Missing, invalid or disabled customer credential." }, "Forbidden": { "description": "Forbidden source, endpoint, method, Origin header or mixed credentials." }, "Limited": { "description": "Customer quota exceeded. Honor Retry-After; use bounded retries.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } } }, "Unavailable": { "description": "Authentication/rate-limit storage temporarily unavailable. Fail closed; do not switch keys.", "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "ServerError": { "description": "Data retrieval failed; response may have an empty body." } } } }