NY APIapps.dos.ny.gov ↗
Search and retrieve New York Department of State corporation and business entity records, including filing history, registered agents, and officer info.
What is the NY API?
The NY DOS Business Entity API exposes 2 endpoints covering the New York Department of State's Corporation & Business Entity Database. Use search_entities to find companies by name or DOS ID with filters for status and entity type, and get_entity_detail to pull full records including filing history, registered agent, stock information, and principal executive officer data for any entity on file with New York State.
curl -X GET 'https://api.parse.bot/scraper/8ceea6f9-34d2-4d7f-adf1-fc7bdd90b476/search_entities?query=Apple&status=all&match_type=begins_with&search_type=name&entity_types=Corporation' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace apps-dos-ny-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: NY DOS entity search and detail lookup, bounded and re-runnable."""
from parse_apis.apps_dos_ny_gov_api import NyDos, MatchType, EntityNotFound
client = NyDos()
# Search for entities whose name begins with "Apple", cap total items fetched.
for summary in client.entity_summaries.search(query="Apple", match_type=MatchType.BEGINS_WITH, limit=5):
print(summary.entity_name, summary.dos_id, summary.status)
# Drill into the first result's full detail via .first() + navigation.
hit = client.entity_summaries.search(query="Apple", limit=1).first()
if hit is not None:
entity = hit.details()
print(entity.entity_name, entity.entity_type, entity.status)
print("Filed:", entity.date_of_initial_dos_filing, "County:", entity.county)
if entity.service_of_process_address is not None:
addr = entity.service_of_process_address
print("SOP:", addr.name, addr.street_address, addr.city, addr.state, addr.zip_code)
for filing in entity.filing_history:
print(filing.file_date, filing.document_type, filing.file_number)
for stock in entity.stock_info or []:
print(stock.stock_type, stock.quantity)
# Point lookup by a known DOS ID discovered from search.
if hit is not None:
try:
detail = client.entities.get(dos_id=hit.dos_id)
print(detail.entity_name, detail.jurisdiction)
except EntityNotFound:
print("Entity not found for dos_id", hit.dos_id)
print("exercised: entity_summaries.search / details / entities.get / filing_history / stock_info")
Search the NY DOS Corporation & Business Entity Database. Supports searching by entity name (with configurable match type: begins with, contains, or base word) or by DOS ID. Results can be filtered by entity status and entity type category. Returns paginated results with entity name, DOS ID, type, status, filing date, jurisdiction, and county. The upstream caps results at 300 entities per search; refine the query to find entities beyond that limit. Caller pagination uses page and limit (max 50 per page).
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (1-based). |
| limit | integer | Maximum number of results per page (max 50). |
| queryrequired | string | Entity name (at least 3 characters) or DOS ID to search for. |
| status | string | Filter results by entity status. |
| match_type | string | How to match the query against entity names. Only applicable when search_type is 'name'. |
| search_type | string | Whether to search by entity name or DOS ID. |
| entity_types | string | Comma-separated list of entity type categories to include: Corporation, LimitedLiabilityCompany, LimitedPartnership, LimitedLiabilityPartnership. When omitted, all types are searched. |
{
"type": "object",
"fields": {
"page": "integer current page number",
"limit": "integer results per page",
"total": "integer total number of matching entities (capped at 300 by upstream)",
"entities": "array of entity objects with entity_name, dos_id, entity_type, entity_type_category, status, initial_filing_date, jurisdiction, county, assumed_name, assumed_name_id",
"result_indicator": "string indicating match status from upstream"
},
"sample": {
"data": {
"page": 1,
"limit": 5,
"total": 300,
"entities": [
{
"county": "Kings",
"dos_id": "1577981",
"status": "Inactive",
"entity_name": "APPLE & PEACHES, INC.",
"entity_type": "DOMESTIC BUSINESS CORPORATION",
"assumed_name": null,
"jurisdiction": "New York, United States",
"assumed_name_id": null,
"initial_filing_date": "1991-09-26T00:00:00",
"entity_type_category": "CORPORATION"
}
],
"result_indicator": "EntityMatchFound"
},
"status": "success"
}
}About the NY API
Search and Filter Business Entities
The search_entities endpoint accepts an entity name (minimum 3 characters) or a DOS ID as the query parameter. When searching by name, the match_type parameter controls matching behavior: begins with, contains, or base word. Results can be filtered by status (Active, Inactive, etc.) and narrowed to specific entity type categories—Corporation, LimitedLiabilityCompany, LimitedPartnership, and others—using the entity_types parameter as a comma-separated list. Responses are paginated up to 50 results per page and include fields like entity_name, dos_id, entity_type, entity_type_category, status, initial_filing_date, and jurisdiction. Note that the upstream source caps total results at 300 regardless of how many matches exist.
Full Entity Detail Records
The get_entity_detail endpoint takes a dos_id (as returned by search_entities) and returns a complete entity record. This includes general identifiers (entity_name, entity_type, dos_id, status, jurisdiction, county, section_of_law), key dates (initial_filing_date, inactive_date), and structured sub-objects for service of process address, registered agent, CEO/principal executive officer, and principal executive office address. Stock information is returned as an array of objects with stock_type, stock_value, and quantity fields, or null if not applicable.
Filing History
The filing_history array in get_entity_detail lists every document on record for the entity. Each entry includes file_date, document_type, amendment_description, page_count, and file_number. This makes it possible to reconstruct the lifecycle of an entity—from initial formation through amendments, mergers, or dissolution filings—using only the DOS ID.
The NY API is a managed, monitored endpoint for apps.dos.ny.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when apps.dos.ny.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official apps.dos.ny.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Verify whether a New York LLC or corporation is currently active before entering a business relationship
- Look up the registered agent and service of process address for a specific entity by DOS ID
- Retrieve filing history to track amendments, name changes, or dissolution events over time
- Filter search results by entity type category (e.g., LimitedLiabilityCompany) and status to build a targeted business directory
- Cross-reference CEO and principal executive officer data against other public records
- Audit stock structure of a New York corporation using stock_type, stock_value, and quantity fields
- Map entity jurisdiction and county fields to identify where New York-registered foreign entities are originally formed
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does the New York Department of State offer an official developer API for this database?+
What does search_entities return when there are more than 300 matching records?+
total field in the response reflects this cap, not the true count of all matching entities. To narrow results below the cap, use the match_type, status, or entity_types filter parameters.Does get_entity_detail return document images or PDF filings?+
filing_history array returns metadata fields—file_date, document_type, amendment_description, page_count, and file_number—but not the actual document files or images. You can fork this API on Parse and revise it to add an endpoint that fetches associated document content.Does the API cover business entities from other US states?+
jurisdiction field can indicate that an entity was originally formed in another state, but only NY-registered entities are searchable. You can fork this API on Parse and revise it to target the equivalent public registry for other states.What entity types can be filtered in a search?+
entity_types parameter accepts a comma-separated list of categories. Supported values include Corporation, LimitedLiabilityCompany, and LimitedPartnership, among others. Each entity in search results also carries an entity_type string (the specific legal type) and an entity_type_category (the broader group used for filtering).