{
  "openapi": "3.0.1",
  "info": {
    "title": "Zillow Agents Finder By Specialty & Language",
    "description": "Zillow Agents Finder extracts Zillow real estate agent profiles, including agent names, brokerages, ratings, reviews, phone numbers, service areas, profile URLs, and more. Ideal for lead generation, market research, recruitment, and competitive analysis.",
    "version": "0.1",
    "x-build-id": "nhsv6JKyvB2POeeaF"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapio~zillow-agents-finder/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapio-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/scrapio~zillow-agents-finder/runs": {
      "post": {
        "operationId": "runs-sync-scrapio-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/scrapio~zillow-agents-finder/run-sync": {
      "post": {
        "operationId": "run-sync-scrapio-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": {
          "urls": {
            "title": "🔗 Agent URLs / Screen Names / Names (bulk)",
            "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 name (free text) — runs a directory search\n\nLeave empty to run a pure location + specialty/language directory crawl.",
            "items": {
              "type": "string"
            }
          },
          "operation": {
            "title": "📋 Operation",
            "enum": [
              "agents",
              "lenders"
            ],
            "type": "string",
            "description": "This variant is built around the Real Estate Agents pipeline (multi-specialty/language matching + service-area coverage). Mortgage Lenders is included unchanged from the base for parity.",
            "default": "agents"
          },
          "targetLocation": {
            "title": "📍 Target Location",
            "type": "string",
            "description": "City / state used as the geo seed for the directory search AND as the reference point for the new `coversLocation` service-area check (e.g. `Los Angeles, CA`). Falls back to the base `location` key if set. Required unless every URL entry is a direct profile URL or `@screenName`. Default: `New York`."
          },
          "maxAgents": {
            "title": "🔢 Max Agents",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum number of agent profiles returned across all specialty/language combinations. Falls back to the base `limit` key if set. `0` = unlimited. Default: `20`."
          },
          "agentSpecialties": {
            "title": "🎯 Specialties To Match (multi-select)",
            "uniqueItems": true,
            "type": "array",
            "description": "Pick one or more specialties to use as the directory search filter (matches Zillow's own backend search). `specialtyMatch`/`matchedSpecialties` stay `null` — Zillow's public profile page does not expose a per-agent specialties field to verify against (confirmed absent on every profile checked). Falls back to the base single-value `specialty` key when empty (backward compatible).",
            "items": {
              "type": "string",
              "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"
              ],
              "enumTitles": [
                "🏡 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"
              ]
            }
          },
          "spokenLanguages": {
            "title": "🗣️ Languages To Match (multi-select)",
            "uniqueItems": true,
            "type": "array",
            "description": "Pick one or more languages. An agent matches if their REAL profile lists ANY of these (see `languageMatch`/`matchedLanguages` in the output) — live-confirmed on real Zillow agent profiles, populated whenever the agent filled in the 'Languages' field on their profile (~40% of profiles in our sample; the rest simply never filled it in). Falls back to the base single-value `language` key when empty (backward compatible).",
            "items": {
              "type": "string",
              "enum": [
                "english",
                "arabic",
                "bengali",
                "cantonese",
                "farsi",
                "french",
                "german",
                "greek",
                "hebrew",
                "hindi",
                "hungarian",
                "italian",
                "japanese",
                "korean",
                "mandarin",
                "polish",
                "portuguese",
                "russian",
                "spanish",
                "filipino",
                "thai",
                "turkish",
                "vietnamese"
              ],
              "enumTitles": [
                "🇬🇧 English",
                "🇸🇦 Arabic",
                "🇧🇩 Bengali",
                "🇭🇰 Cantonese",
                "🇮🇷 Farsi",
                "🇫🇷 French",
                "🇩🇪 German",
                "🇬🇷 Greek",
                "🇮🇱 Hebrew",
                "🇮🇳 Hindi",
                "🇭🇺 Hungarian",
                "🇮🇹 Italian",
                "🇯🇵 Japanese",
                "🇰🇷 Korean",
                "🇨🇳 Mandarin",
                "🇵🇱 Polish",
                "🇵🇹 Portuguese",
                "🇷🇺 Russian",
                "🇪🇸 Spanish",
                "🇵🇭 Tagalog (Filipino)",
                "🇹🇭 Thai",
                "🇹🇷 Turkish",
                "🇻🇳 Vietnamese"
              ]
            }
          },
          "verifyRealProfileMatch": {
            "title": "🔬 Verify Real Profile Match",
            "type": "boolean",
            "description": "When ✅ (default) — if you picked any specialty/language above, the actor fetches each agent's full profile page (even in compact mode) to cross-check their REAL `languagesSpoken` (and `coversLocation`) against your filters. Note: `languageMatch` is genuinely verifiable this way (Zillow publishes it); `specialtyMatch` stays `null` regardless — Zillow does not publish a per-agent specialties field to verify against. When ❌ — skip the extra fetch in compact mode (faster, but match/coverage fields stay `null`).",
            "default": true
          },
          "dropUnmatchedProfiles": {
            "title": "🚫 Drop Unmatched Profiles",
            "type": "boolean",
            "description": "When ✅ — only keep agents whose VERIFIED real profile data actually matches at least one requested language (specialty can't be verified — see `agentSpecialties`). When ❌ (default) — keep every found agent and just label the match result. Only has an effect when a match was actually verified (see `verifyRealProfileMatch`); never drops a row it can't verify.",
            "default": false
          },
          "fetchFullAgentProfile": {
            "title": "🧾 Fetch Full Agent Profile",
            "type": "boolean",
            "description": "When ✅ — return the full agent profile (sales stats, licenses, service areas, address, phones, email, specialties, languagesSpoken, title, …). When ❌ — return the compact card shape, still enriched with the new match/coverage fields. Falls back to the base `agent_detail_info` key."
          },
          "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
          },
          "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.",
            "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, escalating to Datacenter then Residential on a block.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}