EntitySearch State Data

Structured state-level dataset for sidebar components. This data is designed for use in sidebar components on external websites.

Status

Enrichment is complete for 51 of 51 jurisdictions: all 50 states plus the District of Columbia (washington-d-c.json, stateAbbr: "DC"). Initial batch enrichment finished 2026-05-12, and the full set was re-verified against official sources during the 2026 verification campaign.

Note that root ../states.json deliberately remains a 50-state map and does not include DC.

• Coverage: all 50 states, AL through WY, plus DC
• Each state file contains contact info, addresses, hours, renewal links, LLC filing facts, name reservation details, and official sources — or consciously left as null if not available from official sources.
• Root ../states.json records have been aligned with official fee/source corrections.

Structure

entitysearch-state-data/
├── README.md
├── schema/
│   └── state.schema.json      # JSON validation schema
└── states/                    # Individual state JSON files, one per jurisdiction
    └── alabama.json           # Example state file

That is the whole published surface: a schema and 51 records. The dataset ships no images and no logos of any kind, which is why stateSeal is null in every record. An application that wants a seal supplies its own; see Optional Enrichment Fields.

Schema Fields

Optional Enrichment Fields

The following fields are not mandatory core data for the entity search experience, and missing values are not considered data quality issues:

Core data target: Official search URL, agency website, contact info (phone/email if available), address, hours, filing/renewal facts, and source tracking — practical information for the entity search user.

Cross-namespace contract

filingFacts.nameReservation holds the real out-of-pocket reservation cost, not the statutory filing fee. It mirrors name-rules/states/<slug>.json's nameReservationTotalCost, which is the authoritative field, and the two must agree. Where a state's statutory fee and real cost differ, nameReservationNotes explains the gap.

stateName, stateAbbr, and stateSlug must match the name-rules and dba-rules records for the same jurisdiction.

Data Rules

• Official sources only. "Official" means the government body that publishes the fact, not the domain suffix. See Methodology in the repository README for the list of official non-.gov hosts and the narrow mirror exception.
• Fee and requirement verification: Every fee, due date, and filing requirement is verified against the official state government portal, official fee schedule, official statute, or official filing portal
• Source requirement: sources[], root official_link, and root source_url fields must point to official sources
• No third-party sources: Legal service providers, blogs, SEO pages, news sites, or commercial summary sources are not used
• Unknown values: Left as null or empty
• Date format: ISO 8601 (YYYY-MM-DD)
• Image format: WebP preferred
• URL validation: Valid URI format required

Usage

const stateData = require('./states/alabama.json');

// Sidebar usage example
console.log(stateData.stateName); // "Alabama"
console.log(stateData.secretaryOfState.website); // "https://www.sos.alabama.gov"

Validation

To validate JSON files against state.schema.json:

npx ajv-cli validate --strict=false -s entitysearch-state-data/schema/state.schema.json -d 'entitysearch-state-data/states/*.json'

JSON parse check:

jq empty states.json entitysearch-state-data/states/*.json

Future Update Workflow

Since all states have been enriched, future work should focus on periodic verification, official fee change tracking, and link health checks rather than generating new batches. Maintenance work should still follow the same batch logic.

Batch Selection

• Divide states to update into small batches of 2-3 states.
• For each batch, first read the existing state JSON files and root states.json records.
• Clearly state batch scope in the final response and handoff notes if needed.

Example:

sed -n '1,220p' entitysearch-state-data/states/wisconsin.json
sed -n '1,220p' entitysearch-state-data/states/wyoming.json
sed -n '490,540p' states.json

Official Source Research

For each state, only use these source types:

• Secretary of State or Department of State corporation/business division pages
• Department of Financial Institutions, Department of Revenue, or official filing agency pages
• Official fee schedule HTML/PDF pages
• Official annual report, renewal, or business filing portals
• Official state statute pages

Do not use:

• LegalZoom, Northwest, ZenBusiness, Harbor Compliance, Forbes, etc. commercial pages
• Blogs, SEO landing pages, news sites
• Search result snippets only

Fields to Update

For each state file, check these fields:

• businessEntitySearch.url
• secretaryOfState.agency
• secretaryOfState.website
• secretaryOfState.phone
• secretaryOfState.email
• hours.timezone
• hours.regular
• physicalAddresses[]
• mailingAddress
• renewals.onlineRenewalUrl
• renewals.paperRenewalUrl
• renewals.notes
• filingFacts.llcFee
• filingFacts.llcFeeNotes
• filingFacts.annualReport
• filingFacts.annualReportDue
• filingFacts.nameReservation
• filingFacts.nameReservationNotes
• sources[]
• lastVerified

In root states.json, only update if official data changed or source link was corrected:

• formation_fee
• annual_report_fee
• annual_report_due_date
• official_link
• source_url
• last_verified
• root last_updated

Timestamp and Source Format

• lastVerified in touched state file must be current ISO date.
• lastAccessed in touched source records must be current ISO date.
• Relevant state last_verified in root states.json must be updated.
• If official data change was made across the dataset, root last_updated must be updated.

Annual Report and Fee Rules

• If there's no annual report fee in root states.json, use annual_report_fee: 0.
• Follow existing pattern in detail state JSON: if a state has no annual report, annualReport: null and annualReportDue: "N/A" can be used.
• If online and paper fees differ, the most practical/current online fee can be used as the main value; paper fee should be clearly noted in notes.
• If there's a minimum/maximum or asset-based fee, write the minimum fee as the main value; explain variable structure in filingFacts.*Notes and renewals.notes.

Link health

Every batch ends with a liveness pass over the URLs it touched. The maintenance tooling that performs it is not part of the published dataset, and its output is not committed. What matters for anyone reading the data is the rule the pass applies, which is stated above: a 403, a timeout, or a connection reset is bot protection or a network condition, not a dead page, and no URL is moved without 404 evidence read from the page itself.

Batch End Checklist

1. Run JSON parse check:

jq empty states.json entitysearch-state-data/states/*.json

2. Run schema validation:

npx ajv-cli validate --strict=false -s entitysearch-state-data/schema/state.schema.json -d 'entitysearch-state-data/states/*.json'

3. Re-check the URLs the batch touched, and note any that could not be read.
4. Record the batch scope, the caveats, and the next step in the maintenance notes.
5. Check with git diff that only expected files changed.
6. Write commit message to describe batch scope.

Example commit messages:

Enrich Wisconsin and Wyoming data
Refresh California and Colorado official fee sources
Audit annual report URLs for southeast batch

Agent Notes

• Keep changes small and limited to batch scope.
• Do not revert other user or agent changes.
• Preserve existing field order and file style in JSON edits.
• If changing fee or due date, specifically note in final response.
• If official URL audit errors, try to distinguish whether it's automation-related or a genuinely broken link.
• If a broken official link is replaced with an updated official page, both state JSON sources[] and root states.json sources must be updated.

Built With This Dataset

EntitySearch.us

Comprehensive step-by-step guides for business entity search across all 50 US states. Each state page features screenshots, official portal links, and LLC formation facts powered by this dataset.

https://entitysearch.us/texas/
https://entitysearch.us/wyoming/
https://entitysearch.us/delaware/

This dataset is part of the us-llc-fees-dataset repository.