GET/search

Entity search

Search business entities by name and state. Every state is normalized into one fixed envelope: the best match plus similar filings, each with status, registered agent, officers, and addresses.

Query parameters

Parameter	Type	Required	Description
`state`	string	Yes	Two-letter code or full name, e.g. "WY" or "wyoming".
`business_name`	string	Yes	Business name to search for.
`by`	string	No	Defaults to "name". Set it to the state’s registry-ID field to look one record up directly — e.g. "entityId" (NY, CA, …), "documentNumber" (FL), "fileNumber" (DE), "filingNumber" (AR), "controlNumber" (GA). An ID lookup returns exactly one record.

Request

curl 'https://api.sosfinder.com/search?state=WY&business_name=Acme%20LLC' \
  -H "x-api-key: $SOS_API_KEY"

Response

One fixed schema for all states. bestMatch is the top record (or null); results lists the best match first, then similar filings. Fields a state doesn’t publish come back null (or [] for officers, filings, and documents).

{
  "state": "FL",
  "stateName": "Florida",
  "success": true,
  "query": "Acme LLC",
  "searchBy": "name",
  "count": 3,
  "bestMatch": {
    "name": "ACME LLC",
    "entityId": "L19000123456",
    "stateEntityId": null,
    "oldNames": [],
    "status": "Active",
    "statusReason": null,
    "subStatus": null,
    "entityType": "Florida Limited Liability Company",
    "entityTypeDescription": "LIMITED LIABILITY COMPANY",
    "standing": null,
    "formationDate": "04/08/2019",
    "effectiveDate": "04/08/2019",
    "jurisdiction": "FL",
    "feiEin": "59-1234567",
    "naicsCode": "531210",
    "naicsDescription": "Offices of Real Estate Agents",
    "registeredAgentName": "Jane Doe",
    "registeredAgentAddress": "123 Main St, Tampa, FL 33601",
    "officers": [
      { "name": "Jane Doe", "title": "President",
        "address": "123 Main St, Tampa, FL 33601" }
    ],
    "principalOfficeAddress": "123 Main St, Tampa, FL 33601",
    "mailingAddress": "PO Box 100, Tampa, FL 33601",
    "serviceOfProcessName": null,
    "filings": [
      { "name": "Annual Report 2026", "date": "01/15/2026", "id": null }
    ],
    "filingHistory": [],
    "annualReports": [],
    "documents": [
      { "title": "01/15/2026 -- ANNUAL REPORT",
        "url": "https://search.sunbiz.org/...pdf" }
    ],
    "sosUrl": "https://search.sunbiz.org/...",
    "detailAvailable": true,
    "…": "60+ normalized fields in total — see the field guide below"
  },
  "results": [ "…best match first, then similar filings…" ],
  "error": null,
  "blocked": false
}

Record fields

Every record is normalized into the same 60+ field schema; a state fills the fields it publishes and the rest come back null. The most useful ones:

Field	Type	Description
`name`	string	Legal name of the entity.
`entityId`	string	The state’s public identifier (DOS ID, document number, …) — also the ID for by-ID lookups and monitors.
`stateEntityId`	string	Secondary registry ID, where a state keeps two.
`oldNames`	string[]	Previous legal names, where the state publishes name history.
`status`	string	e.g. Active, Inactive, Dissolved.
`statusReason`	string	Why the entity holds its status (with subStatus), where reported.
`entityType`	string	Entity type as the state labels it; entityTypeDescription carries the long form.
`standing`	string	Good-standing flag — some states split it into arStanding / raStanding / revenueStanding / otherStanding.
`formationDate`	string	Date the entity was formed, as the state formats it. effectiveDate, dissolutionDate, and revivalDate cover the rest of the lifecycle.
`feiEin`	string	Federal employer ID (FEI/EIN), where published (Florida).
`naicsCode`	string	Industry NAICS code, with naicsDescription, where published.
`registeredAgentName`	string	Registered agent of record, with registeredAgentAddress / City / State / Zip and a separate mailing address.
`serviceOfProcessName`	string	Who accepts legal service, with serviceOfProcessAddress (New York).
`officers`	object[]	Officers / directors / members: {name, title, address} — only some states publish these.
`filings`	object[]	Filing / annual-report history: {name, date, id}. filingHistory and annualReports carry richer per-state detail.
`documents`	object[]	Downloadable document PDFs: {title, url}.
`sosUrl`	string	Deep link to the record on the state’s own site.
`detailAvailable`	boolean	False for list-only registries with no per-entity detail page.
`raw`	object	The state’s original unmapped payload, for anything the schema doesn’t cover.

Errors and blocks

Zero matches return success: false with an empty results list. If a state registry temporarily blocks automated lookups, the API retries and — only if every attempt is blocked — returns blocked: true; try again shortly.