{
  "openapi": "3.0.1",
  "info": {
    "title": "🏠🏘️ Zillow Agents Finder & Listings Scraper",
    "description": "🏠🏘️ Zillow Agents Finder & Listings Scraper Extract real estate agents and mortgage lenders from Zillow at scale — by URL, screen name, or location-based directory search.",
    "version": "0.1",
    "x-build-id": "vbQEWElnYSGVBuZ44"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapeflow~zillow-agents-finder/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapeflow-zillow-agents-finder",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/scrapeflow~zillow-agents-finder/runs": {
      "post": {
        "operationId": "runs-sync-scrapeflow-zillow-agents-finder",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/scrapeflow~zillow-agents-finder/run-sync": {
      "post": {
        "operationId": "run-sync-scrapeflow-zillow-agents-finder",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "agentTargets": {
            "title": "🔗 Agent / Lender Targets (URLs, Screen Names, Names)",
            "uniqueItems": true,
            "type": "array",
            "description": "Bulk input — each item can be:\n• Full profile URL — `https://www.zillow.com/profile/REMAX EDGE`\n• Profile sub-tab URL — `https://www.zillow.com/profile/<name>/sales|rentals|sold|reviews` (Zillow no longer serves these sub-tab pages live — this actor detects the intent and returns the equivalent real listing data from the agent's profile page instead, see below)\n• Screen name with `@` prefix — `@REMAX EDGE` (optionally `@REMAX EDGE/reviews`)\n• Agent or lender name (free text) — runs a directory search\n\nLeave empty to run a pure location-based crawl. Accepts the base actor's `urls` key as a fallback.",
            "items": {
              "type": "string"
            }
          },
          "dataMode": {
            "title": "🗂️ Data Mode",
            "enum": [
              "agents",
              "lenders"
            ],
            "type": "string",
            "description": "Which Zillow directory to target. Accepts the base actor's `operation` key as a fallback."
          },
          "market": {
            "title": "📍 Market / City",
            "type": "string",
            "description": "City / state used as the geo seed for every directory search (e.g. `New York`, `Los Angeles, CA`). Required unless every target is a direct profile URL or `@screenName`. Accepts the base actor's `location` key as a fallback."
          },
          "maxRecords": {
            "title": "🔢 Max Agent / Lender Records",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum number of agent/lender profiles returned across all queries. Set `0` for unlimited. Accepts the base actor's `limit` key as a fallback."
          },
          "includeFullAgentProfile": {
            "title": "🧾 Full Agent Detail",
            "type": "boolean",
            "description": "When ✅ — return the full agent profile (sales stats, licenses, service areas, address, phones, email, …). When ❌ — return the compact card shape for directory-discovered agents (id, name, screenName, url, avatar, business, location, phone, rating, reviews.count). Direct URL/@screenName targets always fetch the full profile page regardless of this toggle (needed to read listings below). Accepts the base actor's `agent_detail_info` key as a fallback."
          },
          "specialtyFocus": {
            "title": "🎯 Specialty Filter",
            "enum": [
              "",
              "first-time-home-buyers",
              "foreclosure",
              "investment-properties",
              "lot-or-land",
              "luxury-homes",
              "military-or-veterans",
              "new-construction",
              "property-management",
              "relocation",
              "rentals",
              "senior-communities",
              "vacation-short-term-rentals"
            ],
            "type": "string",
            "description": "Single specialty filter for the agents directory. Accepts a numeric code or a Zillow slug. Accepts the base actor's `specialty` key as a fallback."
          },
          "languageSpoken": {
            "title": "🗣️ Language Filter",
            "enum": [
              "",
              "english",
              "arabic",
              "bengali",
              "cantonese",
              "farsi",
              "french",
              "german",
              "greek",
              "hebrew",
              "hindi",
              "hungarian",
              "italian",
              "japanese",
              "korean",
              "mandarin",
              "polish",
              "portuguese",
              "russian",
              "spanish",
              "filipino",
              "thai",
              "turkish",
              "vietnamese"
            ],
            "type": "string",
            "description": "Single language filter (display name). Accepts the base actor's `language` key as a fallback."
          },
          "topAgentsOnly": {
            "title": "⭐ Top Agents only",
            "type": "boolean",
            "description": "Filter to Zillow-flagged top agents (agents only). Accepts the base actor's `is_top_agent` key as a fallback."
          },
          "buyerSpecialist": {
            "title": "🛒 Specializes in buying",
            "type": "boolean",
            "description": "Filter to agents who focus on buyers (agents only). Accepts the base actor's `is_buying` key as a fallback."
          },
          "sellerSpecialist": {
            "title": "💸 Specializes in selling",
            "type": "boolean",
            "description": "Filter to agents who focus on sellers (agents only). Accepts the base actor's `is_selling` key as a fallback."
          },
          "includeActiveListings": {
            "title": "🏷️ Include Active For-Sale & Rental Listings",
            "type": "boolean",
            "description": "When ✅ — for every agent whose profile page is fetched (full-detail mode, or a direct URL/@screenName target), emit that agent's real active for-sale and for-rent listings as linked child rows: zpid, address, price, bedrooms/bathrooms, photo, brokerage, and listing URL. Zillow's dedicated /sales and /rentals profile sub-tab pages are no longer served live (confirmed HTTP 404) — this reads the equivalent data straight from the agent's own profile-page JSON instead. Default ON.",
            "default": true
          },
          "includeSoldListings": {
            "title": "💰 Include Itemized Sold / Closed Listings",
            "type": "boolean",
            "description": "When ✅ — emit the agent's itemized closed/sold sales as linked child rows: address, sold price, sold date, bedrooms/bathrooms, and which side the agent represented (buyer/seller) — real sales-history proof beyond the base's `salesStats.pastSalesTotal` count. Zillow's dedicated /sold profile sub-tab page is no longer served live (confirmed HTTP 404) — this reads the equivalent data straight from the agent's own profile-page JSON instead. Default ON.",
            "default": true
          },
          "maxListingsPerAgent": {
            "title": "🔢 Max Listings Per Agent (per category)",
            "minimum": 0,
            "maximum": 50,
            "type": "integer",
            "description": "Cap on how many active-listing / sold-listing child rows to emit per agent per category. Set `0` to keep every itemized item Zillow's profile page embeds (in practice up to 5 per category — see the section note above).",
            "default": 0
          },
          "computeSalesAnalytics": {
            "title": "📊 Compute Price Tier",
            "type": "boolean",
            "description": "When ✅ — add a derived (non-AI) `priceTier` field (entry/mid/upper/luxury) to every full-detail agent record, classified from the agent's `priceRangeThreeYearMin/Max` when Zillow provides it, falling back to the average price of the agent's OWN active for-sale listings (real data, zero extra request) since `priceRangeThreeYearMin/Max` is null on every live profile we tested. Computed locally — no extra request. Default ON.",
            "default": true
          },
          "lenderSortOrder": {
            "title": "📊 Lender Sort Order",
            "enum": [
              "relevance",
              "location",
              "rating"
            ],
            "type": "string",
            "description": "Sort order for the lender directory (lenders only). Accepts the base actor's `sort_lenders` key as a fallback."
          },
          "lenderFieldsToInclude": {
            "title": "🧮 Lender Field Allowlist",
            "uniqueItems": true,
            "type": "array",
            "description": "Pick which fields to keep on each lender record. Leave empty to return every field. Values map to keys on Zillow's lender profile (`displayUser`) payload. Accepts the base actor's `lender_fields` key as a fallback.",
            "items": {
              "type": "string",
              "enum": [
                "aboutMe",
                "address",
                "cellPhone",
                "companyName",
                "confirmedReviews",
                "contactLenderFormDisclaimer",
                "employerMemberFDIC",
                "employerScreenName",
                "equalHousingLogo",
                "faxPhone",
                "hideCellPhone",
                "individualName",
                "languagesSpoken",
                "memberFDIC",
                "nmlsType",
                "officePhone",
                "rating",
                "recentReviews",
                "stateLicenses",
                "stateSponsorships",
                "title",
                "totalReviews"
              ]
            }
          },
          "proxySettings": {
            "title": "Proxy settings",
            "type": "object",
            "description": "By default the actor sends requests **without a proxy**. If Zillow blocks the request, the actor automatically falls back to **Apify datacenter** → **Apify residential** (with 3 retries on residential). Override here to force a specific group."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}