Record Classes
What recordClass and subjectType mean, the seven values they take, and why a Filed record is not always a registered company.
Why this field exists
Filed holds more than company registrations. Alongside Secretary of State registries, the corpus includes federal organisation registers, occupational licences, government vendor and payee lists, assistance awards, trade-name filings, registry events and employer filings. All of them answer to a name search, and before recordClass existed there was nothing in the response that told them apart.
Every record returned by /v1/search and /v1/entity/{id} now carries two fields:
| Field | Type | Description |
|---|---|---|
recordClass | string | What kind of record this is — one of the seven values below |
subjectType | string | organization or person |
Both are always present. They are derived from the record's publisher and its own type value — never from parsing the name — and they do not depend on which endpoint served the record.
Defaults. /v1/search returns only two of the seven classes by default — registry_entity and federal_registration — unless the caller passes record_class to widen or narrow that set (record_class=all removes the filter entirely). /v1/entity/{id} does not accept record_class and never filters: a lookup by id always returns the record regardless of class.
recordClass values
| Value | What it means |
|---|---|
registry_entity | An organisation on a register a state or territory holds itself — most often its corporate registrar, otherwise whichever state body publishes the register the record came from. The closest thing to "a company exists under this name here". |
federal_registration | An organisation recorded in a register maintained by a federal body. Evidence the organisation exists federally, not a state registration. |
filing_event | A dated filing in an organisation's record rather than a record of the organisation itself: a registry event such as an amendment, dissolution or reinstatement, or a filing made with a regulator. Evidence that something happened, not that an entity exists. |
license | A licence, authorisation or registration permitting an activity — occupational, professional, operating, contractor or spectrum. Says the holder is permitted to do something; says nothing about corporate form. |
name_registration | A claim on a name rather than on an entity — for example a trade name, DBA, name reservation or registration, trademark or service mark. There may or may not be a registered entity behind it. |
government_vendor | A record from a procurement, supplier or federal payment dataset. Evidence of a transaction with a government, not of a registration. |
financial_assistance_award | A grant, loan or direct payment to the subject — for example an SBA PPP loan. The record is about money received. |
Each definition is deliberately at least as broad as the set of records that carries the value. A value may describe a record you would not have predicted from its examples; it will not exclude one. registry_entity is additionally what a record gets when its source's class has not been determined, so it is the one value that can mean "classified conservatively" rather than "positively identified as a registration".
subjectType values
| Value | What it means |
|---|---|
organization | The subject is a company, non-profit, institution or other organisation. |
person | The subject is a natural person. |
Some datasets publish sole proprietors and individual licence holders in the same feed as companies, under the same record types. Those records are real and are not excluded, but they are about a person. subjectType is how you tell: a licence held by a named individual is { "recordClass": "license", "subjectType": "person" }, and treating it as a company — to send mail to, or to count as a business — is a mistake recordClass alone will not stop you making.
The authority axis: jurisdictionLevel and sourceAgency
recordClass says what kind of record this is. It does not say who asserted it, and that is a separate question — two measured records show it is also an independent one. md_moco_vendor rows are correctly government_vendor, and are still published as Maryland state government approval; the real registrar is Montgomery County. fcc_uls rows are correctly license, and are still published as a Washington Secretary of State entity type; the real authority is the Federal Communications Commission, with no connection to Washington State government. Getting recordClass right does not get this right, and no value of it can substitute for an answer.
Every record also carries:
| Field | Type | Description |
|---|---|---|
jurisdictionLevel | string or null | federal, state, county — or null if this release has no verified authority for the record's source |
sourceAgency | string or null | The real asserting body, e.g. "Internal Revenue Service", "Texas Comptroller of Public Accounts", "Montgomery County, Maryland" — or null alongside a null jurisdictionLevel |
Unlike recordClass and subjectType, these two fields can be null, and deliberately so. An unclassified source still gets a conservative recordClass, because a classification is always owed. sourceAgency makes the opposite trade-off: naming an asserting body nobody has verified is worse than naming none, so a source this axis has not measured resolves to null for both fields rather than a guess. As of this release, every published record's source resolves to a real jurisdictionLevel and sourceAgency — null is reserved for a source added after this page was last updated.
jurisdictionLevel splits the measured corpus federal 11,073,175 rows, state 19,443,935 rows, county 2,168 rows — the three subtotals reconcile exactly to the corpus total, 30,519,278, with every row answering to one of them.
This axis is independent of recordClass in both directions: a registry_entity can be county-level (md_moco_vendor), and a license can be federal (fcc_uls). Do not infer one from the other.
A note on the District of Columbia
DC has no county government, and its registrar (the DC Department of Licensing and Consumer Protection) is a state-equivalent body rather than a state or a county one — so federal / state / county has no value built for it. This release resolves DC's records to jurisdictionLevel: "state", on the basis that DC's registrar functions as the state-level authority for its jurisdiction. That placement is a documented judgment call pending confirmation, not a measured fact in the way the row counts above are — because jurisdictionLevel is a public API contract, it is flagged here rather than left to be inferred from the data. sourceAgency for DC records is unaffected either way: it already names the DC Department of Licensing and Consumer Protection specifically, not a generic "state" placeholder.
How to use them
- Filtering client-side. If you only want state-registered companies, keep
recordClass === "registry_entity". If you want any evidence the organisation exists in a government record, keep everything. - Branching on meaning. A
licenserecord has no formation date and usually no registered agent. That is the record being what it is, not missing data. - Counting. Do not treat a result count as a count of companies. One organisation can appear as several records of different classes, and
financial_assistance_awardandgovernment_vendorrows are frequently about organisations that also appear asregistry_entity. - Attribution. If you display who a record is registered with, or approved by, use
sourceAgency— not a blanket "Secretary of State" — and check it fornullfirst, since it is the one field on this page that can be.
Stability
The seven recordClass values above are the complete current set. New values may be added as new source types are ingested, and an existing value's definition may be widened when a source is classified into it — the definitions above are kept at least as broad as the records that carry them. A value will not be narrowed or repurposed. Which value an individual record carries is a separate fact, and it can change: we correct a source's placement when a review finds it wrong, a record whose source had not yet been classified moves off registry_entity once that source is classified, and a publisher can change a record's own type, which we do not control. We announce our own corrections as dated entries in the changelog; a publisher's relabelling reaches you without one. Branch on the value, not on a record keeping it. Treat an unrecognised recordClass value as "a kind of record this client does not know about" rather than as an error: recordClass and subjectType are always a non-empty string, never null and never absent, so a client can branch on them without a presence check.
jurisdictionLevel and sourceAgency carry the same non-narrowing promise for the values above, with one difference already noted: either field can legitimately be null for a source this axis has not yet measured, so — unlike recordClass — a presence check on these two is required, not optional.