> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topograph.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Massachusetts
> Country-specific identifiers, data sources, and integration details
## Start here
This guide contains public integration notes for Massachusetts. Use it for identifier formats, search behavior, and country-specific caveats. The live source of truth for coverage, pricing, data sources, documents, legal forms, roles, and status values is the pricing page.
Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
Country details below are preserved as integration notes. If a table or example conflicts with the live pricing page, use the pricing page as the source of truth and contact support.
## Table of Contents
* [Data Sources](#data-sources)
* [Company Identifiers](#company-identifiers)
* [Search Capabilities](#search-capabilities)
* [Quirks & Gotchas](#quirks--gotchas)
* [Mappings](#mappings)
* [Legal Forms](#legal-forms)
* [Officer Roles](#officer-roles)
* [Company Status](#company-status)
* [Data Availability](#data-availability)
**API access:** `US-MA` is not yet part of the public `countryCode` enum. Contact us to enable it on your workspace. Requests sent with `countryCode: "US-MA"` will otherwise return `400` until the enum is expanded.
## Data Sources
Massachusetts uses two data channels routed through a single block:
* **Massachusetts Corporations Book (DOR/DLS)** (onboarding, fast, non-authoritative). The Massachusetts Department of Revenue, Division of Local Services publishes an annual "Corporations Book" under G.L. c.58 §2. The book lists every entity subject to MA corporate excise, with name, location (city or home state/country for foreign entities), and an M/R/D excise-class flag. It covers approximately 339,000 entities and is the source for the fast path. Republished annually, so data may be up to twelve months stale.
* **Massachusetts Corporations Division** (verification, authoritative). The Secretary of the Commonwealth operates the online corporation search at `corp.sec.state.ma.us`. The live register covers every corporation, LLC, LP, LLP, professional entity, and nonprofit on file with the Commonwealth. It exposes the full entity profile: 9-digit internal ID, entity type, jurisdiction, filing date, status, addresses, registered agent, and the officer/director/manager roster from annual reports.
**Mode-based routing.** Onboarding requests (`mode: "onboarding"`) are served from the annual Corporations Book. Verification requests (`mode: "verification"`) query the live Secretary of the Commonwealth register and return the full officer roster and registered agent.
**DLS coverage scope.** The Corporations Book only includes entities currently subject to Massachusetts corporate excise. Dissolved, inactive, and many pass-through entities are excluded. If an entity is not found in onboarding mode, retry in verification mode against the live register.
## Company Identifiers
### Query Identifiers
| Identifier Type | Format | Example | Notes |
| -------------------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| **MA SoC Entity ID** | 9 digits, zero-padded | `000804945` | Internal entity number assigned by the Secretary of the Commonwealth. Some legacy entities carry an alphanumeric prefix. |
The MA SoC Entity ID is the canonical identifier for direct lookups. Onboarding-mode responses may carry a synthetic DLS identifier instead. See the note below on identifier promotion.
### Identifiers in API Response
| Identifier | Format | Example | Found in |
| ---------- | ----------------------- | -------------- | ------------------------------------------------------------------------ |
| `maSocId` | 9 digits, zero-padded | `000804945` | Entities fetched via the live register (verification mode) |
| `dlsId` | 12-character hex string | `19dcdd187b79` | Entities served from the annual Corporations Book (onboarding mode only) |
`dlsId` is a placeholder derived from the entity's name and location in the annual bulk publication. It carries no official register meaning. Once a live register query is made for the same entity, `maSocId` replaces it as the primary identifier.
## Search Capabilities
| Search Type | Pattern | Example | Match type | Expected results |
| ------------ | ----------- | ------------------ | ------------------------------ | ---------------------------------------------------------------------- |
| By Name | 2-100 chars | `"Liberty Mutual"` | Starts-with (case-insensitive) | Multiple results |
| By MA SoC ID | 9 digits | `000804945` | Exact | Exact match returned first (`matchType: id`); other results may follow |
**Onboarding search uses the Corporations Book.** Name search covers the \~339,000 entities in the annual publication. Dissolved or inactive entities are not included. For entities absent from search results, use `mode: "verification"` with a known MA SoC ID to query the live register directly.
## Quirks & Gotchas
| Quirk | Details |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Identifier promotion** | Onboarding responses carry a synthetic `dlsId`. When you later fetch the same entity in verification mode, the response carries the official `maSocId`. Update your records to the authoritative identifier after the first live-register fetch. |
| **Annual publication lag** | The Corporations Book is published once a year. Entities incorporated after the last publication date will not appear in onboarding-mode search results. Use `mode: "verification"` with a known SoC ID for recently incorporated entities. |
| **Status is inferred, not a register field** | The live register does not publish a discrete status field. Status is derived from merger and inactivity signals on the corporation summary page. The two observable values are `Active` and `Merged / Inactive`. |
| **Excise-class flag is not an industry code** | The M/R/D flag in the Corporations Book (manufacturing, revoked-manufacturing, R\&D) is a Massachusetts corporate excise exemption indicator, not an industry classification. No NAICS, NACE, or ISIC codes are collected by the Commonwealth. |
| **Officer data requires verification mode** | Officers, directors, and managers are populated from the entity's most recent annual report on the live register. They are not available in onboarding mode. |
| **Members of LLCs are generally not disclosed** | Massachusetts LLCs disclose only managers and persons authorized to validate documents in their annual reports. Members of member-managed LLCs are not disclosed unless they also hold a manager role. |
| **No shareholders or UBO register** | Massachusetts does not collect shareholder lists or beneficial-ownership data for any entity type. Federal BOI (FinCEN) is not accessible to private parties. |
| **DBAs are city-level filings** | Business certificates (doing-business-as names) are filed with the individual city or town clerk, not the state. There is no central DBA registry. |
| **Free-form officer titles** | MGL c.156D §8.40 mandates only President, Treasurer, and Secretary (or Clerk). All other officer titles on annual reports are free-form and normalized by AI enrichment. |
## Mappings
### Legal Forms
Legal form is sourced from the entity-type label on the Secretary of the Commonwealth Corporations Division. The vocabulary is derived from Massachusetts General Laws Title XXII (c.156D, c.156A, c.156C, c.180, c.109, c.108A). The full table with standardized categories and ISO 20275 codes is on the pricing page.
| SoC Entity Type | Standardized |
| -------------------------------------- | ----------------------- |
| Domestic Profit Corporation | Corporation |
| Foreign Profit Corporation | Corporation |
| Domestic Professional Corporation | Corporation |
| Foreign Professional Corporation | Corporation |
| Domestic Nonprofit Corporation | NonprofitOrganization |
| Foreign Nonprofit Corporation | NonprofitOrganization |
| Domestic Limited Liability Company | LimitedLiabilityCompany |
| Foreign Limited Liability Company | LimitedLiabilityCompany |
| Domestic Limited Partnership | Partnership |
| Foreign Limited Partnership | Partnership |
| Domestic Limited Liability Partnership | Partnership |
| Foreign Limited Liability Partnership | Partnership |
| Foreign Corporation | Corporation |
Onboarding-mode responses sourced from the Corporations Book do not carry an entity type. Legal form is populated only for verification-mode responses from the live register.
### Officer Roles
Massachusetts law (MGL c.156D §8.40 and §16.22) mandates a small set of statutory officer titles. All other titles filed on annual reports are free-form and normalized by AI enrichment.
| Role | Standardized | Notes |
| ---------------- | --------------- | --------------------------------------------------------------------------------- |
| President | President | Statutory officer under MGL c.156D §8.40 |
| Treasurer | Treasurer | Statutory officer under MGL c.156D §8.40 |
| Secretary | Secretary | Statutory officer under MGL c.156D §8.40 |
| Clerk | Secretary | Massachusetts-specific synonym for Secretary on for-profit corporations |
| Director | Director | Governed by MGL c.156D §16.22; classified as Other Key Person |
| Registered Agent | RegisteredAgent | Service-of-process contact under MGL c.156D §5.01; classified as Other Key Person |
President, Treasurer, Secretary, and Clerk are classified as Legal Representatives. Director and Registered Agent are Other Key Persons. Registered Agent has no authority to bind the entity.
### Company Status
Status is inferred from signals on the corporation summary page, not from a discrete register field. Two values are possible:
| Status | Meaning |
| ----------------- | --------------------------------------------------------------------- |
| Active | No merger record and no inactivity marker detected on the SoC summary |
| Merged / Inactive | A merger record or inactivity marker is present |
## Data Availability
| Data point | Available | Notes |
| --------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Company name | Yes | Current legal name |
| Company status | Verification only | Inferred from the live register summary; not available in onboarding mode |
| Registration date | Verification only | Filing date from the live register |
| Legal address | Yes | City for onboarding mode; full street address from the live register in verification mode |
| Legal form | Verification only | Not present in the Corporations Book; populated from the live register |
| Legal representatives | Verification only | Officers and managers from the most recent annual report |
| Registered agent | Verification only | From the live register corporation detail page |
| Activity codes | No | Not collected by the Commonwealth |
| Shareholders | No | Not published |
| UBOs | No | Federal FinCEN BOI is not publicly accessible |
| Documents | Roadmap | Annual reports, articles of organization, and certificates are accessible on the live register; document retrieval is planned for a future release |
| Financial data | No | Not collected |
| DBAs / assumed names | No | Filed at city/town clerk level; no central registry |
## Example API Responses
### Search by Name
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-MA&query=Liberty+Mutual" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "000804945",
"legalName": "SAMPLE HOLDINGS INC.",
"countryCode": "US-MA",
"matchReason": {
"matchType": "default"
},
"address": {
"city": "BOSTON",
"region": "MA",
"countryCode": "US"
}
}
]
```
### Search by SoC ID
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-MA&query=000804945" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
[
{
"id": "000804945",
"legalName": "SAMPLE HOLDINGS INC.",
"countryCode": "US-MA",
"matchReason": {
"matchType": "id"
}
}
]
```
### Company Profile (Onboarding)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-MA", "id": "000804945", "dataPoints": ["company"], "mode": "onboarding"}'
```
```json theme={null}
{
"company": {
"id": "000804945",
"countryCode": "US-MA",
"identifiers": { "dlsId": "19dcdd187b79" },
"legalName": "SAMPLE HOLDINGS INC.",
"legalAddress": {
"city": "BOSTON",
"region": "MA",
"countryCode": "US"
}
}
}
```
### Company Profile (Verification)
```bash theme={null}
curl -X POST "https://api.topograph.co/v2/company" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countryCode": "US-MA", "id": "000804945", "dataPoints": ["company", "legalRepresentatives"], "mode": "verification"}'
```
```json theme={null}
{
"company": {
"id": "000804945",
"countryCode": "US-MA",
"identifiers": { "maSocId": "000804945" },
"legalName": "SAMPLE HOLDINGS INC.",
"registrationDate": "1998-03-15",
"status": { "active": true, "localStatus": "Active" },
"legalForm": {
"localName": "Domestic Profit Corporation",
"standardized": "Corporation"
},
"legalAddress": {
"street": "123 State Street",
"city": "Boston",
"region": "MA",
"postalCode": "02109",
"countryCode": "US"
}
},
"legalRepresentatives": [
{
"individual": { "firstName": "Jane", "lastName": "Smith" },
"roles": [{ "localName": "President", "standardized": "President" }]
}
]
}
```