{ "openapi": "3.0.1", "info": { "title": "FDD Item 19 Parser — Franchise AUV & Financial Performance", "description": "Search state franchise registries (Minnesota CARDS + Wisconsin DFI), download Franchise Disclosure Document PDFs, and extract Item 19 Financial Performance Representations — has-FPR flag, raw Item 19 text, every dollar figure, and best-effort average/median/high/low unit volume. No logins.", "version": "0.0", "x-build-id": "0wxOjGyORK68Ka89E" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/silentshadow55~fdd-item19-actor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-silentshadow55-fdd-item19-actor", "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/silentshadow55~fdd-item19-actor/runs": { "post": { "operationId": "runs-sync-silentshadow55-fdd-item19-actor", "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/silentshadow55~fdd-item19-actor/run-sync": { "post": { "operationId": "run-sync-silentshadow55-fdd-item19-actor", "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": { "franchiseNames": { "title": "Franchise names", "type": "array", "description": "One or more franchise or franchisor names to search for in the Minnesota CARDS registry (e.g. 'Jersey Mike's', 'Anytime Fitness'). Each name normally produces ONE record: the newest full FDD is downloaded and its Item 19 section parsed. CARDS matches franchise names by SUBSTRING, so a short string can match several franchisors. No document is billed twice in a run: repeated or whitespace-variant entries are collapsed before searching, and if two different names resolve to the same document it is delivered (and charged) once, with an unbilled log note naming the record that covers the other name. A name that returns nothing, that matches only non-FDD paperwork, or that is never reached because the maxFdds budget ran out also produces an unbilled log note, so no requested name ever disappears without explanation. Leave empty to use sweep mode (year + document type). You are billed per record returned, so maxFdds caps the cost.", "items": { "type": "string" } }, "year": { "title": "Filing year (sweep mode)", "type": "string", "description": "Sweep mode: pull a batch of FDDs filed in this year (e.g. '2026') instead of by name. Combine with documentType to narrow (e.g. all 'Clean FDD' filed in 2026). When combined with franchiseNames, restricts each name's results to that filing year. Sweep mode downloads only genuine full FDD document types; if a sweep matches rows but none of them is an FDD, nothing is downloaded or billed and an unbilled diagnostic explains why." }, "documentType": { "title": "Document type", "enum": [ "", "Clean FDD", "Final FDD", "Marked FDD", "Revised FDD - Clean" ], "type": "string", "description": "Restrict to a Minnesota CARDS document type. 'Clean FDD' (the default when unset) is the standard full disclosure document and the best choice for Item 19 extraction. Choose 'Any document type' to apply no filter — the actor still downloads only full FDD document types (Clean, Final, Revised or Marked FDD) and never bills an amendment, consent or deficiency notice as an FDD. Applies to both name search and sweep mode.", "default": "Clean FDD" }, "states": { "title": "States", "type": "array", "description": "Which state franchise registry to query. Minnesota CARDS is the source in this version: it offers full search, complete filing history, year sweeps and stable per-document PDF URLs, and because an FDD is a single national document most franchisors' disclosure documents are available there. 'MN' is the only supported value; support for a second registry (Wisconsin DFI) is planned for a later version. California and NASAA EFD are intentionally excluded because they block automated HTTP access.", "items": { "type": "string", "enum": [ "MN" ], "enumTitles": [ "Minnesota — CARDS (search, filing history, FDD PDFs)" ] }, "default": [ "MN" ] }, "maxFdds": { "title": "Max FDDs", "minimum": 1, "maximum": 200, "type": "integer", "description": "Hard cap on the number of FDD PDFs downloaded and parsed per run — a single global budget across all names. One downloaded PDF produces exactly one dataset record, so each parsed FDD is one billed result and this cap is also your hard cost cap. No document is downloaded or billed twice in a run (Minnesota documents are deduplicated by CARDS document id across every name you request). Failed searches/downloads are never written to the dataset (they are reported in the run log and status message) and do NOT consume it either. If the budget runs out before every requested name is searched, each unsearched name is named in the run log with the value to raise this to. FDDs are large (5-7 MB, 400-500 pages) and PDF text extraction is CPU-bound, so budget roughly 20-40 seconds per FDD at the default 4 GB memory. The default of 3 keeps a first run quick; raise it (up to 200) for batch sweeps and raise the run timeout to match.", "default": 3 }, "downloadPdfToKvs": { "title": "Save FDD PDFs to key-value store", "type": "boolean", "description": "Also store each downloaded FDD PDF in the run's default key-value store (key returned as pdf_bytes_kvs_key). Turn on if you want the raw PDF, not just the extracted Item 19 fields. Adds storage but does not change per-result billing.", "default": false }, "requestDelaySeconds": { "title": "Delay between requests (seconds)", "minimum": 0, "maximum": 10, "type": "integer", "description": "Politeness delay between HTTP requests to Minnesota CARDS. These are public government records with no published rate limit; 1-2 seconds is courteous. Lower values run faster but are less polite.", "default": 2 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxies for the HTTP requests. Minnesota CARDS is a public state-government site, so Apify Proxy (datacenter) is sufficient. Leave default unless the source rate-limits your IP.", "default": { "useApifyProxy": true } } } }, "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 } } }, "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 } } } } } } } } } }