Look up a business entity or UCC filing by name and state

post/v1/lookup

Request

  • Base URL: https://api.opensosdata.com
  • URL: https://api.opensosdata.com/v1/lookup
  • Auth: one of:
    • API key in header x-api-key
    • none

Query parameters

freshboolean

Legacy parameter — all lookups now return fresh data by default.

Request body

entity_namestring required

Business name or debtor name to search

statestring required

Two-letter US state code

searchType'business_entity' | 'ucc'

Type of search to perform

searchBy'debtor' | 'secured_party'

Set to secured_party to search by secured party name instead of debtor. Supported states: AL, CA, CO, CT, FL, ID, KY, MA, MT, NC, RI, WV

dateAfterstring date

Filter to filings filed after this date (YYYY-MM-DD). Supported states: CO, CA, ID, MT

dateBeforestring date

Filter to filings filed before this date (YYYY-MM-DD). Supported states: CO, CA, ID, MT

source'auto' | 'cache' | 'live'

Data source preference. "auto" uses account settings, "cache" forces cached data (requires Cached Data subscription), "live" forces a live scrape from the state portal.

cache_preference'cache_only' | 'cache_first' | 'live_only'

Fine-grained cache behavior. "cache_only" returns cached data or 404 (never scrapes). "cache_first" returns cache if available, otherwise scrapes live. "live_only" always scrapes live.

fieldsstring[]

Return only these keys from the data object. Accepts a comma-separated string, repeated query params, or a JSON array in the request body. Envelope fields (success, cost, etc.) are always included. Unrecognised names appear in a warnings array in the envelope. Omit to receive the full response.

Response

Entity or UCC filing found

OR

Example response

{
  "success": true,
  "cost": 0.0314,
  "state_scraper_version": "3.0"
}

Changes

No recorded changes to this operation across all 1 revision of this API.