Documentation

API Reference

Integrate 500K+ verified US real estate agent contacts into your CRM, marketing tools, or applications with our simple REST API.

60 requests/min

10,000 requests/month

SHA-256 hashed keys

Overview

The USAgentLeads API provides read-only access to our database of US real estate agent contacts. All responses are JSON. The API uses API key authentication and includes rate limiting and monthly quota tracking.

Protocol

HTTPS only

Format

JSON

Auth

API Key

Authentication

All API requests require a valid API key. Include your key in the request headers using one of these methods:

Option 1 — X-API-Key header (recommended)

curl -H "X-API-Key: sk_live_abc123..." \
  https://www.usagentleads.com/api/v1/agents

Option 2 — Bearer token

curl -H "Authorization: Bearer sk_live_abc123..." \
  https://www.usagentleads.com/api/v1/agents

Keep your API key secret

Never expose your API key in client-side code, public repos, or browser requests. Use it only in server-to-server calls. If compromised, revoke it immediately from your dashboard.

Base URL

https://www.usagentleads.com/api/v1

All endpoints are relative to this base URL. HTTPS is required — HTTP requests will be rejected.

GET /agents

Search and retrieve real estate agent contacts. Returns paginated results with name, email, phone, and state.

GET/api/v1/agents

Query Parameters

Parameter	Type	Status	Description
`state`	string	Optional	Two-letter US state code (e.g., `CA`, `TX`, `NY`). Filters agents by state.
`search`	string	Optional	Search agents by name or email. Case-insensitive partial match. Max 100 characters, alphanumeric and common punctuation only.
`page`	integer	Optional	Page number for pagination. Defaults to `1`.
`pageSize`	integer	Optional	Results per page. Accepted values: `25`, `50`, or `100`. Defaults to `25`.

Response Format

200 OKJSON

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Jane Smith",
      "email": "jane.smith@realty.com",
      "phone": "(310) 555-0142",
      "state": "California"
    },
    {
      "id": "e5f6g7h8-...",
      "name": "John Doe",
      "email": "john.doe@homes.com",
      "phone": "(212) 555-0198",
      "state": "New York"
    }
  ],
  "count": 42318,
  "page": 1,
  "totalPages": 1693,
  "quota": {
    "used": 148,
    "limit": 10000,
    "resets_at": "2026-04-01T00:00:00.000Z"
  }
}

Response Fields

Field	Type	Description
`data`	array	Array of agent objects with id, name, email, phone, and state
`count`	integer	Total matching agents (across all pages)
`page`	integer	Current page number
`totalPages`	integer	Total pages available
`quota`	object	Monthly quota status: used count, limit, and reset timestamp

Rate Limiting

The API enforces a per-key rate limit of 60 requests per minute. Rate limit status is returned in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute (60)
`X-RateLimit-Remaining`	Remaining requests in current window
`X-Monthly-Quota-Limit`	Monthly quota limit (10,000)
`X-Monthly-Quota-Remaining`	Remaining monthly requests

When rate limited, the API returns a 429 status. Wait and retry after the window resets (1 minute).

Monthly Quota

Each Pro API subscription includes 10,000 successful requests per calendar month. Only requests that return a 2xx or 3xx status code count toward your quota. Failed requests (4xx, 5xx) do not count.

Trial quota

During the 3-day free trial, API access is limited to 100 requests so you can test the integration. The full 10,000/month quota unlocks automatically when the trial ends and your subscription activates.

Quota resets on the 1st of each month at midnight UTC. Track your usage in real-time from the API Keys dashboard.

Error Handling

The API uses standard HTTP status codes. All error responses include a JSON body with an error field.

200 OK

Successful request. Agent data returned.

401 Unauthorized

Missing, invalid, revoked, or expired API key.

403 Forbidden

API key is valid but subscription is inactive or not on the Pro API plan.

429 Too Many Requests

Rate limit exceeded (60/min) or monthly quota depleted (10,000/month).

500 Server Error

Internal server error. Retry after a brief delay.

Error response exampleJSON

{
  "error": "Monthly API quota exceeded",
  "quota": {
    "used": 10000,
    "limit": 10000
  }
}

Code Examples

cURL

Get all California agents

curl -s \
  -H "X-API-Key: sk_live_abc123..." \
  "https://www.usagentleads.com/api/v1/agents?state=CA&pageSize=50" | jq .

JavaScript / TypeScript

Fetch agents with error handlingJavaScript

async function getAgents({ state, search, page = 1, pageSize = 25 }) {
  const params = new URLSearchParams({ page: String(page), pageSize: String(pageSize) });
  if (state) params.set("state", state);
  if (search) params.set("search", search);

  const res = await fetch(
    `https://www.usagentleads.com/api/v1/agents?${params}`,
    { headers: { "X-API-Key": process.env.USAGENTLEADS_API_KEY } }
  );

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error || `HTTP ${res.status}`);
  }

  return res.json();
}

// Usage
const { data, count, totalPages, quota } = await getAgents({ state: "TX" });
console.log(`Found ${count} agents (${quota.used}/${quota.limit} quota used)`);

Python

Paginate through all agents in a statePython

import requests
import os

API_KEY = os.environ["USAGENTLEADS_API_KEY"]
BASE_URL = "https://www.usagentleads.com/api/v1/agents"

def get_all_agents(state: str):
    agents = []
    page = 1

    while True:
        res = requests.get(
            BASE_URL,
            params={"state": state, "page": page, "pageSize": 100},
            headers={"X-API-Key": API_KEY},
        )
        res.raise_for_status()
        data = res.json()

        agents.extend(data["data"])
        if page >= data["totalPages"]:
            break
        page += 1

    return agents

# Fetch all California agents
ca_agents = get_all_agents("CA")
print(f"Fetched {len(ca_agents)} California agents")

Managing API Keys

API keys are managed from your dashboard. You can create up to 3 active keys per account.

Create a key

Go to Dashboard → API Keys → New Key. Copy the key immediately — it is shown only once.

Revoke a key

Click the trash icon next to any key. Revocation is instant and permanent — any request using the revoked key will receive a 401.

Monitor usage

The API Keys page shows a live usage bar, daily breakdown, and last-used timestamps for each key.

Security

We take API security seriously. Here's how your keys and data are protected:

API keys are SHA-256 hashed before storage — we never store plaintext keys
All traffic is encrypted via HTTPS (TLS 1.2+)
Keys are scoped to your account — you can only access your own subscription data
Revoked keys are rejected immediately at the authentication layer
Per-key rate limiting prevents abuse (60 requests/minute)
Row-level security (RLS) enforced at the database level
Input validation on all query parameters (state codes, search terms, pagination)

Ready to get started?

Subscribe to the Pro API plan, create your first API key, and start querying 500K+ agents in minutes.

Get Pro API — $79/mo Go to API Keys