# Texas Franchise Tax — Company Lookup (Comptroller) (`ai-lead-gen-tools/us-tx-comptroller`) Actor

Search Texas taxable entities in the Comptroller franchise-tax registry. Returns normalized records: name, DBA, EIN, SOS file number, status, formation state and date, registered agent, officers and addresses. Public JSON API, no proxy needed.

- **URL**: https://apify.com/ai-lead-gen-tools/us-tx-comptroller.md
- **Developed by:** [Vladimir Chernykh](https://apify.com/ai-lead-gen-tools) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.80 / 1,000 company scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Texas Company Registry Scraper — Comptroller Franchise Tax

Look up Texas companies in the official **Texas Comptroller franchise-tax registry** and export clean, normalized records — legal name, DBA, EIN, SOS file number, status, formation state and date, registered agent, officers with titles, and addresses.

The source is a **public JSON API**. No login, no cookies, no proxies, no captchas — which is why runs are fast (a few seconds for a hundred companies) and reliable.

### What you get

One row per company, every field always present, `null` when the registry does not publish it:

| Field | Example |
|---|---|
| `name` / `legalName` | ANTHROPIC, PBC |
| `dbaName` | ANTHROPIC, PBC, INC. |
| `ein` | 861696045 |
| `documentNumber` | 0805470362 (SOS file number) |
| `entityType` | Corporation / LLC / PBC (derived from the legal suffix) |
| `status` | ACTIVE |
| `jurisdiction` / `formationDate` | Delaware / 2024-03-19 |
| `registeredAgent` | name + full address |
| `officers[]` | name, title, year, address |
| `principalAddress`, `mailingAddress` | street, city, state, ZIP |
| `annualReports`, `lastEvent`, `filingHistory` | reporting history |
| `sourceUrl` | link back to the source |

Output is available as JSON, CSV or Excel from the dataset tab.

### How to use it

Paste company names into **Search terms** and run. That is the whole setup.

```json
{
  "searchTerms": ["TESLA MOTORS", "ANTHROPIC", "STRIPE"],
  "maxResults": 100
}
```

| Input | Default | Notes |
|---|---|---|
| `searchTerms` | `["ANTHROPIC"]` | names or fragments, 2–50 characters |
| `taxpayerIds` | `[]` | exact 9/11-digit numbers — fastest, skips the search |
| `fileNumbers` | `[]` | 6–10-digit SOS file numbers |
| `maxResults` | `100` | hard cap on saved records |
| `mode` | `full` | `new` = only companies you have not seen before |
| `includePartialRecords` | `false` | keep entities the detail endpoint refuses |
| `includeRaw` | `false` | attach the untouched source JSON |
| `maxConcurrency` | `5` | parallel requests |
| `sameDomainDelaySecs` | `1.5` | politeness gap |

At least one of `searchTerms`, `taxpayerIds`, `fileNumbers` is required.

### Monitoring: run it on a schedule

Set `mode` to **`new`** and put the actor on a schedule (daily or weekly). It remembers which companies it already returned and only saves fresh ones — so you get a change feed instead of paying for the same records twice.

This is the intended use for lead generation, compliance monitoring and vendor screening.

### Broad searches

The registry caps a single query at about 925 rows and answers `413` when you exceed it. When that happens the actor automatically re-searches the term with legal suffixes (`"ACME"` → `"ACME LLC"`, `"ACME INC"`, …), up to two levels deep — measured on `"TEXAS"` (65 137 entries), that produced 191 real candidates. If a term is still too broad, narrow it.

Two more things worth knowing:

- Some entities are registered with the Secretary of State but are **not enrolled in franchise tax**; the detail endpoint returns `400` for them. Enable `includePartialRecords` to keep them as name + ZIP stubs.
- `entityType` is **derived from the name**, not published by the registry. Treat it as a hint, not a fact.

### Cost

**$2 per 1 000 companies**, plus a one-off $0.00005 for starting the run.

You pay only for records that land in the dataset — an empty or failed search costs you nothing.
A company whose detail page is unavailable is still billed if you enable `includePartialRecords`,
because you do receive a row for it; leave it off and you are not charged for those.

Check the **Pricing** tab of this Actor for the current price before running at scale.

### Notes

- Data comes straight from `comptroller.texas.gov`; `sourceUrl` on every record lets you verify it.
- No proxy is used, so there is no proxy cost passed on to you.
- The registry is updated continuously by the state; `statusDate` tells you how fresh each record is.

# Actor input Schema

## `searchTerms` (type: `array`):

Company names or name fragments, e.g. "TESLA MOTORS", "ANTHROPIC". Minimum 2 characters. Broad terms that exceed the API limit of ~925 rows are automatically re-searched with legal suffixes (LLC, INC, CORP, ...).

## `taxpayerIds` (type: `array`):

Exact Texas taxpayer numbers (9 or 11 digits). Fastest path: skips the name search entirely.

## `fileNumbers` (type: `array`):

Texas Secretary of State file numbers (6–10 digits). Resolved to taxpayer numbers automatically.

## `maxResults` (type: `integer`):

Hard cap on the number of company records saved to the dataset. Each saved record is charged.

## `mode` (type: `string`):

"full" returns everything matching the query. "new" remembers what previous runs already returned and only saves fresh companies — use it for a daily schedule.

## `includePartialRecords` (type: `boolean`):

Some entities are registered with the Secretary of State but are not enrolled in franchise tax, so the detail endpoint returns HTTP 400. When enabled, a minimal record (name, taxpayer number, ZIP) is saved for them instead of being skipped.

## `includeRaw` (type: `boolean`):

Attach the untouched JSON returned by the Comptroller to every record under the `raw` field. Useful for auditing, roughly doubles the dataset size.

## `maxConcurrency` (type: `integer`):

Parallel detail requests. Keep this modest to stay polite to a government API.

## `sameDomainDelaySecs` (type: `number`):

Minimum gap between two requests to comptroller.texas.gov.

## `requestTimeoutSecs` (type: `integer`):

Per-request timeout before a retry is attempted.

## `runBudgetSecs` (type: `integer`):

How long this run may take before it stops and returns what it has. Leave it empty (recommended) and the run uses the whole timeout you set for it. Set a number only to stop earlier. Stopping early is not a failure: the run summary reports it and you get the records found so far.

## `proxyConfiguration` (type: `object`):

Not required: the Texas API is publicly accessible. Leave disabled for the fastest and cheapest runs.

## Actor input object example

```json
{
  "searchTerms": [
    "ANTHROPIC"
  ],
  "maxResults": 100,
  "mode": "full",
  "includePartialRecords": false,
  "includeRaw": false,
  "maxConcurrency": 5,
  "sameDomainDelaySecs": 1.5,
  "requestTimeoutSecs": 30,
  "runBudgetSecs": 205,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

One row per company. Every field is always present — unknown values are null, never omitted, so the column set is stable between runs. See the Companies tab for the full table.

## `summary` (type: `string`):

Counters for the run: records pushed, candidates collected, records skipped as already seen, detail pages that returned no franchise-tax record, and how many charge events were emitted.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerms": [
        "ANTHROPIC"
    ],
    "runBudgetSecs": 205
};

// Run the Actor and wait for it to finish
const run = await client.actor("ai-lead-gen-tools/us-tx-comptroller").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchTerms": ["ANTHROPIC"],
    "runBudgetSecs": 205,
}

# Run the Actor and wait for it to finish
run = client.actor("ai-lead-gen-tools/us-tx-comptroller").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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": [
    "ANTHROPIC"
  ],
  "runBudgetSecs": 205
}' |
apify call ai-lead-gen-tools/us-tx-comptroller --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ai-lead-gen-tools/us-tx-comptroller"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/BPTbscBlAJbSNPoJQ/builds/XHBPZw1lLja8Q5XWl/openapi.json