# 🏠 Zillow Agents Finder (`scraperx/zillow-agents-finder`) Actor

Extract real estate agents and mortgage lenders from Zillow at scale — by URL, screen name, or location-based directory search.

- **URL**: https://apify.com/scraperx/zillow-agents-finder.md
- **Developed by:** [ScraperX](https://apify.com/scraperx) (community)
- **Categories:** Automation, Lead generation, Social media
- **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 🏠 Zillow Agents & Lenders Finder

Extract **real estate agents** and **mortgage lenders** from [Zillow](https://www.zillow.com) at scale — by URL, screen name, or location-based directory search. Built with a smart 3-tier proxy fallback ladder that automatically routes around blocks without you lifting a finger.

***

### 🤔 Why Choose Us?

- 🪜 **Smart proxy ladder** — starts direct, escalates to Apify **Datacenter** → **Residential** only when Zillow pushes back. No wasted proxy spend on requests that work.
- 🧾 **Two output shapes** — flip *Full Agent Detail* on for sales stats / licenses / phones / service areas, or keep it off for a slim card-style dataset.
- 💰 **Lenders too** — same directory + profile pipeline, with a `lender_fields` allowlist to trim the payload.
- 🔍 **Bulk inputs** — paste 1 or 10 000 profile URLs, screen names, or agent names — all in one field.
- 🌍 **Filters that matter** — specialty, language, top-agent, buying/selling, lender sort order.
- 📊 **Live dataset push** — every scraped profile lands in the dataset *as soon as it's parsed*, so a crash never costs you the run.
- 📋 **Three pre-built views** — Overview, Agent Detail, Lenders — switch in the Console without writing a query.

***

### ✨ Key Features

- ✅ Search agents or lenders by **city / state**
- ✅ Fetch profiles directly by **URL** or **`@ScreenName`**
- ✅ Profile **sub-tabs** — `sales`, `rentals`, `sold`, `reviews`
- ✅ **Specialty filter** — 12 Zillow specialties (luxury, foreclosure, military, …)
- ✅ **Language filter** — 24 languages
- ✅ **Top Agent / Buying / Selling** flags
- ✅ **Sort lenders** by relevance, location, or rating
- ✅ Pulls *real* rating from the HTML (not the cached JSON average)
- ✅ Live partial results — push happens per-profile, mid-run crashes never lose data

***

### 🔗 Input

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `urls` | `array<string>` | ⚪ | Bulk URLs / `@screenNames` / agent names. Empty = pure directory crawl. |
| `operation` | `string` | ⚪ | `agents` (default) or `lenders` |
| `location` | `string` | ⚪\* | City / state geo seed. \*Required unless every `urls` item is a direct URL or `@name`. |
| `limit` | `integer` | ⚪ | Max records (0 = unlimited). Default `20`. |
| `agent_detail_info` | `boolean` | ⚪ | `true` → full profile; `false` → compact card |
| `specialty` | `string` | ⚪ | One of 12 Zillow specialty slugs |
| `language` | `string` | ⚪ | One of 24 languages |
| `is_top_agent` / `is_buying` / `is_selling` | `boolean` | ⚪ | Agent filters |
| `sort_lenders` | `string` | ⚪ | `relevance` / `location` / `rating` |
| `lender_fields` | `array<string>` | ⚪ | Multi-select allowlist of lender fields (dropdown: `aboutMe`, `address`, `cellPhone`, `companyName`, `confirmedReviews`, `contactLenderFormDisclaimer`, `employerMemberFDIC`, `employerScreenName`, `equalHousingLogo`, `faxPhone`, `hideCellPhone`, `individualName`, `languagesSpoken`, `memberFDIC`, `nmlsType`, `officePhone`, `rating`, `recentReviews`, `stateLicenses`, `stateSponsorships`, `title`, `totalReviews`) |
| `proxyConfiguration` | `object` | ⚪ | Optional override. Default = no proxy + auto-escalation. |

#### 💡 Example input

```json
{
  "operation": "agents",
  "location": "New York",
  "limit": 20,
  "agent_detail_info": false,
  "urls": []
}
```

```json
{
  "operation": "agents",
  "urls": [
    "https://www.zillow.com/profile/REMAX EDGE",
    "@Teresa Stephenson",
    "Matthew Bizzarro"
  ],
  "location": "New York",
  "agent_detail_info": true
}
```

***

### 📤 Output

#### Compact agent record (`agent_detail_info: false`)

```json
{
  "avatar": "https://photos.zillowstatic.com/fp/.../h_l.jpg",
  "business": "RE/MAX EDGE",
  "id": "X1-ZUytouqbzgwsnd_75224",
  "location": "Brooklyn, NY",
  "name": "REMAX EDGE",
  "phone": "(718) 612-3088",
  "rating": 5.0,
  "reviews": { "count": 2640 },
  "screenName": "REMAX EDGE",
  "url": "https://www.zillow.com/profile/REMAX EDGE"
}
```

#### Full agent record (`agent_detail_info: true`)

```json
{
  "id": "...",
  "name": "Matthew Bizzarro",
  "screenName": "Matthew Bizzarro",
  "url": "https://www.zillow.com/profile/Matthew Bizzarro",
  "avatar": "...",
  "business": "The Bizzarro Agency",
  "rating": 5.0,
  "yearsOfExperience": 17,
  "reviews": { "count": 911 },
  "serviceAreas": [{ "name": "Manhattan, NY", "url": "/homes/Manhattan-NY/" }],
  "email": "agent@example.com",
  "phone": "(917) 473-8368",
  "phones": { "cell": "...", "brokerage": "...", "business": "..." },
  "address": { "line1": "...", "city": "New York", "state": "NY", "postalCode": "10001", "full": "..." },
  "licenses": {
    "Real estate licenses": [{ "License No.": "10301...", "issued by": "NY", "status": "Active", "expiration": "2026-...-..." }],
    "otherLicenses": []
  },
  "salesStats": {
    "countAllTime": 234, "countLastYear": 45,
    "priceRangeThreeYearMin": 350000, "priceRangeThreeYearMax": 12500000,
    "averageValueThreeYear": 1850000,
    "statsIncludeTeam": true, "pastSalesTotal": 234
  }
}
```

#### Lender record (no allowlist)

```json
{
  "id": "...",
  "name": "Jane Banker",
  "screenName": "janebanker",
  "url": "https://www.zillow.com/lender-profile/janebanker",
  "avatar": "...",
  "business": "First Republic",
  "nmlsLicense": "1234567",
  "phone": "(212) 555-0100",
  "email": "jane@example.com",
  "address": { "line1": "...", "city": "New York", "state": "NY", "postalCode": "10001" },
  "rating": 4.9,
  "reviews": { "count": 87 },
  "languages": ["English", "Spanish"],
  "specialties": ["First-time home buyers"]
}
```

***

### 🪜 How the smart proxy ladder works

```
   ┌──────────┐    blocked?    ┌──────────────┐    blocked?    ┌──────────────┐
   │ 🌐 Direct │ ─────────────▶ │ 🏢 Datacenter │ ─────────────▶ │ 🏠 Residential│ × 3 retries
   └──────────┘                └──────────────┘                └──────────────┘
```

- **Default** — every request goes out **direct** (no proxy spend).
- On HTTP `403`/`429`/captcha/empty-body, the actor switches to **Apify Datacenter**.
- If datacenter also gets blocked, it switches to **Apify Residential** with **3 retries**.
- Once escalated, the actor **stays** on the new tier for the rest of the run.
- You can override the starting tier in `proxyConfiguration` — explicit choices are respected.

Every escalation is logged with a clear ⛔ → 🏠 message.

***

### 🚀 How to Use (Apify Console)

1. Log in at [console.apify.com](https://console.apify.com) → **Actors**.
2. Open **🏠 Zillow Agents & Lenders Finder**.
3. Pick **Operation** = `agents` or `lenders`.
4. Set a **Location** (e.g. `New York`) and/or paste profile URLs/`@names`.
5. Tune filters (specialty, language, top-agent, …) if you want.
6. Click **Start** ▶️.
7. Watch the live log — every scraped profile prints with name / rating / location.
8. Open the **Output** tab → switch between **Overview**, **Agent Detail**, **Lenders** views.
9. Export as JSON / CSV / XLSX from the Output tab.

***

### 🤖 Use via API

```bash
curl -X POST "https://api.apify.com/v2/acts/<USER>~zillow-agents-finder/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "operation": "agents",
       "location": "New York",
       "limit": 10,
       "agent_detail_info": false
     }'
```

***

### 💼 Best Use Cases

- 🎯 Lead generation for real estate SaaS
- 📈 Market intelligence on top agents per metro
- 🏘️ Building an agent directory for a real-estate portal
- 💰 Comparing lender NMLS coverage by language / specialty
- 📊 Tracking agent sales-volume trends across markets

***

### 💵 Pricing

This actor uses Apify's **Pay-Per-Event** model. You're billed per successfully scraped profile (`result-item`) plus the standard platform startup. Limits are respected: if your spend limit is reached mid-run, the actor exits cleanly with whatever was already pushed to the dataset.

***

### ❓ FAQ

**Q: Does it work without a proxy?**
A: Yes — that's the default. It only spends proxy budget if Zillow blocks the direct request.

**Q: What if Zillow rate-limits my run?**
A: The actor escalates automatically (Direct → Datacenter → Residential, 3 retries) and stays on the highest tier reached. You'll see ⛔ → 🏠 messages in the log.

**Q: Can I get just the screen names without the full profile?**
A: Not currently — the actor always fetches the profile page to pull phone / rating / business. Toggle `agent_detail_info: false` to keep the dataset slim.

**Q: Can I search a sub-tab like `reviews` or `sold`?**
A: Yes — prefix the screen name with `@` and append the sub-tab, e.g. `@Matthew Bizzarro/reviews`, or pass the full URL with the sub-tab path.

**Q: What languages and specialties are supported?**
A: 24 languages and 12 specialties — pick from the dropdowns in the input form, or pass the slug directly.

**Q: How do I narrow lender output?**
A: Pick the field names you want from the `Lender Field Allowlist` dropdown (e.g. `["companyName","officePhone","nmlsType","rating","totalReviews"]`). Empty = every field.

***

### 📣 Support & Feedback

Found a bug or want a new filter? Open an issue on the actor's Issues tab in the Apify Console.

***

### ⚠️ Cautions / Legal

- Data is collected only from **publicly available** profile pages on Zillow.
- This actor does **not** access private or authenticated content.
- You are responsible for legal compliance (GDPR, CCPA, anti-spam laws, Zillow ToS).
- Honor reasonable rate limits — being a good citizen reduces blocks too.

# Actor input Schema

## `urls` (type: `array`):

Bulk input — each item can be:
• Full profile URL — `https://www.zillow.com/profile/REMAX EDGE`
• Profile sub-tab URL — `https://www.zillow.com/profile/<name>/sales|rentals|sold|reviews`
• Screen name with `@` prefix — `@REMAX EDGE` (optionally `@REMAX EDGE/reviews`)
• Agent or lender name (free text) — runs a directory search

Leave empty to run a pure location-based crawl.

## `operation` (type: `string`):

Which Zillow directory to target.

## `location` (type: `string`):

City / state used as the geo seed for every directory search (e.g. `New York`, `Los Angeles, CA`). Required unless every URL entry is a direct profile URL or `@screenName`.

## `limit` (type: `integer`):

Maximum number of profiles returned across all queries. Set `0` for unlimited.

## `agent_detail_info` (type: `boolean`):

When ✅ — return the full agent profile (sales stats, licenses, service areas, address, phones, email, …). When ❌ — return the compact card shape (id, name, screenName, url, avatar, business, location, phone, rating, reviews.count).

## `specialty` (type: `string`):

Single specialty filter for the agents directory. Accepts a numeric code or a Zillow slug.

## `language` (type: `string`):

Single language filter (display name).

## `is_top_agent` (type: `boolean`):

Filter to Zillow-flagged top agents (agents only).

## `is_buying` (type: `boolean`):

Filter to agents who focus on buyers (agents only).

## `is_selling` (type: `boolean`):

Filter to agents who focus on sellers (agents only).

## `sort_lenders` (type: `string`):

Sort order for the lender directory (lenders only).

## `lender_fields` (type: `array`):

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.

## `proxyConfiguration` (type: `object`):

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.

## Actor input object example

```json
{
  "urls": [],
  "operation": "agents",
  "location": "New York",
  "limit": 20,
  "agent_detail_info": false,
  "specialty": "",
  "language": "",
  "is_top_agent": false,
  "is_buying": false,
  "is_selling": false,
  "sort_lenders": "relevance",
  "lender_fields": [],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "urls": [],
    "lender_fields": [],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scraperx/zillow-agents-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "urls": [],
    "lender_fields": [],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("scraperx/zillow-agents-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "urls": [],
  "lender_fields": [],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scraperx/zillow-agents-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=scraperx/zillow-agents-finder",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/TgonRChUA8nYf5pxh/builds/kNfjWauLoEshIVcPD/openapi.json