# Massachusetts Secretary of State Business Search Scraper (`crawlerbros/massachusetts-sos-scraper`) Actor Search the Massachusetts Corporations Division (Secretary of the Commonwealth) business registry by entity name, officer/agent name, or identification number. Get entity type, status, registered agent, principal office address, and officers/directors. - **URL**: https://apify.com/crawlerbros/massachusetts-sos-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Agents, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Massachusetts Secretary of State Business Search Scraper Search the **Massachusetts Corporations Division** (Office of the Secretary of the Commonwealth) free public business registry. Search by entity name, officer/registered-agent name, or identification number, and get entity type, status, registered agent, principal office address, and the full officers/directors list. HTTP-only via the public `corp.sec.state.ma.us` search form — no login required. ### Why Massachusetts instead of Nevada? This actor was originally scoped against Nevada's SilverFlume/`esos.nv.gov` business entity search. Live verification found Nevada's search endpoint sits behind a **full Incapsula JavaScript challenge** — every request returns only a ~1 KB `_Incapsula_Resource` iframe, never the real page, regardless of client or retry strategy. That's a genuine bot-wall, not a flaky endpoint, so per this project's zero-cost policy it was replaced with an equivalent free state business registry: Massachusetts. Massachusetts sits behind Incapsula too, but only at the *cookie* level (see below) — no JavaScript execution is required to reach real data. ### Data Source & Usage Notes **Read this before running a large job.** - **Cookie-level bot protection, not a JS challenge.** The source is fronted by Imperva/Incapsula. A plain HTTP client is served a small interstitial on its first request; a second request on the *same* session (with the seeded `visid_incap_*`/`incap_ses_*` cookies) returns the real page. This actor performs that warm-up automatically at the start of every run. - **Conservative by design.** `maxItems` defaults to a small value and is capped at 100. Each result requires a separate detail-page fetch, so the actor adds deliberate delays between requests and only ever uses Apify's free datacenter (AUTO) proxy group — never a paid residential proxy — as an escalation fallback if a run gets rate-limited. - **Not affiliated with the Commonwealth of Massachusetts.** This is an independent third-party tool using the source's own public, no-login search form. ### What this actor does - **Four search modes:** - `byEntityName` — search by business/entity name, with the source's own **Begins with / Exact match / Full text / Soundex** match modes - `byIndividualName` — search by officer/registered-agent last name (+ optional first/middle name), returning every business entity where a matching individual is on file - `byIdentificationNumber` — direct lookup by the entity's Massachusetts identification number - `byFilingNumber` — direct lookup by a specific filing/document number (see caveat below) - **Full entity detail** — automatically follows through from search results to each entity's detail page - **Officers & directors** — full list with title, name, and address when on file - **Registered agent info** — name and full address when on file - **Derived status** — `Active` / `Inactive`, with the specific inactivity reason and date when applicable (e.g. involuntary dissolution, revocation, withdrawal) - **Empty fields are omitted** ### What's NOT included (and why) - **Stock/share class detail.** The detail page's "total number of shares" table is present on the page but is populated only for a small subset of entities and its values are frequently blank/placeholder characters in the source HTML itself — not reliably real data, so it's not scraped. - **Filing history documents.** Each entity's detail page links to a "View filings" list of document types (Annual Report, Articles of Merger, etc.) but not to the documents themselves (those require a separate paid-certificate request flow on the source). `byFilingNumber` mode looks up one specific filing/document number if you already have it (e.g. from correspondence with the Division); it does not enumerate an entity's full filing history. - **`filingNumber` results are narrow by nature.** A filing/document number identifies one specific transaction in the source's records, not the entity itself — searching an entity's own identification number in this mode will not resolve a filing. Use `byIdentificationNumber` to look up the entity itself. ### Output per entity - `entityName` - `entityType` — e.g. `Domestic Profit Corporation`, `Foreign Corporation`, `Domestic Limited Liability Company` - `identificationNumber` — Massachusetts identification number - `oldIdentificationNumber` — legacy identification number, when on file - `status` — `Active` or `Inactive` (derived from the presence of an inactivity date) - `statusReason` — the source's own inactivity label (e.g. `Date of Involuntary Dissolution by Court Order or by the SOC`), when inactive - `statusDate` — `YYYY-MM-DD`, when inactive - `dateOfOrganization` — `YYYY-MM-DD` - `dateOfRevival` — `YYYY-MM-DD`, when on file - `currentFiscalMonthDay`, `previousFiscalMonthDay` — e.g. `12/31` - `principalOfficeAddress` (combined) plus `principalOfficeStreet`, `principalOfficeCity`, `principalOfficeState`, `principalOfficeZip`, `principalOfficeCountry` - `registeredAgentName`, `registeredAgentAddress` - `officers` — array of `{ title, name, address }` - `jurisdictionState`, `jurisdictionCountry`, `jurisdictionDate` — state/country of incorporation and date, when on file (foreign entities only -- domestic MA entities omit this section on the source since they're organized under Massachusetts law by definition) - `mergedWith` — array of `{ entityName, date, sourceUrl }`, when on file (entities this one absorbed via merger, each linking to that now-inactive entity's own detail page) - `previousNames` — array of `{ previousName, date }`, when on file (the entity's legal name-change history) - `publiclyTraded` — `true` when the source's own checkbox is checked (omitted, not `false`, when unchecked/unknown) - `sourceUrl` — the entity's `CorpSummary.aspx` detail page URL - `recordType: "entity"`, `scrapedAt` ### Input | Field | Type | Default | Description | |---|---|---|---| | `mode` | string | `byEntityName` | `byEntityName` / `byIndividualName` / `byIdentificationNumber` / `byFilingNumber` | | `entityName` | string | `microsoft` | Search query (mode=byEntityName) | | `entityMatchMode` | string | `B` | `B` Begins with / `M` Exact match / `F` Full text / `S` Soundex (mode=byEntityName) | | `lastName` | string | – | Officer/agent last name (mode=byIndividualName, required) | | `firstName` | string | – | Officer/agent first name, optional (mode=byIndividualName) | | `middleName` | string | – | Officer/agent middle name, optional (mode=byIndividualName) | | `individualMatchMode` | string | `B` | Same 4 match modes as `entityMatchMode` (mode=byIndividualName) | | `identificationNumber` | string | – | Entity identification number (mode=byIdentificationNumber, required) | | `filingNumber` | string | – | Filing/document number (mode=byFilingNumber, required) | | `maxItems` | int | `10` | Hard cap (1–100) | | `proxyConfiguration` | object | AUTO proxy | Apify proxy config; always datacenter (AUTO), never residential | #### Example: search by entity name ```json { "mode": "byEntityName", "entityName": "microsoft", "entityMatchMode": "B", "maxItems": 10 } ```` #### Example: exact entity name match ```json { "mode": "byEntityName", "entityName": "MICROSOFT CORPORATION", "entityMatchMode": "M", "maxItems": 5 } ``` #### Example: search by officer/agent name ```json { "mode": "byIndividualName", "lastName": "SMITH", "individualMatchMode": "B", "maxItems": 10 } ``` #### Example: lookup by identification number ```json { "mode": "byIdentificationNumber", "identificationNumber": "000445089" } ``` ### Use cases - **Due diligence** — confirm a counterparty's Massachusetts entity type, status, and registered agent before contracting - **Compliance & KYC** — cross-check a business's legal entity name and identification number - **Officer/director research** — find every Massachusetts entity a named individual is an officer, director, or registered agent of - **Startup / legal research** — see how a company's Massachusetts entity is structured (Corp vs. LLC, domestic vs. foreign) - **Company name availability checks** — see what similarly-named entities already exist before choosing a new name ### FAQ **What's the data source?** The Massachusetts Corporations Division's own free public business search at `corp.sec.state.ma.us`. This actor is an independent third-party tool and is not affiliated with the Commonwealth of Massachusetts. **Is this data official / legally binding?** No. For an official Certificate of Good Standing or certified copies, use the Division's paid ordering channels (see the source site). This actor returns the same free informational data the public search page shows. **What's the difference between the four match modes?** They mirror the source search form's own dropdown exactly: `Begins with` matches names starting with your query, `Exact match` requires the whole name to match, `Full text` matches your query anywhere in the name, and `Soundex` matches names that sound similar even with different spelling. **Why did my `byIndividualName` search return results for entities I didn't expect?** Each row in the source's own results table is one officer/agent *appointment*, so a common name (e.g. `SMITH`) can return many entities across many different people who happen to share that surname. Narrow with `firstName`/`middleName` or switch to `individualMatchMode: "M"` (exact) for a specific person. **Why is `Active`/`Inactive` status "derived" rather than an explicit field on the source?** The source site doesn't render a single "Status:" label — it renders an inactivity date (with a specific reason label like "Date of Involuntary Dissolution...") only when an entity is no longer active, and renders nothing in that slot for active entities. This actor infers `Active` vs `Inactive` from that presence/absence, and passes through the source's own reason text verbatim when inactive. **Why did my `byFilingNumber` search return 0 results?** A filing/document number identifies one specific transaction (e.g. one Annual Report filing) in the source's own records — it's not the entity's identification number. You can find real filing numbers via an entity's "View filings" list on its own detail page. If you have an entity's identification number instead, use `byIdentificationNumber`. **How fresh is the data?** Real-time — the search reflects the Corporations Division's database as of the moment of the search. # Actor input Schema ## `mode` (type: `string`): Which axis of the Massachusetts Corporations Division search to use. ## `entityName` (type: `string`): Business/entity name to search for. ## `entityMatchMode` (type: `string`): How `entityName` is matched against the registry. ## `lastName` (type: `string`): Officer/registered-agent last name to search for. ## `firstName` (type: `string`): Officer/registered-agent first name (optional, narrows results). ## `middleName` (type: `string`): Officer/registered-agent middle name (optional, narrows results). ## `individualMatchMode` (type: `string`): How the individual's name fields are matched against the registry. ## `identificationNumber` (type: `string`): The entity's Massachusetts identification number (numeric, commonly 9 digits, e.g. `000445089`). ## `filingNumber` (type: `string`): A specific filing/document number within an entity's history (found via that entity's 'View filings' list on its detail page) -- not the entity's own identification number. ## `maxItems` (type: `integer`): Hard cap on emitted records (each record requires a separate detail-page fetch, so keep this modest). ## `proxyConfiguration` (type: `object`): Used only as an escalation fallback if the source rate-limits the run. The free Apify AUTO (datacenter) group is used -- no paid proxy is required. ## Actor input object example ```json { "mode": "byEntityName", "entityName": "microsoft", "entityMatchMode": "B", "individualMatchMode": "B", "maxItems": 10, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `entities` (type: `string`): Dataset containing all scraped Massachusetts business entities. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "byEntityName", "entityName": "microsoft", "entityMatchMode": "B", "individualMatchMode": "B", "maxItems": 10, "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/massachusetts-sos-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "byEntityName", "entityName": "microsoft", "entityMatchMode": "B", "individualMatchMode": "B", "maxItems": 10, "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/massachusetts-sos-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "byEntityName", "entityName": "microsoft", "entityMatchMode": "B", "individualMatchMode": "B", "maxItems": 10, "proxyConfiguration": { "useApifyProxy": true } }' | apify call crawlerbros/massachusetts-sos-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/massachusetts-sos-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Massachusetts Secretary of State Business Search Scraper", "description": "Search the Massachusetts Corporations Division (Secretary of the Commonwealth) business registry by entity name, officer/agent name, or identification number. Get entity type, status, registered agent, principal office address, and officers/directors.", "version": "1.0", "x-build-id": "yiPfu7e1WBF2qZQf5" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~massachusetts-sos-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-massachusetts-sos-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/crawlerbros~massachusetts-sos-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-massachusetts-sos-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/crawlerbros~massachusetts-sos-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-massachusetts-sos-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", "required": [ "mode" ], "properties": { "mode": { "title": "Search mode", "enum": [ "byEntityName", "byIndividualName", "byIdentificationNumber", "byFilingNumber" ], "type": "string", "description": "Which axis of the Massachusetts Corporations Division search to use.", "default": "byEntityName" }, "entityName": { "title": "Entity name (mode=byEntityName)", "type": "string", "description": "Business/entity name to search for.", "default": "microsoft" }, "entityMatchMode": { "title": "Entity name match mode (mode=byEntityName)", "enum": [ "B", "M", "F", "S" ], "type": "string", "description": "How `entityName` is matched against the registry.", "default": "B" }, "lastName": { "title": "Last name (mode=byIndividualName)", "type": "string", "description": "Officer/registered-agent last name to search for." }, "firstName": { "title": "First name (mode=byIndividualName)", "type": "string", "description": "Officer/registered-agent first name (optional, narrows results)." }, "middleName": { "title": "Middle name (mode=byIndividualName)", "type": "string", "description": "Officer/registered-agent middle name (optional, narrows results)." }, "individualMatchMode": { "title": "Individual name match mode (mode=byIndividualName)", "enum": [ "B", "M", "F", "S" ], "type": "string", "description": "How the individual's name fields are matched against the registry.", "default": "B" }, "identificationNumber": { "title": "Identification number (mode=byIdentificationNumber)", "type": "string", "description": "The entity's Massachusetts identification number (numeric, commonly 9 digits, e.g. `000445089`)." }, "filingNumber": { "title": "Filing/document number (mode=byFilingNumber)", "type": "string", "description": "A specific filing/document number within an entity's history (found via that entity's 'View filings' list on its detail page) -- not the entity's own identification number." }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 100, "type": "integer", "description": "Hard cap on emitted records (each record requires a separate detail-page fetch, so keep this modest).", "default": 10 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Used only as an escalation fallback if the source rate-limits the run. The free Apify AUTO (datacenter) group is used -- no paid proxy is required.", "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 } } } } } } } } } } ```