# Texas Taxable Entity Search — Comptroller Franchise Tax Status (`bovi/texas-taxable-entity`) Actor

Search the Texas Comptroller's public franchise-tax account-status registry by entity name, taxpayer number, or SOS file number. Returns official taxable-entity status, right-to-transact standing, registered agent, and officer/director records from mycpa.cpa.state.tx.us.

- **URL**: https://apify.com/bovi/texas-taxable-entity.md
- **Developed by:** [Vitalii Bondarev](https://apify.com/bovi) (community)
- **Categories:** Lead generation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 texas taxable entity search — comptroller franchise tax statuses

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Texas Taxable Entity Search — Comptroller Franchise Tax Status

Search the Texas Comptroller's public franchise-tax account-status registry
([mycpa.cpa.state.tx.us](https://mycpa.cpa.state.tx.us/coa/Index.html)) by
entity name, taxpayer number, or Texas Secretary of State (SOS) file number.
Returns the official record: right-to-transact-business status, SOS
registration status, registered agent, mailing address, and — when on file
— officer/director/general-partner records from the entity's most recent
Public Information Report (PIR).

Typical use: verify a Texas-registered company's standing before doing
business with it, find its registered agent for service of process, or
confirm the officers/managers on file for a compliance or lead-generation
workflow.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `searchNames` | string\[] | `["Whataburger Restaurants LLC"]` | Entity names to search. Each name is one search. |
| `searchTaxpayerIds` | string\[] | `[]` | Exact Comptroller Taxpayer Numbers (11-digit) or Federal EINs (9-digit). Faster and unambiguous — use when you already know the number. |
| `searchFileNumbers` | string\[] | `[]` | Exact Texas SOS file numbers (6–10 digits). |
| `maxResultsPerSearch` | integer | `20` | Cap on matching entities returned per name search. Taxpayer-number and file-number searches always return at most one match. |
| `fetchDetails` | boolean | `true` | Fetch each match's detail record for mailing address, right-to-transact/SOS status, registered agent, and officers. If `false`, only the search-result summary fields are returned (one fewer request per entity). |
| `maxItems` | integer | `100` | Overall cap across all searches combined. `0` = unlimited. |
| `proxyConfiguration` | object | Apify Proxy, RESIDENTIAL, US | Standard Apify Proxy input. The actor works out of the box — no proxy key or credentials of your own are required. |

At least one of `searchNames` / `searchTaxpayerIds` / `searchFileNumbers`
must be non-empty. A name that is too broad (matches hundreds of entities)
is rejected by the registry itself — narrow the name and re-run; this is
logged as a warning per term, not a hard failure of the whole run.

### Output fields

One record per matched entity. Fields marked "detail" only populate when
`fetchDetails` is `true` (default) and the detail fetch succeeds.

| Field | Source | Description |
|---|---|---|
| `search_query` | input | The name/number that produced this record |
| `search_type` | input | `name`, `taxpayerId`, or `fileNumber` |
| `taxpayer_id` | search+detail | Texas Comptroller Taxpayer Number |
| `fei_number` | detail | Federal EIN, when on file |
| `name` | search+detail | Official taxable-entity name on file |
| `dba_name` | detail | Doing-business-as name, if any |
| `mailing_address` | detail | Full mailing address, single line |
| `mailing_address_zip` | search | Mailing ZIP (always populated, even without detail) |
| `right_to_transact_tx` | detail | ACTIVE = franchise-tax account status is in good standing; a non-ACTIVE value signals the right to transact business in Texas is forfeited/ended |
| `state_of_formation` | detail | Jurisdiction of formation |
| `sos_registration_status` | detail | SOS registration status (updated each business day) |
| `effective_sos_registration_date` | detail | Effective date of SOS registration |
| `sos_file_number` | detail | Texas SOS file number |
| `registered_agent_name` | detail | Registered agent name — see PII note below |
| `registered_office_address` | detail | Registered agent's office address |
| `officers` | detail | Array of `{name, title, active_year, address, city, state, zip, source}` — see the standalone PII-granularity section below |
| `officer_count` | detail | Number of officer/director/general-partner records found |
| `report_year` | detail | Year of the most recent Public Information Report on file |
| `last_updated` | detail | Timestamp the Comptroller's system last refreshed this record |
| `detail_url` | derived | Direct link to the entity's page on comptroller.texas.gov |
| `parse_confidence` | derived | `high` / `medium` / `low` — see below |

`parse_confidence` is `high` when the core search fields (name, taxpayer ID)
are present and the detail fetch enriched the record with a registered
agent; `medium` when core fields are present but detail enrichment is
missing or thin (e.g. `fetchDetails: false`); `low` if even the core
search-row fields are missing (an unrecognized API response shape).

### ⚠️ PII disclosure — officer/director records carry a full home or mailing street address

This is the most sensitive personal-data field in this actor and it is
called out here on its own, not folded into a general description.

The `officers` array (sourced from each entity's Public Information Report,
filed with and disclosed by the Texas Comptroller / Secretary of State) can
carry, for each officer, director, or general partner: their **full name**
**plus a full street address, city, state, and ZIP code** (fields
`AD_STR_POB_TX` / `CITY_NM` / `ST_CD` / `AD_ZP` in the source data). For a
large company this address is typically the corporate headquarters. For a
smaller entity where an individual serves in their own capacity, this can
be that **individual's home or personal mailing address** — a materially
higher granularity of personal information than a bare name.

This is the same legal basis as this fleet's other business-registry
actors (a legally-mandated public state filing, not personal data
collected from a private source) — Texas law requires this disclosure
precisely so the public, courts, and counterparties can identify and
reach a company's responsible officers. The difference here is the
**address granularity**: unlike a bare-name-only registry, this source's
officer records routinely include a full street address alongside the
name. Buyers using this actor for outreach, compliance, or due-diligence
should be aware of that granularity before using the `officers` field —
this is standard, already-public Texas state data, not a private source,
but it is more identifying than a name alone.

The `registered_agent_name` field carries the same general pattern as this
fleet's other SOS-registry actors: a business name for filings that use a
registered-agent service company, or a natural person's name (paired with
`registered_office_address`) for filings where an individual serves as
their own registered agent.

### Charge event

This actor bills per matched entity record delivered:

- **`entity-record`** — charged once per record pushed to the dataset
  (whether or not `officers` populated for that record — the
  right-to-transact status, SOS status, and registered agent fields are
  the JTBD-critical payload on every record regardless of entity type or
  officer-disclosure history).

### Notes

- Officer/director coverage varies by entity and filing history — not every
  active entity has an officer array on file (e.g. no PIR filed yet, or a
  entity type/report combination the Comptroller doesn't track officers
  for). An empty `officers` array with a populated `registered_agent_name`
  and `right_to_transact_tx` is still a `high`-confidence record — officer
  coverage is a registry-completeness fact, not a parser gap.
- A taxpayer-number or SOS-file-number search is exact-match and
  unambiguous — prefer it whenever the number is already known.
- The registry itself rejects an overly broad name search (HTTP 413,
  "Search will return N entries. Please refine search by Entity Name.")
  rather than returning a huge unfiltered list — this actor treats that as
  "no records for this term" and logs the registry's own message so the
  caller knows to narrow the name, rather than silently truncating or
  retrying.

# Actor input Schema

## `searchNames` (type: `array`):

One or more company/entity names to search on the Texas Comptroller's franchise-tax account-status registry (mycpa.cpa.state.tx.us). Each name is one search — matches use substring search server-side. A very broad name (e.g. a single common word) can be rejected by the registry itself as 'too many results' — narrow the name if that happens.

## `searchTaxpayerIds` (type: `array`):

One or more exact Texas Comptroller Taxpayer Numbers (11-digit) or Federal EINs (9-digit) to look up directly. Faster and unambiguous — use when you already know the taxpayer number.

## `searchFileNumbers` (type: `array`):

One or more exact Texas Secretary of State file numbers (6-10 digits) to look up directly.

## `maxResultsPerSearch` (type: `integer`):

Cap on how many matching entities to return for each name searched (a broad name can match many entities). Taxpayer-number and file-number searches always return at most one match. Results are ordered as the registry returns them.

## `fetchDetails` (type: `boolean`):

If true, fetch each matched entity's detail record for mailing address, right-to-transact status, SOS registration status, registered agent, and officer/director records. If false, only the search-result summary fields (name, taxpayer number, mailing ZIP) are returned, one fewer request per entity.

## `maxItems` (type: `integer`):

Overall cap on entity records returned across all searches combined. 0 = unlimited (bounded only by maxResultsPerSearch per search).

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

Proxy settings. Use Apify Proxy with the RESIDENTIAL group (country US) — required for reliable access to the Comptroller's site.

## Actor input object example

```json
{
  "searchNames": [
    "Whataburger Restaurants LLC"
  ],
  "searchTaxpayerIds": [],
  "searchFileNumbers": [],
  "maxResultsPerSearch": 20,
  "fetchDetails": true,
  "maxItems": 100,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset containing Texas taxable-entity records (name, taxpayer\_id, mailing\_address, right\_to\_transact\_tx, sos\_registration\_status, registered\_agent\_name, officers, officer\_count, detail\_url, parse\_confidence).

# 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 = {
    "searchNames": [
        "Whataburger Restaurants LLC"
    ],
    "searchTaxpayerIds": [],
    "searchFileNumbers": [],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("bovi/texas-taxable-entity").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 = {
    "searchNames": ["Whataburger Restaurants LLC"],
    "searchTaxpayerIds": [],
    "searchFileNumbers": [],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("bovi/texas-taxable-entity").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 '{
  "searchNames": [
    "Whataburger Restaurants LLC"
  ],
  "searchTaxpayerIds": [],
  "searchFileNumbers": [],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call bovi/texas-taxable-entity --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bovi/texas-taxable-entity"
        }
    }
}

```

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/IhopyznOUtuwr2jBU/builds/CGUu9jRapFySY2amh/openapi.json