SCHEMA REFERENCE

Company object

The GovFiles dataset contains a single normalized Company object per entity.

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

Top-level fields

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

Field
Type
Req
Description
company_number
string
*
Unique ID assigned by the state registry (filing number, entity ID, etc). Stable across amendments.
name
string
*
Legal name as currently registered.
jurisdiction_code
string
*
Lowercase ISO 3166-2 style with underscore. us_de, us_ca, us_ny, etc.
retrieved_at
date
*
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[] · null
Company-owned URLs. Always an array (may be empty); null when the registry does not publish one.
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.
total_shares
TotalShares · null
Total number of authorized or issued shares, when disclosed.
all_attributes
AllAttributes · null
Extended fields: registered agent, foreign-qualification info, mergers, employee count.
(*) Required

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", etc.
other_attributes
object · null
Extra fields: type (EntityType) and 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.
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. "us_fein", "us_sec_cik", "lei", etc.

IndustryCode

Field
Type
Description
code
string
Required. e.g. "541512".
code_scheme_id
string
Required. "us_naics_2007", "uk_sic_2007", "eu_nace_2", etc.
name
string · null
Human-readable description of the code.

PreviousName

Field
Type
Description
company_name
string
Required.
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

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

"F"
Foreign-qualified registration.
"L"
Local / domestic.

EntityType

"Person"
Natural person.
"Company"
Legal entity.

AlternativeNameType

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

Full example

{
  "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"
  }
}