{
  "openapi": "3.0.1",
  "info": {
    "title": "Realtor.com Agents Scraper — Contacts, Reviews & B2B Leads",
    "description": "Scrape realtor.com real-estate agents by US city or ZIP with contacts — direct & office phone · websites · office address · license number · social media, broker & client reviews per agent. Incremental mode tracks new and changed agents across scheduled runs.",
    "version": "0.1",
    "x-build-id": "IfcbrFf5LOYtTIhHk"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~realtor-agents-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-realtor-agents-scraper",
        "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/blackfalcondata~realtor-agents-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-realtor-agents-scraper",
        "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/blackfalcondata~realtor-agents-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-realtor-agents-scraper",
        "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": {
          "maxResults": {
            "title": "💯 Max Results",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum agents to return (0 = full directory).",
            "default": 200
          },
          "startUrls": {
            "title": "🔗 realtor.com URLs",
            "type": "array",
            "description": "Paste realtor.com agent pages: a Find-a-Realtor search (e.g. https://www.realtor.com/realestateagents/boca-raton_fl or .../realestateagents/33139) or an agent profile (https://www.realtor.com/realestateagents/<profile id>). Combined with the locations above.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "mode": {
            "title": "⚙️ Mode",
            "type": "string",
            "description": "Fixed to agents for this actor.",
            "default": "agents"
          },
          "agentLocations": {
            "title": "📍 Locations",
            "type": "array",
            "description": "One or more locations to find agents in: \"City, ST\" (e.g. \"Boca Raton, FL\"), \"City, State\" (e.g. \"Austin, Texas\"), a ZIP code (e.g. \"90210\") or a whole state (e.g. \"Delaware\" or \"DE\"). Each is searched independently; a state is searched city by city, largest first, until Max Results is reached.",
            "items": {
              "type": "string"
            }
          },
          "agentStates": {
            "title": "🗺️ Whole States",
            "type": "array",
            "description": "Whole US states to find agents in (e.g. \"Delaware\" or \"DE\"). Each state is searched city by city — every incorporated city and town, largest first — until Max Results is reached. Agents listed in several cities are returned once.",
            "items": {
              "type": "string"
            }
          },
          "agentType": {
            "title": "🤝 Agent Type",
            "enum": [
              "BUYER",
              "SELLER",
              "BOTH"
            ],
            "type": "string",
            "description": "Which side the agent represents. Both = agents of either side (each agent once).",
            "default": "BUYER"
          },
          "agentLanguages": {
            "title": "🗣️ Languages",
            "type": "array",
            "description": "Filter by spoken language (e.g. \"spanish\", \"mandarin\").",
            "items": {
              "type": "string"
            }
          },
          "agentName": {
            "title": "👤 Agent Name",
            "type": "string",
            "description": "Find agents by name (full or partial, e.g. \"Jeff Tricoli\"). Works with a location, or on its own to search all of realtor.com."
          },
          "agentPriceMin": {
            "title": "💲 Home Price From (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "Only agents who handle homes at or above this price."
          },
          "agentPriceMax": {
            "title": "💲 Home Price To (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "Only agents who handle homes at or below this price."
          },
          "agentSort": {
            "title": "↕️ Sort By",
            "enum": [
              "RELEVANT_AGENTS",
              "MOST_RECENT_ACTIVITY",
              "MOST_SALES"
            ],
            "type": "string",
            "description": "Order agents the way realtor.com's Find-a-Realtor does.",
            "default": "RELEVANT_AGENTS"
          },
          "minRating": {
            "title": "⭐ Minimum Rating",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "Only agents with at least this average star rating (e.g. 4.5). Agents without a rating are left out when set."
          },
          "minReviews": {
            "title": "💬 Minimum Reviews",
            "minimum": 0,
            "type": "integer",
            "description": "Only agents with at least this many reviews."
          },
          "minRecentSales": {
            "title": "🏷️ Minimum Sales (last 12 months)",
            "minimum": 0,
            "type": "integer",
            "description": "Only agents with at least this many homes sold in the last 12 months."
          },
          "minListingsForSale": {
            "title": "🏠 Minimum Active Listings",
            "minimum": 0,
            "type": "integer",
            "description": "Only agents with at least this many homes for sale right now."
          },
          "brokerageName": {
            "title": "🏢 Brokerage / Office",
            "type": "string",
            "description": "Only agents whose brokerage or office name contains this text (e.g. \"Keller Williams\")."
          },
          "agentSpecializations": {
            "title": "🎯 Specializations",
            "type": "array",
            "description": "Only agents listing at least one of these specializations (text match, e.g. \"luxury\", \"first time\"). Uses the contact profile, so contact details are included.",
            "items": {
              "type": "string"
            }
          },
          "onlyWithPhone": {
            "title": "📞 Only Agents With a Phone Number",
            "type": "boolean",
            "description": "Leave out agents without a phone number on their profile.",
            "default": false
          },
          "onlyWithEmail": {
            "title": "✉️ Only Agents With an Email",
            "type": "boolean",
            "description": "Leave out agents with no email address (implies the email lookup).",
            "default": false
          },
          "enrichAgentContacts": {
            "title": "📇 Enrich Agent Contacts",
            "type": "boolean",
            "description": "Fetch each agent's full contact profile — direct & office phone, website, office address, license number, and social media. On by default.",
            "default": true
          },
          "includeAgentEmail": {
            "title": "✉️ Include Agent Email",
            "type": "boolean",
            "description": "Look up each agent's email address (taken from the agent's own listings — agents with no listings have none). Adds one lookup per agent, so runs take a little longer.",
            "default": false
          },
          "includeAgentListings": {
            "title": "🏠 Include Agent Listings",
            "type": "boolean",
            "description": "Add each agent's homes currently for sale (address, price, beds, baths, size, photo and link) plus their total number of active listings. Adds one lookup per agent, so runs take a little longer.",
            "default": false
          },
          "maxListingsPerAgent": {
            "title": "🔢 Listings per Agent",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "How many of each agent's homes for sale to include when Include Agent Listings is on. The total count is always given.",
            "default": 10
          },
          "includeAgentReviews": {
            "title": "💬 Include Agent Reviews & Testimonials",
            "type": "boolean",
            "description": "Add each agent's review and testimonial texts with their ratings (reviewer name, relationship, transaction year, the agent's reply). Costs about one extra request per agent that has reviews, so runs take a little longer. No extra charge.",
            "default": false
          },
          "maxReviewsPerAgent": {
            "title": "🔢 Reviews per Agent",
            "minimum": 0,
            "maximum": 500,
            "type": "integer",
            "description": "How many reviews and testimonials to include per agent when Include Agent Reviews & Testimonials is on, newest first. 0 = all.",
            "default": 10
          },
          "includeRepresentationCounts": {
            "title": "⚖️ Include Buyer/Seller Split",
            "type": "boolean",
            "description": "Split each agent's sales over the last 24 months into deals where they listed the home (seller side) and deals where they represented the buyer. Adds one lookup per agent, so runs take a little longer.",
            "default": false
          },
          "compact": {
            "title": "📦 Compact Output",
            "type": "boolean",
            "description": "Output only core agent fields (for AI-agent / MCP workflows).",
            "default": false
          },
          "excludeEmptyFields": {
            "title": "🧹 Exclude Empty Fields",
            "type": "boolean",
            "description": "Drop null / empty-string / empty-array fields from each record.",
            "default": false
          },
          "notifyOnlyChanges": {
            "title": "🔄 Notify Only New/Updated",
            "type": "boolean",
            "description": "Reserved for incremental agent monitoring (coming soon); has no effect in the current directory-snapshot mode.",
            "default": false
          },
          "notificationLimit": {
            "title": "📊 Max Agents Per Notification",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of agents included in each notification message (1–20).",
            "default": 5
          },
          "telegramToken": {
            "title": "🔑 Telegram Bot Token",
            "type": "string",
            "description": "Telegram bot token (from @BotFather). Required for Telegram notifications."
          },
          "telegramChatId": {
            "title": "💬 Telegram Chat ID",
            "type": "string",
            "description": "Telegram chat or channel ID where alerts are sent."
          },
          "discordWebhookUrl": {
            "title": "🎮 Discord Webhook URL",
            "type": "string",
            "description": "Discord incoming webhook URL."
          },
          "slackWebhookUrl": {
            "title": "💼 Slack Webhook URL",
            "type": "string",
            "description": "Slack incoming webhook URL."
          },
          "whatsappPhoneNumberId": {
            "title": "📞 WhatsApp Phone Number ID",
            "type": "string",
            "description": "WhatsApp Business phone number ID (numeric, from Meta dashboard). Required when whatsappAccessToken is set."
          },
          "whatsappAccessToken": {
            "title": "📱 WhatsApp Access Token",
            "type": "string",
            "description": "WhatsApp Cloud API access token from Meta Business Manager. The recipient must have messaged your business number within the last 24 hours."
          },
          "whatsappTo": {
            "title": "📲 WhatsApp Recipient",
            "type": "string",
            "description": "Recipient phone number in E.164 format without + (e.g. \"33612345678\"). Recipient must have messaged your business number within the last 24 hours."
          },
          "webhookUrl": {
            "title": "🪝 Generic Webhook URL",
            "type": "string",
            "description": "Universal escape hatch for n8n / Make / Zapier / custom HTTP backends. Receives a JSON POST per run."
          },
          "webhookHeaders": {
            "title": "🪝 Webhook Headers (optional)",
            "type": "object",
            "description": "Additional HTTP headers sent with the generic webhook POST."
          },
          "appConnector": {
            "title": "📤 Send results to a connected app",
            "type": "string",
            "description": "Optional. Pick a connected app under Settings → API & Integrations to receive your results. A run-summary is written to the connected app; support is best-effort as Apify expands its connector catalog."
          },
          "mcpIssueTeam": {
            "title": "🏷️ Issue tracker team",
            "type": "string",
            "description": "Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one."
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}