{
  "openapi": "3.0.1",
  "info": {
    "title": "BBB Scraper - Business Leads, Ratings & Accreditation",
    "description": "Scrape Better Business Bureau businesses by category & city: name, BBB rating (A+ to F), accreditation, phone, full address, website, email, years in business, complaints, customer reviews & owner contacts. US & Canada B2B lead generation. Export JSON, CSV, Excel.",
    "version": "1.0",
    "x-build-id": "rtr3wmjigfKbG2iA3"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapesage~bbb-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapesage-bbb-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/scrapesage~bbb-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapesage-bbb-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/scrapesage~bbb-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapesage-bbb-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": {
          "searchTerms": {
            "title": "Search terms (category or business name)",
            "type": "array",
            "description": "What to search for on BBB - a category or keyword such as <code>Plumbers</code>, <code>Roofing Contractors</code>, <code>Auto Repair</code>, <code>HVAC</code>, <code>Lawyers</code>, or a specific business name. Each term is combined with every location below.",
            "items": {
              "type": "string"
            }
          },
          "locations": {
            "title": "Locations (city & state / province)",
            "type": "array",
            "description": "Where to search - a <code>City, ST</code> string (<code>Austin, TX</code>, <code>Chicago, IL</code>), a ZIP/postal code, or a US state / Canadian province. Each location is combined with every search term. Leave empty to search nationwide for a named business.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs (optional)",
            "type": "array",
            "description": "Direct BBB URLs to scrape in addition to searches: search pages (<code>https://www.bbb.org/search?find_text=...&find_loc=...</code>), category pages (<code>https://www.bbb.org/us/tx/austin/category/plumber</code>), near-me pages, or business profile pages (<code>https://www.bbb.org/us/.../profile/...</code>). Profile URLs always return the full profile.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "maxResults": {
            "title": "Max businesses",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum number of businesses to scrape across all searches. Use <code>0</code> for no limit. BBB lists up to 225 businesses per search order; when you ask for more, the actor also reads BBB's other orders (distance, rating, A–Z, Z–A), so one search term + location can reach several hundred businesses.",
            "default": 100
          },
          "maxResultsPerSearch": {
            "title": "Max businesses per search",
            "minimum": 0,
            "type": "integer",
            "description": "Optional cap per individual search term + location combination. <code>0</code> = no per-search cap (still bounded by Max businesses).",
            "default": 0
          },
          "accreditedOnly": {
            "title": "BBB-accredited businesses only",
            "type": "boolean",
            "description": "Keep only businesses that are BBB Accredited (paying members that meet BBB standards). Uses BBB's own accredited filter, so a search returns accredited businesses only.",
            "default": false
          },
          "minRating": {
            "title": "Minimum BBB rating",
            "enum": [
              "any",
              "A+",
              "A",
              "A-",
              "B+",
              "B",
              "B-",
              "C+",
              "C",
              "C-",
              "D+",
              "D",
              "D-"
            ],
            "type": "string",
            "description": "Keep only businesses at or above this BBB letter rating. Businesses BBB has not graded are left out when a minimum is set.",
            "default": "any"
          },
          "includeDetails": {
            "title": "Scrape full business details",
            "type": "boolean",
            "description": "Open each business profile for the complete record: the email BBB holds for the business, website, social profiles, owner / principal contacts with titles, years in business, business start / incorporation / accreditation dates, legal entity type, products & services, licences, hours, service area (cities, counties, ZIP codes), other locations, complaint and review counts, photos and the full \"About\" overview. Adds one request per business.",
            "default": false
          },
          "includeReviews": {
            "title": "Include customer reviews",
            "type": "boolean",
            "description": "Add the business's BBB customer reviews, newest first: reviewer, star rating, date, full text and the business's reply. Turns on full details (the reviews page carries the full profile too).",
            "default": false
          },
          "maxReviewsPerBusiness": {
            "title": "Max reviews per business",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many customer reviews to keep per business when \"Include customer reviews\" is on (BBB pages them 10 at a time). Only reviews with text or a star rating are returned and billed.",
            "default": 8
          },
          "enrichContacts": {
            "title": "Enrich emails & socials from business website",
            "type": "boolean",
            "description": "For businesses that list a website, also visit it (home + contact/about, up to 3 pages) and add the contact emails, phone numbers, contact-form URL and social profiles (LinkedIn, Instagram, Facebook, X, YouTube, TikTok) it publishes. Template and placeholder addresses are filtered out. Turns on full details.",
            "default": false
          },
          "monitorMode": {
            "title": "Monitor mode - only output new businesses",
            "type": "boolean",
            "description": "Remember businesses delivered on previous runs (in a named key-value store) and output only businesses that are new or changed (rating, accreditation or phone) since last time. Perfect for scheduled lead pipelines - pair with Apify Schedules to drip only fresh leads into your CRM.",
            "default": false
          },
          "monitorKey": {
            "title": "Monitor key",
            "type": "string",
            "description": "Names the persistent monitor store so you can keep separate watch-lists (e.g. <code>austin-plumbers</code>). Reuse the same key across scheduled runs to keep deduplicating against history.",
            "default": "default"
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 12,
            "type": "integer",
            "description": "How many business profiles to fetch in parallel. The default is tuned for speed and reliability.",
            "default": 5
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Leave this at the default: the actor routes every request itself (search pages over Apify datacenter proxies, business profiles over residential IPs in the country set here, US by default) and switches routes automatically when BBB pushes back. Add your own proxy URLs only if you must use your own proxies.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ],
              "apifyProxyCountry": "US"
            }
          },
          "urlsFromFile": {
            "title": "Import URLs from a file",
            "type": "string",
            "description": "Paste a list of URLs (one per line), OR one link to a .txt/.csv file, Google Sheet or Google Drive file containing them. Lets you import many Start URLs at once instead of typing each. Google Sheet/Drive share links are handled automatically."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}