Company schema - GovFiles API

The GovFiles dataset contains a single normalized Company object per entity. This object is sourced directly from US state business registries. Fields the registry does not publish are returned as null. List fields are null when unknown and [] when known-empty. Dates are ISO 8601 (YYYY-MM-DD). View an example Company

Company object

Four fields are required on every record. All others are optional and nullable.

Field	Type	Required	Description
`company_number`	string	yes	Unique ID assigned by the state registry (filing number, entity ID, etc). Stable across amendments.
`name`	string	yes	Legal name as currently registered.
`jurisdiction_code`	string	yes	Lowercase ISO 3166-2 style with underscore: `us_de`, `us_ca`, `us_ny`, etc. See jurisdictions.
`retrieved_at`	date	yes	Date this snapshot was scraped from the registry.
`incorporation_date`	date \| null		Formation / registration date.
`dissolution_date`	date \| null		Dissolution date, if any.
`current_status`	string \| null		Free-form registry status. Examples: `"Active"`, `"Good Standing"`, `"Revoked"`, `"Withdrawn"`. Varies by state.
`company_type`	string \| null		Free-form entity type. Examples: `"LLC"`, `"Corporation"`, `"Limited Partnership"`, `"Nonprofit"`.
`registry_url`	string \| null		Direct link to this entity on the state’s registry website.
`website`	string \| string[] \| null		Company-owned URLs as reported by the registry.
`telephone_number`	string \| null		Unformatted. Include country/area codes as reported.
`fax_number`	string \| null		Unformatted.
`branch`	BranchType \| null		`"F"` = foreign-qualified, `"L"` = domestic.
`registered_address`	Address \| string \| null		Principal / registered office. Structured when we could parse it; raw string otherwise.
`headquarters_address`	Address \| string \| null		Where the business is actually operated, when distinct from the registered address.
`mailing_address`	Address \| string \| null		Correspondence address, when provided.
`officers`	Officer[] \| null		Directors, managers, members, registered agents — anyone the registry lists as an officer.
`filings`	Filing[] \| null		Statutory filings: annual reports, amendments, certificates, etc.
`identifiers`	Identifier[] \| null		External IDs: EIN, SEC CIK, LEI, etc.
`industry_codes`	IndustryCode[] \| null		NAICS, SIC, NACE, etc. Scheme identified by `code_scheme_id`.
`previous_names`	PreviousName[] \| null		Historical legal names, with transition dates when published.
`alternative_names`	AlternativeName[] \| null		DBAs, trade names, abbreviations, alternate-language legal names.
`share_parcels`	ShareParcel[] \| null		Blocks of shares held by shareholders. Includes banded disclosures (e.g. “25–50% of shares”).
`total_shares`	TotalShares \| null		Total number of authorized or issued shares, when disclosed.
`subsequent_registrations`	object[] \| null		Re-registrations of this entity in other jurisdictions.
`alternate_registrations`	object[] \| null		Parallel registrations in other jurisdictions.
`all_attributes`	AllAttributes \| null		Extended fields: registered agent, foreign-qualification info, mergers, employee count.

Nested objects

These submodels appear inside the Company object’s structured fields. Field types marked null are optional.

Address

A postal address. Returned as an object when structured fields could be parsed; returned as a raw string otherwise. At least one of street_address, postal_code, or locality is always present.

Field	Type	Description
`street_address`	string \| null
`locality`	string \| null	City or town.
`region`	string \| null	State, province, or equivalent.
`postal_code`	string \| null
`country`	string \| null	Full country name.
`country_code`	string \| null	ISO 3166-1 alpha-2.

Officer

A director, manager, member, registered agent, or other company officer.

Field	Type	Description
`name`	string	Required.
`position`	string \| null	Free-form. `"Director"`, `"CEO"`, `"Registered Agent"`, `"Manager"`, etc.
`start_date`	date \| null	When this person took the role.
`end_date`	date \| null	When they left the role.
`uid`	string \| null	Unique ID for this specific officership.
`other_attributes`	object \| null	Extra fields: `type` (EntityType), `date_of_birth`, `nationality`, `person_uid` (stable ID for the individual across officerships), `address` (Address \| string).

Filing

A statutory filing — annual report, amendment, certificate, dissolution, etc. Requires date and at least one of title, description, or filing_type_name.

Field	Type	Description
`date`	date	Required. Filing date.
`title`	string \| null
`description`	string \| null
`uid`	string \| null	Filing number or document ID from the registry.
`url`	string \| null	URL to the filing document on the state’s site (PDF, image, etc.).
`filing_type_code`	string \| null	Registry’s internal code.
`filing_type_name`	string \| null	Human-readable filing type.

Identifier

An external ID tied to the company.

Field	Type	Description
`uid`	string	Required. The identifier value.
`identifier_system_code`	string	Required. Scheme slug. Common values: `"us_fein"`, `"us_sec_cik"`, `"lei"`.

IndustryCode

Field	Type	Description
`code`	string	Required. e.g. `"541512"`.
`code_scheme_id`	string	Required. e.g. `"us_naics_2007"`, `"us_naics_2022"`, `"us_sic_1987"`, `"uk_sic_2007"`, `"eu_nace_2"`.
`name`	string \| null	Human-readable description of the code.
`start_date`	date \| null
`end_date`	date \| null

PreviousName

Field	Type	Description
`company_name`	string	Required.
`start_date`	date \| null	Date the company started using this name.
`con_date`	date \| null	Date the company stopped using this name.

AlternativeName

DBAs, trade names, abbreviations, and alternate-language legal names.

Field	Type	Description
`company_name`	string	Required.
`type`	AlternativeNameType	Required.
`start_date`	date \| null
`end_date`	date \| null
`language`	string \| null	ISO 639 two-letter code.

ShareParcel

A block of shares held by one or more shareholders. min/max fields are for banded disclosures (e.g. “25–50% of shares”).

Field	Type	Description
`number_of_shares`	integer \| null
`percentage_of_shares`	float \| null	0–100.
`percentage_of_shares_min`	float \| null	0–100.
`percentage_of_shares_max`	float \| null	0–100.
`voting_percentage`	float \| null	0–100.
`voting_percentage_min`	float \| null	0–100.
`voting_percentage_max`	float \| null	0–100.
`share_class`	string \| null
`start_date`	date \| null
`end_date`	date \| null
`sample_date`	date \| null	Date the ownership was observed or reported.
`shareholders`	Shareholder[] \| null	The people or entities holding this parcel. Each has `name`, optional `jurisdiction`, `company_number`, `identifier`, `type` (EntityType), `address`.

TotalShares

Field	Type	Description
`number`	integer	Required.
`share_class`	string \| null

AllAttributes

Extended fields for foreign-qualified entities, registered agents, and mergers.

Field	Type	Description
`jurisdiction_of_origin`	string \| null	Home state/country if this record is a foreign branch.
`home_company_number`	string \| null	Company number in the home jurisdiction.
`home_legal_name`	string \| null	Legal name in the home jurisdiction, if different.
`registered_agent_name`	string \| null	Person or entity accepting service of process.
`registered_agent_address`	string \| null	Address for service of process.
`number_of_employees`	string \| integer \| float \| null	Reported as-is. Some registries publish banded strings (e.g. `"10-49"`).
`merged_into`	object \| null	Set when this entity was merged into another. Contains `surviving_company` (`name`, `company_number`, `jurisdiction`) and `effective_date`.

Enums

BranchType

Value	Meaning
`"F"`	Foreign-qualified registration.
`"L"`	Local / domestic.

EntityType

Value	Meaning
`"Person"`	Natural person.
`"Company"`	Legal entity.

AlternativeNameType

Value	Meaning
`"trading"`	DBA / trade name.
`"abbreviation"`	Short form of the legal name.
`"legal"`	Alternate-language legal name.
`"alias"`	Known-as name.
`"unknown"`	Type not classified by the registry.

Example company

{
  "company_number": "5910230",
  "name": "VERTICAL VENTURES LLC",
  "jurisdiction_code": "us_de",
  "retrieved_at": "2026-04-09",
  "incorporation_date": "2021-06-08",
  "dissolution_date": null,
  "current_status": "Good Standing",
  "company_type": "Limited Liability Company",
  "registry_url": "https://icis.corp.delaware.gov/ecorp/entitysearch/...",
  "website": ["https://verticalventures.example"],
  "telephone_number": "+1-302-555-0199",
  "fax_number": null,
  "branch": "L",
  "registered_address": {
    "street_address": "1209 Orange St",
    "locality": "Wilmington",
    "region": "DE",
    "postal_code": "19801",
    "country": "United States",
    "country_code": "US"
  },
  "headquarters_address": {
    "street_address": "220 Main St, Suite 400",
    "locality": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country_code": "US"
  },
  "mailing_address": "PO Box 1024, Austin, TX 78767",
  "officers": [
    {
      "name": "Michael J. Torres",
      "position": "Member",
      "other_attributes": { "type": "Person" }
    }
  ],
  "filings": [
    {
      "title": "Annual Report",
      "date": "2025-02-28",
      "uid": "AR-2025-0291847",
      "filing_type_name": "Annual Report"
    },
    {
      "title": "Certificate of Formation",
      "date": "2021-06-08",
      "uid": "CF-2021-0591023",
      "filing_type_name": "Certificate of Formation"
    }
  ],
  "identifiers": [
    { "uid": "87-1234567", "identifier_system_code": "us_fein" }
  ],
  "industry_codes": [
    {
      "code": "541512",
      "code_scheme_id": "us_naics_2022",
      "name": "Computer Systems Design Services"
    }
  ],
  "previous_names": [
    { "company_name": "TORRES HOLDINGS LLC", "con_date": "2023-02-15" }
  ],
  "alternative_names": [
    { "company_name": "Vertical Ventures Capital", "type": "trading" }
  ],
  "total_shares": { "number": 10000, "share_class": "Common" },
  "all_attributes": {
    "registered_agent_name": "CT Corporation System",
    "registered_agent_address": "1209 Orange St, Wilmington, DE 19801",
    "number_of_employees": "10-49"
  }
}

​Company object

​Nested objects

​Address

​Officer

​Filing

​Identifier

​IndustryCode

​PreviousName

​AlternativeName

​ShareParcel

​TotalShares

​AllAttributes

​Enums

​BranchType

​EntityType

​AlternativeNameType

​Example company