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

# New York (US)

> Country-specific identifiers, data sources, and integration details

## Start here

This guide contains public integration notes for New York. 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.

<Card title="New York coverage, pricing, and sources" icon="arrow-up-right-from-square" href="https://topograph.co/pricing/us-ny">
  Open the current catalog for supported datapoints, documents, sources, identifiers, and availability.
</Card>

<Warning>
  This jurisdiction may be in preview or limited availability. Check the live pricing page or contact support before relying on it in production.
</Warning>

<Note>
  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.
</Note>

## 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)
  * [Company Status](#company-status)
  * [Officer Roles](#officer-roles)
* [Data Availability](#data-availability)

<Warning>
  **API access:** `US-NY` is not yet part of the public `countryCode` enum. Contact us to enable it on your workspace. Requests sent with `countryCode: "US-NY"` will otherwise return `400` until the enum is expanded.
</Warning>

## Data Sources

New York State uses two complementary integrations against the **New York Department of State, Division of Corporations**. Both serve the same underlying database of \~4.2M active business entities.

* **Public Inquiry portal** (live, authoritative). The official interactive register at apps.dos.ny.gov. Returns the richest record: authorized stock share info, next biennial statement due date, and four separated addresses (service-of-process, registered agent, principal executive office, entity location). Used for `mode: "verification"` requests.

* **NYS Open Data snapshot** (fast, non-authoritative). A daily refresh of the same DOS database published at data.ny.gov. Used for sub-second onboarding checks, company search, and former and assumed name matching. Lag is at most one day.

<Note>
  **Mode-based routing.** Onboarding requests (`mode: "onboarding"`) hit the
  deduplicated snapshot for speed. Verification requests (`mode: "verification"`) hit
  both sources in parallel and merge the richer live fields on top of the
  snapshot.
</Note>

<Warning>
  **Biennial cadence.** New York corporations file a biennial statement every
  two years. Officer and CEO data can lag up to 24 months behind ground truth.
  The `next statement due date` field (verification mode only) surfaces when
  the entity is next due to refresh its information.
</Warning>

## Company Identifiers

### Query Identifiers

| Identifier Type | Format     | Example | Notes                                     |
| --------------- | ---------- | ------- | ----------------------------------------- |
| **DOS ID**      | 6-8 digits | `30059` | NY Department of State primary identifier |

<Tip>
  The DOS ID is the only identifier supported for company retrieval. To find a
  DOS ID from a name, use the search endpoint first.
</Tip>

### Identifiers in API Response

| Identifier | Format     | Example | Found In     |
| ---------- | ---------- | ------- | ------------ |
| `dosId`    | 6-8 digits | `30059` | All entities |

## Search Capabilities

| Search Type     | Pattern     | Example                | Match Type | Expected Results                                                     |
| --------------- | ----------- | ---------------------- | ---------- | -------------------------------------------------------------------- |
| By Name         | 2-100 chars | `"International Busi"` | Fuzzy      | Multiple results                                                     |
| By Former Name  | 2-100 chars | `"Bell Atlantic"`      | Fuzzy      | Multiple results                                                     |
| By Assumed Name | 2-100 chars | `"Verizon"`            | Fuzzy      | Multiple results                                                     |
| By DOS ID       | 6-8 digits  | `30059`                | Exact      | Exact match returned first (matchType: id); other results may follow |

<Note>
  **Former name search.** Entities often change legal names. Searching for a
  former name (for example `"Bell Atlantic"`) will surface the current entity
  (`"Verizon Communications Inc."`) via the DOS name history dataset.
</Note>

## Quirks & Gotchas

| Quirk                                   | Details                                                                                                                                                                                           |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No LLC officer data**                 | New York DOS does not collect or publish LLC member, manager, or officer information. For LLC entities the legal-representatives response will always be empty.                                   |
| **Corporations disclose CEO only**      | Biennial statements only disclose the CEO of a corporation. Directors, Vice Presidents, Secretaries, and other officers are not published by DOS.                                                 |
| **No shareholder or UBO register**      | New York does not publish shareholders or beneficial owners for any entity type.                                                                                                                  |
| **No activity codes**                   | DOS does not collect NAICS or industry codes. The NY Department of Taxation and Finance holds NAICS for tax purposes but does not publish it openly.                                              |
| **DBAs live at county clerks**          | Assumed name (DBA) filings go to the county clerk, not DOS. A mandatory 2-newspaper-for-6-weeks publication requirement makes many small businesses skip formal DBA filing.                       |
| **Certified documents are paid + mail** | Certified copies of formation documents and Good Standing certificates are paid (see [pricing](https://www.topograph.co/pricing)) and delivered by mail only. No free electronic download exists. |
| **Registered agent vs SOP agent**       | In verification mode the response separates three distinct roles: the registered agent (formal service), the SOP agent (service of process on the DOS), and the CEO from the biennial statement.  |

## Mappings

### Company Status

Status comes from the DOS entity status field. Dissolution, merger, and surrender statuses are all mapped to `active: false`.

| Source Value                             | Mapped Status | Active  |
| ---------------------------------------- | ------------- | ------- |
| `ACTIVE`                                 | Active        | `true`  |
| `INACTIVE - Dissolution by Proclamation` | Dissolved     | `false` |
| `INACTIVE - Merged Out`                  | Merged        | `false` |
| `INACTIVE - Voluntary Dissolution`       | Dissolved     | `false` |
| `INACTIVE - Surrender of Authority`      | Withdrawn     | `false` |

### Legal Forms

Legal form is derived from the DOS `entity_type` field. Closed vocabulary of \~20 values covering domestic and foreign variants of every supported entity class.

<AccordionGroup>
  <Accordion title="Common DOS entity types">
    | DOS Entity Type                        | Standardized                  | ISO 20275 |
    | -------------------------------------- | ----------------------------- | --------- |
    | DOMESTIC BUSINESS CORPORATION          | Corporation                   | `C5K7`    |
    | FOREIGN BUSINESS CORPORATION           | Corporation                   | `C5K7`    |
    | DOMESTIC LIMITED LIABILITY COMPANY     | Limited Liability Company     | `WYG5`    |
    | FOREIGN LIMITED LIABILITY COMPANY      | Limited Liability Company     | `WYG5`    |
    | DOMESTIC LIMITED PARTNERSHIP           | Limited Partnership           | `FE1L`    |
    | FOREIGN LIMITED PARTNERSHIP            | Limited Partnership           |           |
    | DOMESTIC LIMITED LIABILITY PARTNERSHIP | Limited Liability Partnership | `LA8V`    |
    | FOREIGN LIMITED LIABILITY PARTNERSHIP  | Limited Liability Partnership |           |
    | DOMESTIC NOT-FOR-PROFIT CORPORATION    | Non-Profit Organization       | `OGSS`    |
    | FOREIGN NOT-FOR-PROFIT CORPORATION     | Non-Profit Organization       |           |
    | DOMESTIC PROFESSIONAL CORPORATION      | Professional Corporation      | `9AAS`    |
  </Accordion>
</AccordionGroup>

### Officer Roles

New York discloses only three named roles per entity. There is no free-text field, so all three are deterministic (no AI enrichment required).

| DOS Role         | Standardized            | Notes                                 |
| ---------------- | ----------------------- | ------------------------------------- |
| CEO              | Chief Executive Officer | Biennial statement, corporations only |
| Registered Agent | Other                   | Statutory service-of-process contact  |
| SOP Agent        | Other                   | Service-of-process on the DOS itself  |

<Note>
  Registered Agent and SOP Agent are classified as Other Key Persons, not Legal
  Representatives. They have no statutory authority to bind the entity.
</Note>

## Data Availability

| Data Point             | Available | Notes                                                                                                     |
| ---------------------- | --------- | --------------------------------------------------------------------------------------------------------- |
| Company name           | Yes       | Current legal name plus former legal names (searchable)                                                   |
| Former names           | Yes       | From DOS name history dataset. Indexed for search.                                                        |
| Assumed names          | Yes       | DOS-filed assumed names only. County-clerk DBAs are out of scope.                                         |
| Company status         | Yes       | ACTIVE plus 8 INACTIVE variants mapped to standardized statuses                                           |
| Registration date      | Yes       | DOS initial filing date                                                                                   |
| Legal address          | Yes       | Verification mode returns four separated addresses: SOP, registered agent, principal executive, location. |
| Legal form             | Yes       | Closed DOS entity-type vocabulary with ISO 20275 mapping                                                  |
| Authorized stock       | Yes\*     | Verification mode only. Includes stock type, par value, quantity.                                         |
| Next biennial due date | Yes\*     | Verification mode only. Indicates when officer and address data will next refresh.                        |
| Filing history         | Yes       | Every filing event against the entity (20.5M-row dataset)                                                 |
| Merger history         | Yes       | Constituents of merger filings                                                                            |
| Legal representatives  | Yes\*     | Corporations return the CEO. LLCs, LPs, and not-for-profits return none.                                  |
| Other key persons      | Yes       | Registered Agent and SOP Agent                                                                            |
| Activity codes         | No        | Not collected by DOS                                                                                      |
| Shareholders           | No        | Not published                                                                                             |
| UBOs                   | No        | Not published (federal CTA/FinCEN is a separate system)                                                   |
| Documents              | No        | Certified copies are paid and mailed only                                                                 |
| Financial data         | No        | Not collected                                                                                             |

## Example API Responses

### Search by Name

```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-NY&query=INTERNATIONAL+BUSINESS+MACHINES" \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
[
  {
    "id": "30059",
    "legalName": "INTERNATIONAL BUSINESS MACHINES CORPORATION",
    "countryCode": "US-NY",
    "matchReason": {
      "matchType": "default"
    },
    "address": {
      "region": "NY",
      "countryCode": "US"
    }
  }
]
```

### Search by Former Name

```bash theme={null}
curl -X POST "https://api.topograph.co/v2/search?country=US-NY&query=BELL+ATLANTIC" \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
[
  {
    "id": "1898443",
    "legalName": "VERIZON COMMUNICATIONS INC.",
    "countryCode": "US-NY",
    "matchReason": {
      "matchType": "previousName"
    }
  }
]
```

### Company Profile (Onboarding Mode)

```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-NY", "id": "30059", "dataPoints": ["company", "legalRepresentatives"], "mode": "onboarding"}'
```

```json theme={null}
{
  "company": {
    "id": "30059",
    "countryCode": "US-NY",
    "identifiers": { "dosId": "30059" },
    "legalName": "INTERNATIONAL BUSINESS MACHINES CORPORATION",
    "registrationDate": "1911-06-16",
    "status": { "localName": "Active", "active": true },
    "legalForm": {
      "localName": "DOMESTIC BUSINESS CORPORATION",
      "standardized": "Corporation",
      "iso20275Code": "C5K7"
    },
    "legalAddress": {
      "city": "ARMONK",
      "region": "NY",
      "countryCode": "US"
    }
  },
  "legalRepresentatives": []
}
```

### Company Profile (Verification Mode)

Verification mode adds authorized stock, next biennial due date, and four separated addresses from the authoritative live portal.

```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-NY", "id": "30059", "dataPoints": ["company", "legalRepresentatives"], "mode": "verification"}'
```