# Zillow Agent Search

<p>Find real estate agents in a US city or ZIP code. Each agent carries a name, brokerage, rating, review count, sales figures for the last 12 months, a team flag and the ids the other agent endpoints use.</p><h2>Filters</h2><p>Narrow the list by specialty, spoken language, top-agent status, and whether the agent works with buyers or sellers. Several languages combine: an agent has to speak all of them. A specialty or language Zillow does not offer is rejected with a 422 instead of being ignored. The response lists the filters that were applied.</p><h2>Paging</h2><p>Each page holds up to 16 agents. The agent list stops at page 25, so page 26 and above are rejected. <code>total_results</code> is the number of agents that match, not the number you can page through.</p><h2>Next steps</h2><p>Pass <code>screen_name</code> to the agent profile endpoint, or <code>encoded_zuid</code> to the agent reviews, sold and listings endpoints. Costs 1 credit per request.</p>

- **Documentation:** [https://scrappa.co/docs/zillow-api/zillow_agents](https://scrappa.co/docs/zillow-api/zillow_agents)
- **API group:** Zillow API
- **Endpoint:** `GET https://scrappa.co/api/zillow/agents`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `location` | string | Yes | City and state such as "Seattle, WA", or a five digit ZIP code. |
| `page` | integer | No | Page number, 1 to 25. |
| `specialties[]` | array | No | One or more of first-time-home-buyers, investment-properties, rentals, military-or-veterans, luxury-homes, new-construction, property-management, senior-communities, relocation, foreclosure, lot-or-land, vacation-short-term-rentals. |
| `languages[]` | array | No | Spoken languages in lower case, for example spanish or french. The agent has to speak all of them. |
| `is_top_agent` | boolean | No | Only agents Zillow marks as top agents. |
| `is_buying` | boolean | No | Only agents who work with buyers. |
| `is_selling` | boolean | No | Only agents who work with sellers. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/zillow/agents?location=Seattle%2C+WA&specialties%5B0%5D=luxury-homes&page=1"
```

## Example response

```json
{
    "data": {
        "location": "Seattle, WA",
        "page": 1,
        "max_page": 25,
        "total_results": 1398,
        "count": 16,
        "filters_applied": [
            {
                "filter": "SPECIALTIES",
                "value": "luxury-homes"
            }
        ],
        "agents": [
            {
                "encoded_zuid": "X1-ZUy9ks3xfgesqx_ahuyq",
                "screen_name": "everydoorrealestate",
                "name": "The Every Door Team",
                "brokerage": "Every Door Real Estate",
                "is_top_agent": true,
                "is_team": true,
                "rating": 5,
                "review_count": 2569
            }
        ]
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 400 | The request validation failed | A query parameter is missing, malformed, or outside its documented range. This is the only Zillow response that carries no error code: the body has a message and a field list and nothing else, so match it on the 400 status. |
| 422 | No research dataset matches that family and geography | The requested research file does not exist for the combination given. |
| 422 | More than one research dataset matches | The family, geography and variant given do not identify a single research file. |
| 422 | No accuracy figures are published for that region | The named state or metropolitan area publishes no estimate-accuracy data. |
| 422 | The upstream rejected the request | Zillow answered with a deterministic 4xx. |
| 422 | The building returned does not match the requested address | The decoded building token resolved to a building at a different address than the slug names. |
| 503 | The listing source answered with a block or rate-limit page | The request reached the source, but what came back was a challenge or rate-limit page rather than the data. |
| 503 | The listing source returned a server error | The request was served and answered with a 5xx. |
| 503 | The listing source did not answer in time | The request was sent and no answer came back before the deadline. |
| 503 | The request could not be sent | No approved exit could be reached, so the request never reached the listing source. |
| 503 | No approved exit is available | There was no usable approved exit to send the request through. |
| 503 | The upstream returned a document this integration cannot read | The publisher changed the shape of a response or served a document that is not the expected file. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)