{
  "openapi": "3.0.1",
  "info": {
    "title": "Zillow Agents Finder: Lead Scoring & ZIP Search",
    "description": "Zillow Agents Finder extracts real estate agent profiles from Zillow, including agent names, brokerages, phone numbers, ratings, reviews, service areas, profile URLs, and more. Ideal for lead generation, market research, recruitment, and competitive analysis.",
    "version": "0.1",
    "x-build-id": "YSU9va1wrYXpDvl6b"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapier~zillow-agents-finder/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapier-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/scrapier~zillow-agents-finder/runs": {
      "post": {
        "operationId": "runs-sync-scrapier-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/scrapier~zillow-agents-finder/run-sync": {
      "post": {
        "operationId": "run-sync-scrapier-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 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`\n• Screen name with `@` prefix — `@REMAX EDGE` (optionally `@REMAX EDGE/reviews`)\n• Agent or lender name (free text) — searched inside every 🗺️ Search Area\n\nLeave empty to run a pure area-based discovery crawl. (Also accepts the base actor's `urls` key.)",
            "items": {
              "type": "string"
            }
          },
          "leadOperation": {
            "title": "📋 Operation Mode",
            "enum": [
              "agents",
              "lenders"
            ],
            "type": "string",
            "description": "Which Zillow directory to target. (Also accepts the base actor's `operation` key.)"
          },
          "searchAreas": {
            "title": "🗺️ Search Areas — Cities & ZIP Codes (multi-value)",
            "uniqueItems": true,
            "type": "array",
            "description": "One or more geo seeds for the directory crawl — mix city names and raw 5-digit ZIP codes freely in the SAME run, e.g. `[\"New York, NY\", \"10001\", \"Beverly Hills, CA\", \"90210\"]`. Each ZIP is automatically resolved to its Zillow city/state slug before searching. (Also accepts the base actor's single `location` string — wrapped as a 1-item list.)",
            "items": {
              "type": "string"
            }
          },
          "maxRecords": {
            "title": "🔢 Max Records",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum number of profiles returned across ALL search areas and queries combined. Set `0` for unlimited. (Also accepts the base actor's `limit` key.)"
          },
          "fullProfileDetail": {
            "title": "🧾 Full Profile Detail",
            "type": "boolean",
            "description": "When ✅ — fetch the full agent profile (sales stats, licenses, service areas, address, phones, email, years of experience, …). Required for the 📈 Years-of-Experience and 💵 Sales-Volume lead filters below — auto-enabled when either is set. When ❌ — return the compact card shape (id, name, screenName, url, avatar, business, location, phone, rating, reviews.count). (Also accepts the base actor's `agent_detail_info` key.)"
          },
          "specialty": {
            "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 applied inside every search area. Accepts a numeric code or a Zillow slug.",
            "default": ""
          },
          "language": {
            "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), applied inside every search area.",
            "default": ""
          },
          "is_top_agent": {
            "title": "⭐ Top Agents only",
            "type": "boolean",
            "description": "Filter to Zillow-flagged top agents (agents only).",
            "default": false
          },
          "is_buying": {
            "title": "🛒 Specializes in buying",
            "type": "boolean",
            "description": "Filter to agents who focus on buyers (agents only).",
            "default": false
          },
          "is_selling": {
            "title": "💸 Specializes in selling",
            "type": "boolean",
            "description": "Filter to agents who focus on sellers (agents only).",
            "default": false
          },
          "minRating": {
            "title": "⭐ Min Star Rating",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "Drop agents with `rating` below this value (0-5). Example: `4.5` keeps only highly-rated agents. Default `0` = no rating filter.",
            "default": 0
          },
          "minReviewCount": {
            "title": "📝 Min Review Count",
            "minimum": 0,
            "type": "integer",
            "description": "Drop agents with fewer than this many reviews (`reviews.count`) — separates a 5.0 rating built on 2 reviews from one built on 900. Example: `10`. Default `0` = no minimum.",
            "default": 0
          },
          "minYearsExperience": {
            "title": "📈 Min Years of Experience",
            "minimum": 0,
            "type": "integer",
            "description": "Drop agents with fewer than this many years in the industry (`yearsOfExperience`). Requires 🧾 Full Profile Detail — auto-enabled when this is set (compact directory cards don't carry it). Example: `5`. Default `0` = no minimum.",
            "default": 0
          },
          "minSalesVolume": {
            "title": "💵 Min Career Sales (count)",
            "minimum": 0,
            "type": "integer",
            "description": "Drop agents with fewer than this many total career sales (`salesStats.countAllTime`). Requires 🧾 Full Profile Detail — auto-enabled when this is set. Example: `50`. Default `0` = no minimum.",
            "default": 0
          },
          "minAvgSaleValue": {
            "title": "🏷️ Min Average Sale Value ($)",
            "minimum": 0,
            "type": "integer",
            "description": "Drop agents whose 3-year average sale value (`salesStats.averageValueThreeYear`) is below this dollar amount. Requires 🧾 Full Profile Detail — auto-enabled when this is set. Example: `500000`. Default `0` = no minimum.",
            "default": 0
          },
          "computeLeadScore": {
            "title": "💯 Compute Contact-Completeness Score",
            "type": "boolean",
            "description": "When ✅ — add a `contactCompletenessScore` (0-100) + `contactCompletenessBreakdown` to every agent record, a weighted-presence lead-quality proxy over email/phone/address/business/license fields. Only meaningful in 🧾 Full Profile Detail mode — stays `null` in compact mode (those fields are never fetched there, never faked).",
            "default": true
          },
          "dedupeAcrossAreas": {
            "title": "🧹 Dedupe Across Search Areas",
            "type": "boolean",
            "description": "When ✅ — the same agent found under two different 🗺️ Search Areas (e.g. two nearby ZIPs) is pushed once, with a `matchedSearchAreas` array listing every area it matched. When ❌ — every area's result is pushed independently.",
            "default": true
          },
          "sort_lenders": {
            "title": "📊 Lender Sort Order",
            "enum": [
              "relevance",
              "location",
              "rating"
            ],
            "type": "string",
            "description": "Sort order for the lender directory (lenders only).",
            "default": "relevance"
          },
          "lender_fields": {
            "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.",
            "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"
              ]
            }
          },
          "proxyConfiguration": {
            "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.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}