Massachusetts - Topograph

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.

Massachusetts coverage, pricing, and sources

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.

Data Sources
Company Identifiers
Search Capabilities
Quirks & Gotchas
Mappings
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.

All Massachusetts entity types

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

curl -X POST "https://api.topograph.co/v2/search?country=US-MA&query=Liberty+Mutual" \
  -H "x-api-key: YOUR_API_KEY"

[
  {
    "id": "000804945",
    "legalName": "SAMPLE HOLDINGS INC.",
    "countryCode": "US-MA",
    "matchReason": {
      "matchType": "default"
    },
    "address": {
      "city": "BOSTON",
      "region": "MA",
      "countryCode": "US"
    }
  }
]

Search by SoC ID

curl -X POST "https://api.topograph.co/v2/search?country=US-MA&query=000804945" \
  -H "x-api-key: YOUR_API_KEY"

[
  {
    "id": "000804945",
    "legalName": "SAMPLE HOLDINGS INC.",
    "countryCode": "US-MA",
    "matchReason": {
      "matchType": "id"
    }
  }
]

Company Profile (Onboarding)

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

{
  "company": {
    "id": "000804945",
    "countryCode": "US-MA",
    "identifiers": { "dlsId": "19dcdd187b79" },
    "legalName": "SAMPLE HOLDINGS INC.",
    "legalAddress": {
      "city": "BOSTON",
      "region": "MA",
      "countryCode": "US"
    }
  }
}

Company Profile (Verification)

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

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

​Start here

Massachusetts coverage, pricing, and sources

​Table of Contents

​Data Sources

​Company Identifiers

​Query Identifiers

​Identifiers in API Response

​Search Capabilities

​Quirks & Gotchas

​Mappings

​Legal Forms

​Officer Roles

​Company Status

​Data Availability

​Example API Responses

​Search by Name

​Search by SoC ID

​Company Profile (Onboarding)

​Company Profile (Verification)

Start here

Table of Contents

Data Sources

Company Identifiers

Query Identifiers

Identifiers in API Response

Search Capabilities

Quirks & Gotchas

Mappings

Legal Forms

Officer Roles

Company Status

Data Availability

Example API Responses

Search by Name

Search by SoC ID

Company Profile (Onboarding)

Company Profile (Verification)