API reference — Netstate

Introduction

The Netstate API is organized around a single resource — the business — a company anchored on its Secretary-of-State registration and enriched at query time with every public-record category we track for it. Endpoints accept standard query parameters and return JSON.

Responses always carry the complete schema: a section with no data is an empty array, an empty list object or null — never a missing key. Fields we republish verbatim from a registry keep the registry’s wording; every record-level object carries its source pipeline and the original fields under record.

The open, keyless demo endpoints at netstate.co/v1 (documented at /api.md) are unaffected; this reference covers the production data API.

Base URL

https://api.netstate.co/v1

First request

curl "https://api.netstate.co/v1/businesses?q=acme&state=tx" \
  -H "x-api-key: YOUR_API_KEY"

Authentication

Authenticate with an API key, passed as an x-api-key header or an Authorization: Bearer header. All endpoints except /health require a key. (An api_token query parameter is still accepted for older integrations, but keys in URLs end up in logs and browser history — prefer the header.)

Keys are provisioned per workspace with a daily request cap (10,000 by default); check your usage with GET /v1/account. To get a key, contact us or see plans.

Header (recommended)

curl "https://api.netstate.co/v1/account" \
  -H "x-api-key: YOUR_API_KEY"

Bearer token

curl "https://api.netstate.co/v1/account" \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

Errors return a conventional HTTP status and a JSON body with an errors array.

400 — malformed request (bad id, missing q, page too deep)
401 — missing or invalid API key
403 — daily call limit reached
404 — no business with that id
502 — upstream datastore unavailable; retry with backoff

Error shape

{
  "errors": [
    { "message": "business us-tx-000000000 not found" }
  ]
}

Pagination

Every collection endpoint returns a list object: {"object": "list", "data": [...], "has_more", "total_count", "page", "per_page"}. Page with page (1-based) and per_page (max 100); windows deeper than 10,000 results return 400.

Record sections embedded in a business object use the same list shape with the 10 most recent rows inline; fetch the rest from the section’s own endpoint.

Request

curl "https://api.netstate.co/v1/businesses/us-fl-M99000000591/liens?page=2&per_page=50" \
  -H "x-api-key: YOUR_API_KEY"

The business object

The id is deterministic: us-{state}-{file_number}. Core attributes come from the state registration; record sections are matched to the company by legal name within its state and linked with a match confidence on every row.

Attributes

statusstring

Registry standing, normalized: active, inactive or unknown. The registry’s verbatim wording is on registrations[].status.

formationobject

Entity type, formation date and state from the anchor registration.

registrationsarray

Secretary-of-State registrations. One entry today — the anchor jurisdiction; foreign registrations land here as coverage grows.

namesarray

Legal and alternative names observed across sources.

peoplearray

Officers known for the company; currently the registered agent.

tinobject · nullable

EIN when a tax identifier has been matched, else null.

liens / loans / fmcsa_registrations / licenses / permits / federallist objects

Public-record sections: UCC liens, SBA PPP loans, FMCSA carrier registrations, state licenses, permits, and the remaining federal datasets (SAM, H-1B, E-Verify, Medicare/NPI, IRS 990, FEC, Form 5500, SEC and more).

watchlist / review / documents / …varies

Present for schema stability; populate as verification features ship. Today watchlist is an empty result set and review, monitor, website are null.

The business object

{
  "object": "business",
  "id": "us-tx-803212845",
  "external_id": null,
  "name": "ACME WIDGETS LLC",
  "status": "active",
  "created_at": "2026-08-15T22:41:07Z",
  "updated_at": "2026-08-16T07:58:12Z",
  "tags": [],
  "formation": {
    "entity_type": "Domestic Limited Liability Company (LLC)",
    "formation_date": "2019-03-14",
    "formation_state": "TX"
  },
  "registrations": [
    {
      "object": "registration",
      "id": "us-tx-803212845",
      "state": "TX",
      "status": "In existence",
      "entity_type": "Domestic Limited Liability Company (LLC)",
      "file_number": "803212845",
      "registration_date": "2019-03-14",
      "name": "ACME WIDGETS LLC",
      "addresses": [
        {
          "object": "address",
          "full_address": "1200 MAIN ST STE 4, HOUSTON, TX 77002",
          "address_line1": null,
          "address_line2": null,
          "city": null,
          "state": "TX",
          "postal_code": "77002"
        }
      ],
      "officers": [],
      "source": "us_tx_sos_lookup"
    }
  ],
  "names": [
    {
      "object": "name",
      "name": "ACME WIDGETS LLC",
      "type": "legal",
      "sources": [
        { "object": "source", "type": "registration", "id": "us-tx-803212845" }
      ]
    },
    { "object": "name", "name": "ACME WIDGET CO", "type": "alternative", "sources": [] }
  ],
  "addresses": [
    {
      "object": "address",
      "full_address": "1200 MAIN ST STE 4, HOUSTON, TX 77002",
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "state": "TX",
      "postal_code": "77002"
    }
  ],
  "people": [
    {
      "object": "person",
      "name": "JANE DOE",
      "titles": [{ "object": "person_title", "title": "Registered Agent" }],
      "sources": [
        { "object": "source", "type": "registration", "id": "us-tx-803212845" }
      ]
    }
  ],
  "tin": { "object": "tin", "tin": "742938475" },
  "industry_classification": null,
  "website": null,
  "phone_numbers": [],
  "email_addresses": [],
  "profiles": [],
  "watchlist": { "object": "watchlist", "hit_count": 0, "agencies": [], "lists": [] },
  "liens": {
    "object": "list",
    "total_count": 2,
    "data": [
      {
        "object": "lien",
        "type": "ucc",
        "filing_number": "19-0032178965",
        "filed_date": "2023-06-01",
        "state": "TX",
        "status": "Active",
        "expiration_date": "2028-06-01",
        "secured_parties": ["FIRST NATIONAL BANK"],
        "debtors": ["ACME WIDGETS LLC"],
        "collateral": "ALL ASSETS",
        "source": "us_tx_ucc_filings",
        "match": { "method": "name_state_unique", "confidence": 0.85 },
        "record": { "…": "original registry fields, verbatim" }
      }
    ]
  },
  "loans": {
    "object": "list",
    "total_count": 1,
    "data": [
      {
        "object": "loan",
        "type": "ppp",
        "amount": 128400,
        "date": "2020-04-28",
        "lender": "FROST BANK",
        "status": "Paid in Full",
        "jobs_reported": 11,
        "forgiveness_amount": 129012.5,
        "source": "us_sba_ppp_loans",
        "match": { "method": "name_state_unique", "confidence": 0.85 },
        "record": { "…": "…" }
      }
    ]
  },
  "fmcsa_registrations": { "object": "list", "total_count": 0, "data": [] },
  "licenses": { "object": "list", "total_count": 0, "data": [] },
  "permits": { "object": "list", "total_count": 0, "data": [] },
  "federal": { "object": "list", "total_count": 0, "data": [] },
  "documents": [],
  "bankruptcies": [],
  "litigations": [],
  "certifications": [],
  "orders": [],
  "review": null,
  "monitor": null
}

Search businesses

GET/v1/businesses

Full-text search over all names a company has been seen under. Returns sparse business objects; follow id for the full profile.

Query parameters

qstring · required

Company name query. All terms must match.

statestring

Two-letter state (tx) or jurisdiction code (us_tx).

statusstring

Filter on the registry’s verbatim status value.

entity_typestring

Filter on the registry’s verbatim entity type.

sortstring

registration_date for newest-first; default is relevance.

liveboolean

With a state that has a live parser, runs a Secretary-of-State lookup first so brand-new filings appear. Adds up to ~20s.

Request

curl "https://api.netstate.co/v1/businesses?q=acme+widgets&state=tx" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "object": "business",
      "id": "us-tx-803212845",
      "name": "ACME WIDGETS LLC",
      "status": "active",
      "entity_type": "Domestic Limited Liability Company (LLC)",
      "formation_state": "TX",
      "formation_date": "2019-03-14",
      "file_number": "803212845",
      "full_address": "1200 MAIN ST STE 4, HOUSTON, TX 77002"
    }
  ],
  "has_more": true,
  "total_count": 274,
  "page": 1,
  "per_page": 30
}

Get a business

GET/v1/businesses/{id}

Retrieves the full business object, with the 10 most recent rows of every record section inline.

Query parameters

refreshboolean

Re-pulls the company from the state’s Secretary-of-State (and UCC, where live parsers exist) before responding. Adds up to ~15s per lookup; lookup failures degrade gracefully to stored data.

sparseboolean

Skips the record sections for a faster response; their total_count comes back as null (“not fetched”, distinct from zero).

Request

curl "https://api.netstate.co/v1/businesses/us-tx-803212845" \
  -H "x-api-key: YOUR_API_KEY"

Live refresh

curl "https://api.netstate.co/v1/businesses/us-tx-803212845?refresh=true" \
  -H "x-api-key: YOUR_API_KEY"

List liens

GET/v1/businesses/{id}/liens

UCC financing statements matched to the business, newest first. Registries publish different shapes — some file-level, some one row per party — so the normalized head fields are best-effort and the registry’s original fields ride along under record.

Lien attributes

filing_numberstring

The UCC filing number as issued.

statusstring · nullable

Registry wording — Active, Lapsed, etc.

secured_parties / debtorsarrays

Party names where the registry provides them.

expiration_datestring · nullable

Lapse date, where published.

Request

curl "https://api.netstate.co/v1/businesses/us-fl-M99000000591/liens?per_page=1" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "object": "lien",
      "type": "ucc",
      "filing_number": "200100139363",
      "filed_date": null,
      "state": "FL",
      "status": "Lapsed",
      "expiration_date": null,
      "secured_parties": ["SNAP-ON CREDIT LLC"],
      "debtors": [],
      "collateral": null,
      "source": "us_fl_ucc_filings",
      "match": { "method": "name_state_unique", "confidence": 0.85 },
      "record": { "…": "…" }
    }
  ],
  "has_more": true,
  "total_count": 165995,
  "page": 1,
  "per_page": 30
}

Licenses & permits

GET/v1/businesses/{id}/licenses · /v1/businesses/{id}/permits

Professional and business licenses (38M) and building/trade permits (118M) matched to the business. Items carry a unified head — name, number, date, state, source — plus the issuing register’s original fields under record.

Request

curl "https://api.netstate.co/v1/businesses/us-tx-803212845/licenses" \
  -H "x-api-key: YOUR_API_KEY"

Federal records

GET/v1/businesses/{id}/federal

Everything from the federal datasets that isn’t a lien: SAM contractor registrations, H-1B LCAs, E-Verify enrollment, Medicare/NPI providers, IRS 990 filings, FEC records, Form 5500 plans, SEC filings, customs manifests and more.

Each item is typed by its source: FMCSA rows come back as fmcsa_registration, PPP rows as loan, the rest as record with a type slug derived from the pipeline.

Request

curl "https://api.netstate.co/v1/businesses/us-co-19931003706/federal" \
  -H "x-api-key: YOUR_API_KEY"

Search people

GET/v1/people

Search companies by the people on file. Coverage today is registered agents; officer rosters expand as registries publish them.

Query parameters

qstring · required

Person or firm name. All terms must match.

statestring

Restrict to one state.

Request

curl "https://api.netstate.co/v1/people?q=jane+doe&state=tx" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "object": "person",
      "name": "JANE DOE",
      "titles": [{ "object": "person_title", "title": "Registered Agent" }],
      "business": {
        "object": "business",
        "id": "us-tx-803212845",
        "name": "ACME WIDGETS LLC",
        "status": "active",
        "entity_type": "Domestic Limited Liability Company (LLC)",
        "formation_state": "TX",
        "formation_date": "2019-03-14",
        "file_number": "803212845",
        "full_address": "1200 MAIN ST STE 4, HOUSTON, TX 77002"
      }
    }
  ],
  "has_more": false,
  "total_count": 1,
  "page": 1,
  "per_page": 30
}

Jurisdictions

GET/v1/jurisdictions

Coverage map: company counts per state, whether the data arrived by bulk load, and whether live Secretary-of-State (live_sos) and UCC (live_ucc) lookups are wired for refresh / live requests.

Response

{
  "object": "list",
  "data": [
    {
      "object": "jurisdiction",
      "code": "us_tx",
      "company_count": 3315223,
      "bulk": true,
      "live_sos": true,
      "live_ucc": false
    },
    {
      "object": "jurisdiction",
      "code": "us_fl",
      "company_count": 12607154,
      "bulk": true,
      "live_sos": false,
      "live_ucc": false
    }
  ],
  "has_more": false,
  "total_count": 62,
  "page": 1,
  "per_page": 62
}

Account

GET/v1/account

Usage against your key’s daily cap. The counter resets at midnight UTC.

Response

{
  "object": "account",
  "usage_today": 412,
  "daily_limit": 10000
}