{
  "openapi": "3.0.1",
  "info": {
    "title": "US Franchise Registration & FDD Leads Scraper",
    "description": "Search any US franchisor or brand and get its official state franchise filings with every FDD (Franchise Disclosure Document) as a PDF link, by year and version, plus status, file numbers and a lead score. Minnesota CARDS + Wisconsin DFI. Independent tool, not affiliated with any state regulator.",
    "version": "0.1",
    "x-build-id": "Gq7ZPCJe1yQDkbtsO"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapesage~us-franchise-registrations-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapesage-us-franchise-registrations-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~us-franchise-registrations-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapesage-us-franchise-registrations-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~us-franchise-registrations-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapesage-us-franchise-registrations-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": {
          "franchisorName": {
            "title": "Franchisor or brand name (search)",
            "type": "string",
            "description": "Search one franchisor or brand. Matches the franchisor's legal name OR any of its brand / trade names, so a brand works on its own: 'Atwell Suites' finds Holiday Hospitality Franchising, LLC with only its Atwell Suites filings. Whole words in any order; accents, case, punctuation and Inc/LLC are ignored (see 'Name matching'). Leave blank to browse the newest registrations."
          },
          "searchTerms": {
            "title": "More franchisor or brand names",
            "type": "array",
            "description": "Several franchisors or brands in one run, one per line (each is matched like the field above). Every record says which search it matched in 'matchedSearchTerms'.",
            "items": {
              "type": "string"
            }
          },
          "brandName": {
            "title": "Brand filter",
            "type": "string",
            "description": "Keep only this brand's filings (brand / trade name only, not the franchisor's legal name). Combine with the search above to pick one brand of a multi-brand franchisor, e.g. franchisor 'Holiday Hospitality' + brand 'Atwell'."
          },
          "nameMatch": {
            "title": "Name matching",
            "enum": [
              "words",
              "contains",
              "exact"
            ],
            "type": "string",
            "description": "How a search must match a name. 'All words' (recommended): every word must appear as a whole word, so 'Spark' does not return Sparkle or Mister Sparky. 'Contains': the text may appear anywhere in the name, like the state registry's own search. 'Exact': the whole name must equal the search.",
            "default": "words"
          },
          "filingYearFrom": {
            "title": "Filing year from",
            "minimum": 1990,
            "maximum": 2100,
            "type": "integer",
            "description": "Earliest filing year to include. With a name search every year is included unless you set this; a browse with no name defaults to the current year."
          },
          "filingYearTo": {
            "title": "Filing year to",
            "minimum": 1990,
            "maximum": 2100,
            "type": "integer",
            "description": "Latest filing year to include. Defaults to the current year. Documents outside the period are left out of each record, so 'filingYearFrom: 2023, filingYearTo: 2024' returns only that period's filings and FDDs."
          },
          "onlyWithFdd": {
            "title": "Only franchisors with an FDD",
            "type": "boolean",
            "description": "Keep only franchisors with at least one Franchise Disclosure Document (FDD) in the selected period. FDD links are in 'fddDocuments', 'fddDocumentUrls' and 'latestFddUrl'.",
            "default": false
          },
          "states": {
            "title": "States",
            "type": "array",
            "description": "Official state franchise regulators to query. MN = Minnesota Commerce CARDS (every filing, with the FDD PDFs). WI = Wisconsin DFI (registration status, expiry and the filing contact's email/phone; searched by name, see the README).",
            "items": {
              "type": "string",
              "enum": [
                "MN",
                "WI"
              ],
              "enumTitles": [
                "Minnesota (Commerce CARDS)",
                "Wisconsin (DFI)"
              ]
            }
          },
          "mnDocumentType": {
            "title": "Minnesota document type (filter)",
            "enum": [
              "Acknowledgement",
              "Additional funds request",
              "Advertisement",
              "Advertisement Notice",
              "Application and Certification (Form A)",
              "Application and Forms",
              "Application, Certification, Consent to Service of Process",
              "Application (Form A)",
              "Auditor's Consent (Form F)",
              "Bond",
              "Bond email",
              "Certification Page (Form A)",
              "Clean FDD",
              "Consent to Service of Process (Form C)",
              "Corporate Acknowledgement",
              "Cost and Sources of Funds (Form B)",
              "Cover letter",
              "Cover Letter and Application",
              "Cover letter response",
              "Deficiency Notice",
              "Deferral",
              "Escrow Agreement",
              "Exemption 80C.03(e)",
              "Exemption 80C.03(g)",
              "Final FDD",
              "Financial Statements",
              "Franchise agreement",
              "Franchise Exemption Effectiveness",
              "Guarantee of Performance (Form E)",
              "Marked FDD",
              "Order Amending Registration",
              "Order of Cancellation",
              "Order of Registration and Instructions",
              "Order of Renewed Registration",
              "Order of Renewed Registration w Amendment",
              "Order Reinstating Registration",
              "Order of Withdrawal - 120 Day",
              "Order of Withdrawal - Incomplete submission",
              "Order of Withdrawal - Reminder",
              "Order Vacating Cancellation",
              "Other",
              "Other Letter",
              "Post-effective Amendment",
              "Pre-effective amendment",
              "Refund letter",
              "Rejection Notice",
              "Response Letter",
              "Revised FDD - Clean",
              "Revised FDD - Marked Up",
              "Sellers Disclosure Document Notice",
              "Withdrawal - Franchisor Request"
            ],
            "type": "string",
            "description": "Optional: only Minnesota filings of this document type, as Minnesota labels it. Many FDDs are filed as type 'Other' with the label in the notes, so for FDDs use 'Only franchisors with an FDD' instead."
          },
          "statusFilter": {
            "title": "Registration status filter",
            "type": "array",
            "description": "Keep only these registration statuses. Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "Registered",
                "On file",
                "Exempt",
                "Cancelled",
                "Withdrawn",
                "Rejected",
                "Expired"
              ],
              "enumTitles": [
                "Registered",
                "On file",
                "Exempt (large-franchisor exemption)",
                "Cancelled",
                "Withdrawn",
                "Rejected",
                "Expired"
              ]
            },
            "default": []
          },
          "activeOnly": {
            "title": "Active registrations only",
            "type": "boolean",
            "description": "Keep only franchisors with a currently active registration: registered, on file or exempt, and not expired.",
            "default": false
          },
          "newRegistrationsOnly": {
            "title": "New registrations only",
            "type": "boolean",
            "description": "Keep only franchisors registered / renewed within the window below — the freshest expansion-intent leads.",
            "default": false
          },
          "registeredWithinDays": {
            "title": "Registered within (days)",
            "minimum": 1,
            "maximum": 3650,
            "type": "integer",
            "description": "Window used by 'New registrations only'.",
            "default": 365
          },
          "expiringWithinDays": {
            "title": "Expiring within (days)",
            "minimum": 1,
            "maximum": 1825,
            "type": "integer",
            "description": "Keep only registrations expiring within this many days. Expiry dates come from Wisconsin, so this needs WI in 'States'."
          },
          "hasContactInfo": {
            "title": "Only records with contact email or phone",
            "type": "boolean",
            "description": "Keep only franchisors with a contact email or phone. Contacts come from Wisconsin's filing pages, so this needs WI in 'States'.",
            "default": false
          },
          "fetchContactDetails": {
            "title": "Fetch contact details (Wisconsin)",
            "type": "boolean",
            "description": "Enrich Wisconsin records with the detail page: business address, contact name + email + phone + fax, organization type and multi-state footprint.",
            "default": true
          },
          "consolidateByFranchisor": {
            "title": "Consolidate by franchisor",
            "type": "boolean",
            "description": "Output one record per franchisor, merging its registrations across states (recommended). Turn off for one record per franchisor per state.",
            "default": true
          },
          "maxResults": {
            "title": "Max results",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Maximum number of franchisor records to deliver (each record is one charge)."
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "newest",
              "leadScore"
            ],
            "type": "string",
            "description": "Order results by newest filing date or by lead score.",
            "default": "newest"
          },
          "deduplicateResults": {
            "title": "Deduplicate results",
            "type": "boolean",
            "description": "Remove duplicate franchisor records within a run.",
            "default": true
          },
          "monitorMode": {
            "title": "Monitor mode (only new since last run)",
            "type": "boolean",
            "description": "Emit only franchisors not seen on previous runs with the same monitor key. Ideal with Apify Schedules to capture only newly registered / renewed franchisors. State is stored separately from Apify's scheduler so the two do not conflict.",
            "default": false
          },
          "monitorKey": {
            "title": "Monitor key",
            "type": "string",
            "description": "Namespace for monitor-mode memory. Use distinct keys for distinct saved searches.",
            "default": "default"
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Optional. The state portals are reachable directly from Apify; a proxy is not required.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}