# NC SOS Business Search & Entity Enricher (`monty15/north-carolina-sos-business-search`) Actor Bulk search North Carolina Secretary of State business records. Export structured NC entity status, SOS ID, registered agent, addresses, filings, source URLs, and annual-report phone data when available. - **URL**: https://apify.com/monty15/north-carolina-sos-business-search.md - **Developed by:** [Monty](https://apify.com/monty15) (community) - **Categories:** Lead generation, Real estate, Automation - **Stats:** 2 total users, 0 monthly users, 60.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $7.50 / 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. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 ## NC SOS Business Search & Entity Enricher Bulk search and enrich **North Carolina Secretary of State business entity records** from Apify. Enter company names and export structured NC business data including entity status, SOS ID, business type, formation date, registered agent, principal office address, company officials, filing metadata, source URLs, and annual-report phone numbers when available. Use this Actor when you need an unofficial API-style workflow for **NC SOS business search**, **North Carolina business entity lookup**, **registered agent lookup**, **company status verification**, or CSV enrichment from public NC Secretary of State Business Registration records. ### What is the North Carolina SOS Business Search Actor? This Actor searches the public **North Carolina Secretary of State Business Registration** system by entity name and saves structured results to an Apify dataset. It is built for due diligence, lead enrichment, real estate research, public-record lookup, and automation workflows where copying search results by hand is too slow. It works as an unofficial, Apify-hosted **API-style NC Secretary of State business search workflow**: submit one or more company names, run the Actor from the Apify Console or Apify API, and export the dataset as CSV, Excel, JSON, JSONL, XML, RSS, or HTML. ### What can this Actor do? - Search NC Secretary of State Business Registration records by entity name. - Run bulk searches from a list of company names. - Export one dataset item per matched NC SOS entity. - Return entity name, SOS ID, status, business type, date formed, prior names, and official source URL. - Visit profile pages to include registered agent, principal office address, and company officials when available. - Fetch the latest annual-report PDF and OCR page 1 to extract the public principal office phone number when present. - Include filing-list metadata without downloading every filing PDF. - Label possible affiliate/owner-name fallback matches separately from direct legal-name matches. - Preserve row-level caveats and errors instead of silently turning source problems into false no-matches. ### What data can you extract from NC Secretary of State business records? | Field | Description | | --- | --- | | `search_term` | Original company/entity name you submitted. | | `matched` | Whether an NC SOS entity match was returned. | | `match_type` | `direct_legal_name`, `possible_affiliate`, or `no_match`. | | `affiliate_query` | Broader owner/brand query used when the affiliate resolver is enabled. | | `name` | Entity legal name as shown by NC SOS. | | `sos_id` | North Carolina Secretary of State ID. | | `status` | Entity status, such as `Current-Active`. | | `business_type` | Corporation, LLC, limited partnership, etc. | | `date_formed` | Formation date shown by NC SOS when available. | | `registered_agent_name` | Registered agent from the entity profile when available. | | `principal_address` | Principal office address from the entity profile when available. | | `company_officials` | Officials listed on the NC SOS entity profile when available. | | `latest_filing_type` | Latest annual-report filing used for phone extraction. | | `latest_filing_date` | Date of the filing used for phone extraction. | | `nc_sos_principal_phone` | Phone number OCR-extracted from public annual-report PDFs when present. | | `nc_sos_phone_confidence` | Confidence label for phone extraction. | | `source_url` | Official NC SOS profile URL. | ### How to bulk search NC business entities Paste one or more company names into `searchTerms` and run the Actor. For a first test, use a small batch such as: ```json { "searchTerms": ["Red Hat Inc", "Lowe's Companies Inc"], "maxResultsPerSearch": 5, "includeProfiles": true, "includeFilings": false, "includePhones": true, "enableAffiliateResolver": true, "managedBrowser": true, "managedBrowserHeadless": true, "managedBrowserTimeoutSeconds": 240, "requestDelaySeconds": 1.5 } ```` After the run finishes, open the dataset and export the results as CSV, Excel, JSON, or JSONL. ### How to use this Actor through the Apify API You can run this Actor from Apify Console, schedules, integrations, webhooks, or the Apify API. Use it when you need repeatable, API-style **North Carolina business entity search** behavior but want Apify to handle the run, dataset, exports, and monitoring. Example API flow: 1. Start the Actor with `searchTerms`. 2. Wait for the run to finish. 3. Read the default dataset items from Apify. 4. Export to CSV/Excel or pull JSON into your pipeline. Example input body: ```json { "searchTerms": ["Red Hat Inc", "Lowe's Companies Inc"], "maxResultsPerSearch": 1, "includeProfiles": true, "includePhones": true } ``` Tip: set `maxResultsPerSearch` to `1` when you only need the best match for each company name. Increase it when you want to review multiple possible matches. ### How to enrich a CSV of North Carolina companies If you have a spreadsheet of NC company names, copy the company-name column into `searchTerms` or call the Actor through the Apify API from your own script. The output dataset can be exported back to CSV or Excel with official-source fields such as status, SOS ID, registered agent, address, and profile URL. Common CSV enrichment workflows: - Verify whether NC leads are active business entities. - Add SOS IDs and official profile URLs to a lead list. - Add registered agent and principal office fields to a company list. - Pull public annual-report phone numbers when available. - Separate exact legal-name matches from possible affiliate/brand-name matches. ### Can I get phone numbers from NC SOS annual reports? Yes, when `includePhones` is enabled, the Actor finds the latest Annual Report filing for each matched entity, downloads the public NC SOS PDF, OCRs page 1, and extracts the principal office phone number when the form exposes one. Phone-related output fields: - `nc_sos_principal_phone` - `nc_sos_phone_confidence` - `nc_sos_phone_source` - `latest_filing_type` - `latest_filing_date` This uses public NC SOS filing PDFs. It does not infer phone ownership beyond the label present in the annual-report form. ### Example output ```json { "search_term": "Red Hat Inc", "rank": 1, "matched": true, "match_type": "direct_legal_name", "affiliate_query": null, "relationship_basis": "direct NC SOS legal-name search", "name": "RED HAT, INC.", "sos_id": "...", "internal_id": "...", "status": "Current-Active", "business_type": "Business Corporation", "date_formed": "...", "prior_names": [], "registered_agent_name": "...", "principal_address": "...", "company_officials": [ { "title": "Vice President", "name": "...", "address": "...", "official_url": "https://www.sosnc.gov/online_services/search/Business_Registration_official/..." } ], "latest_filing_type": "Annual Report", "latest_filing_date": "...", "nc_sos_principal_phone": "+1...", "nc_sos_phone_confidence": "high", "nc_sos_phone_source": "principal_office_phone", "filings": [], "source_url": "https://www.sosnc.gov/online_services/search/Business_Registration_profile/...", "source": "NC Secretary of State Business Registration", "transport": "managed_browser" } ``` ### Input settings #### `searchTerms` Required. One or more business/entity names to search. #### `maxResultsPerSearch` Maximum number of matching records saved per search term. Default: `10`. For lower-cost enrichment, use `1` when you only need the best match. For research, use a higher number to inspect possible matches. #### `includeProfiles` Default: `true`. Fetches each matched profile page and extracts profile fields such as principal office, registered agent, and company officials when present. #### `includeFilings` Default: `false`. Fetches filing-list metadata for each matched profile. It does not download every filing PDF. #### `includePhones` Default: `true`. Fetches the latest Annual Report filing, OCRs the public PDF, and returns the principal office phone number when present. #### `enableAffiliateResolver` Default: `true`. When an exact legal-name search returns no NC SOS records, retries with conservative brand/owner tokens. These rows are labeled as `possible_affiliate` so they are not confused with direct legal-name matches. #### `managedBrowser` Default: `true`. Runs NC SOS requests through a managed browser session. This is the recommended Apify cloud setting. #### `managedBrowserHeadless` Default: `true`. Keep enabled for Apify cloud runs. #### `managedBrowserTimeoutSeconds` Default: `240`. Maximum time to wait for the managed browser session to reach the NC SOS search page before failing. #### `requestDelaySeconds` Default: `1.5` seconds. Polite delay between NC SOS requests for fallback/debug runs. The managed-browser path has its own pacing. #### `sessionJson` Fallback only. Leave blank for normal managed-browser runs. Do not publish or share session cookies. ### How much does NC business entity scraping cost? Pricing is per saved result. A search term can return multiple matching entities depending on `maxResultsPerSearch`. For predictable costs: - Use `maxResultsPerSearch: 1` when you only need the best match. - Keep `includeFilings: false` unless you need filing metadata. - Keep a small first run to confirm output shape before running a large batch. ### Common use cases - API-style North Carolina business entity search workflows. - NC Secretary of State registered agent lookup. - Bulk NC company status verification. - CSV enrichment for business leads. - Real estate LLC and entity research. - Due diligence on NC corporations and LLCs. - Public-record lookup for automation pipelines. - Finding principal office phone numbers exposed in public annual-report PDFs. ### Is there an official NC Secretary of State API? North Carolina provides a public Secretary of State Business Registration search website. Bulk export and API-style workflows are limited for many users. This Actor provides an unofficial Apify workflow for repeatable searches, structured datasets, CSV export, scheduling, Apify API runs, and integration with your own tools. This Actor is not affiliated with or endorsed by the North Carolina Secretary of State. ### What this Actor does not do - It does not identify beneficial owners. - It does not guarantee that a registered agent or company official is the true owner, operator, or decision-maker. - It does not download private records or account-only data products. - It does not infer private phone ownership. - It does not download every filing PDF in the default Store-ready configuration. - It does not provide legal, compliance, or investment advice. ### Notes and limits NC SOS can change its page markup, rate limits, or access controls. If the site returns an interstitial or 403, reduce batch size, increase timeouts, and retry. No scraper can guarantee permanent access if the source site changes its controls. Use this Actor responsibly and review NC SOS terms and applicable public-records rules for your use case. # Actor input Schema ## `searchTerms` (type: `array`): One or more company/entity names. The Actor searches each term against NC SOS Business Registration records. ## `maxResultsPerSearch` (type: `integer`): Maximum number of matching NC SOS records to save for each search term. ## `includeProfiles` (type: `boolean`): Fetch each matched profile page to include principal office and registered agent fields when available. ## `includeFilings` (type: `boolean`): Fetch filing-list metadata for each matched entity. Does not download PDFs. ## `includePhones` (type: `boolean`): Fetch the latest NC SOS annual-report PDF for each matched entity, OCR page 1, and extract the principal office phone number when present. ## `enableAffiliateResolver` (type: `boolean`): When an exact legal-name search returns no NC SOS records, retry with conservative brand/owner tokens such as 'Brennan' from 'Brennan Investment Group' or 'Royal Oak' from 'Royal Oak Realty Trust'. Results are labeled as possible\_affiliate instead of direct\_legal\_name. ## `managedBrowser` (type: `boolean`): Use the managed browser session for NC SOS requests. This is the recommended cloud setting. ## `managedBrowserHeadless` (type: `boolean`): Run the managed browser without a visible window. Keep enabled for Apify cloud runs. ## `managedBrowserTimeoutSeconds` (type: `integer`): Maximum seconds to wait for the managed browser session to reach the NC SOS search page before failing. ## `requestDelaySeconds` (type: `number`): Polite delay between NC SOS requests for the fallback HTTP transport. The managed browser has its own pacing. ## `sessionJson` (type: `string`): Fallback only. JSON with cookies, antiforgery\_token, and user\_agent from an already initialized NC SOS session. Used when managedBrowser=false. ## Actor input object example ```json { "searchTerms": [ "Red Hat Inc", "Lowe's Companies Inc" ], "maxResultsPerSearch": 10, "includeProfiles": true, "includeFilings": false, "includePhones": true, "enableAffiliateResolver": true, "managedBrowser": true, "managedBrowserHeadless": true, "managedBrowserTimeoutSeconds": 240, "requestDelaySeconds": 1.5 } ``` # Actor output Schema ## `datasetItems` (type: `string`): Structured NC SOS search results. Use the dataset export controls to download CSV, Excel, JSON, JSONL, XML, RSS, or HTML. ## `datasetCsv` (type: `string`): Structured NC SOS search results. Use the dataset export controls to download CSV for spreadsheets and enrichment workflows. # 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 = { "searchTerms": [ "Red Hat Inc", "Lowe's Companies Inc" ], "sessionJson": "" }; // Run the Actor and wait for it to finish const run = await client.actor("monty15/north-carolina-sos-business-search").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 = { "searchTerms": [ "Red Hat Inc", "Lowe's Companies Inc", ], "sessionJson": "", } # Run the Actor and wait for it to finish run = client.actor("monty15/north-carolina-sos-business-search").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 '{ "searchTerms": [ "Red Hat Inc", "Lowe'\''s Companies Inc" ], "sessionJson": "" }' | apify call monty15/north-carolina-sos-business-search --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=monty15/north-carolina-sos-business-search", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "NC SOS Business Search & Entity Enricher", "description": "Bulk search North Carolina Secretary of State business records. Export structured NC entity status, SOS ID, registered agent, addresses, filings, source URLs, and annual-report phone data when available.", "version": "0.1", "x-build-id": "8tid4p3rK9wvPDitH" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/monty15~north-carolina-sos-business-search/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-monty15-north-carolina-sos-business-search", "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/monty15~north-carolina-sos-business-search/runs": { "post": { "operationId": "runs-sync-monty15-north-carolina-sos-business-search", "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/monty15~north-carolina-sos-business-search/run-sync": { "post": { "operationId": "run-sync-monty15-north-carolina-sos-business-search", "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": [ "searchTerms" ], "properties": { "searchTerms": { "title": "Business names to search", "minItems": 1, "type": "array", "description": "One or more company/entity names. The Actor searches each term against NC SOS Business Registration records.", "items": { "type": "string" } }, "maxResultsPerSearch": { "title": "Max results per search", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum number of matching NC SOS records to save for each search term.", "default": 10 }, "includeProfiles": { "title": "Include profile details", "type": "boolean", "description": "Fetch each matched profile page to include principal office and registered agent fields when available.", "default": true }, "includeFilings": { "title": "Include filing metadata", "type": "boolean", "description": "Fetch filing-list metadata for each matched entity. Does not download PDFs.", "default": false }, "includePhones": { "title": "Extract phone from latest annual report PDF", "type": "boolean", "description": "Fetch the latest NC SOS annual-report PDF for each matched entity, OCR page 1, and extract the principal office phone number when present.", "default": true }, "enableAffiliateResolver": { "title": "Try owner/affiliate resolver when direct search misses", "type": "boolean", "description": "When an exact legal-name search returns no NC SOS records, retry with conservative brand/owner tokens such as 'Brennan' from 'Brennan Investment Group' or 'Royal Oak' from 'Royal Oak Realty Trust'. Results are labeled as possible_affiliate instead of direct_legal_name.", "default": true }, "managedBrowser": { "title": "Use managed browser session", "type": "boolean", "description": "Use the managed browser session for NC SOS requests. This is the recommended cloud setting.", "default": true }, "managedBrowserHeadless": { "title": "Run managed browser headless", "type": "boolean", "description": "Run the managed browser without a visible window. Keep enabled for Apify cloud runs.", "default": true }, "managedBrowserTimeoutSeconds": { "title": "Managed browser startup timeout", "minimum": 30, "maximum": 600, "type": "integer", "description": "Maximum seconds to wait for the managed browser session to reach the NC SOS search page before failing.", "default": 240 }, "requestDelaySeconds": { "title": "Delay between requests", "minimum": 0, "maximum": 30, "type": "number", "description": "Polite delay between NC SOS requests for the fallback HTTP transport. The managed browser has its own pacing.", "default": 1.5 }, "sessionJson": { "title": "Optional pre-cleared session JSON", "type": "string", "description": "Fallback only. JSON with cookies, antiforgery_token, and user_agent from an already initialized NC SOS session. Used when managedBrowser=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 } } }, "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 } } } } } } } } } } ```