Secretary of State Business Entity Search + UCC Liens — KYB

Verify a US company and see the liens against it in one call. Search official state business registries by company name for the normalized entity record — legal name, ID, type, status, formation date, registered agent, officers — and get each entity joined to its UCC / lien filings where covered. Built for KYB, lending, and diligence agents that need to answer "is this company real, in good standing, and does it already have liens against its assets?" without stitching two systems together.

Due diligence check for lending, merchant cash advance and KYB. Set reportType to "due_diligence" and each resolved company whose identity is confirmed also comes back with its registry status read at run time (timestamped, with a normalized standing), its financing over the last 90 days and 12 months from the UCC join (new financing statements and how many distinct secured parties filed them), its time in business, a U.S. Treasury sanctions-list screen, and recorded liens against the company. It checks companies, not their owners or guarantors. A company with no match isn't charged. See Due diligence check.

What this does

• Business entity search by company name across 49 states + DC in one call — the lookup you'd otherwise run on each state's Secretary of State business search, returned as a single normalized record per matched entity (company-registration lookup / business-entity verification).
• Entity → UCC lien join. Where lien-join coverage is available, each resolved entity is joined to the Uniform Commercial Code (secured-transaction) filings recorded against it as debtor — filing number, type, status, filed/lapse dates, secured party (lender), and collateral. This is the differentiator: entity search and lien search, connected, keyed by the debtor's legal name.
• Normalized fields per entity: legal name, state entity/registration ID, entity type, registration status (e.g. Good Standing, Active, Forfeited, Dissolved), formation/registration date, jurisdiction of formation, registered agent, principal / mailing address, and officers where the state publishes them.
• Registered agent lookup and company officers search, included. Every completed record carries the registered agent's name (and address where the state publishes it) plus the officer / director roster where published — a registered agent search or corporate officers lookup by company name is the same single call, with no separate enrichment charge.
• Multi-state in one request — pass a company name, optionally scope to a list of states, and get one record per matched entity across every covered state.
• KYB / diligence use cases: confirm a counterparty is registered and in good standing, check whether a borrower's assets are already encumbered before lending, enrich a CRM/onboarding record with the legal entity + lien picture, screen an acquisition target, or resolve which state(s) a company is registered in.
• Deterministic and agent-callable. Every result carries a machine-readable status (completed / no_match / not_covered / failed), an explicit lien_coverage outcome, and structured field_notes explaining any field that is structurally absent, so an agent can reason about coverage instead of guessing.

Entity search covers 49 states + DC; lien joins cover 31 states + DC.

State	Entity search	UCC lien join
Alaska (AK)	clean	clean
Alabama (AL)	clean	clean
Arkansas (AR)	clean	clean
Arizona (AZ)	extended	none
California (CA)	extended	extended
Colorado (CO)	clean	clean
Connecticut (CT)	clean	clean
District of Columbia (DC)	clean	extended
Delaware (DE)	on request	none
Florida (FL)	clean	clean
Georgia (GA)	on request	none
Hawaii (HI)	clean	extended
Iowa (IA)	clean	extended
Idaho (ID)	clean	clean
Illinois (IL)	clean	none
Indiana (IN)	extended	none
Kansas (KS)	extended	none
Kentucky (KY)	clean	clean
Louisiana (LA)	on request	none
Massachusetts (MA)	on request	none
Maryland (MD)	on request	extended
Maine (ME)	on request	none
Michigan (MI)	extended	extended
Minnesota (MN)	clean	none
Missouri (MO)	extended	extended
Mississippi (MS)	clean	extended
Montana (MT)	extended	extended
North Carolina (NC)	extended	extended
North Dakota (ND)	clean	none
New Hampshire (NH)	clean	none
New Jersey (NJ)	clean	extended
New Mexico (NM)	clean	clean
Nevada (NV)	extended	none
New York (NY)	clean	extended
Ohio (OH)	extended	extended
Oklahoma (OK)	extended	clean
Oregon (OR)	clean	extended
Pennsylvania (PA)	clean	extended
Rhode Island (RI)	clean	clean
South Carolina (SC)	extended	clean
South Dakota (SD)	extended	none
Tennessee (TN)	extended	extended
Texas (TX)	clean	none
Utah (UT)	extended	none
Virginia (VA)	clean	extended
Vermont (VT)	clean	extended
Washington (WA)	extended	extended
Wisconsin (WI)	clean	clean
West Virginia (WV)	clean	none
Wyoming (WY)	extended	none

Don't see your target? Run the lookup anyway — lookups outside coverage are never charged, return an explicit not-covered result, and tell us where to expand next.

Why the entity → lien join matters

Anyone can look up whether a company is registered. The expensive, manual part of KYB and lending diligence is the second question — are there already liens against the company's assets? Answering it normally means finding the entity in one system, then searching a separate UCC/secured-transactions registry by hand, matching names, and hoping you found the same legal entity.

This Actor does both and connects them. It resolves the entity from the state business register, then searches that state's UCC filings by the entity's core legal name and attaches only the filings whose debtor name actually matches — precise, so a lien against a similarly-named company never gets misattributed. One call returns the entity plus its lien exposure, ready for a risk decision.

How it compares to standalone registry tools

	This Actor	Standalone entity-search tools	Single-state UCC scrapers
Entity search by name	Yes, multi-state	Usually yes	No
Normalized schema across states	Yes	Varies	N/A
UCC / lien filings	Joined to each entity	No	Yes, but not linked to an entity
One call for entity + liens	Yes	No	No
Machine-readable status + coverage notes	Yes	Rarely	Rarely

The design bet: multi-jurisdiction assembly behind one schema, plus the entity-to-lien join, is worth more to a diligence workflow than any single registry scraped in isolation.

Input

Field	Type	Required	Default	Description
companyName	string	one of these	—	The company name to search, e.g. Tesla or Acme Holdings LLC.
companyNames	array of strings	one of these	[]	Up to 20 company names to verify in one run; names are deduplicated case-insensitively before processing. Directory-style qualifiers no registry holds — formerly …, dba …, a Div. of …, a trailing c/o … or ATTN …, a trailing jurisdiction such as , a Delaware corporation, and a trailing (…) in broad modes — are removed before the search, and each record says which name was searched in message.
states	array of strings	no	all covered	Two-letter US state codes to scope the entity search. Lien joins cover a subset; the run's COVERAGE key-value record is authoritative. An unrecognized code returns one uncharged malformed_input row naming it, and the states that were spelled correctly are still searched.
includeLiens	boolean	no	true	Join UCC / lien filings where available. A state we cover for entity search but don't join liens for still returns the full entity record (with liens_checked=false, lien_coverage="no_lien_source", and a note) — you still get the entity. Set false to skip the lien join entirely.
matchMode	string	no	contains	contains (broad — find all entities sharing a name), exact (legal name equals the query), or starts (name begins with the query). In exact, punctuation and spacing are ignored, but the legal-form suffix must match — LLC, Inc and Corp are different entities; a name typed with no form at all also matches the one registered name that differs from it only by its form.
maxRecordsPerCompany	integer	no	25	Cap on entity records returned (and billed) per company name, across states. Matches past the cap are dropped (results_truncated=true), so a very low cap can miss the entity you want; scope states first to bound cost.

| reportType | string | no | standard | standard, or due_diligence for a per-company due diligence check (see below). A due_diligence run matches names exactly, takes up to 5 matched companies and defaults to 3 records per company. A record gets the check only when it is confirmed to be the business you named (see Confirming the business); any other record is the standard record at the standard price, with the reason. | | confirmations | array of objects | no | — | due_diligence only. One entry per company: companyName (as in the company list) plus any of entityNumber, address and officer, e.g. [{"companyName": "Acme Roofing", "entityNumber": "L12000012345"}]. See Confirming the business. | | securedParty | string | no | — | Keep only the lien filings that name this lender as secured party, e.g. Kubota Credit (every word, any order). Narrows each record's ucc_filings and ucc_summary; billing is unchanged. Where a state does not publish the secured party, filings are returned unfiltered, marked secured_party_filter: "not_published", with a note. Not available with due_diligence. |

In Delaware, when a capped contains search lists no matching entity for a name ending in a legal form, up to five quoted exact spellings are tried to confirm that entity. A hit is returned at the same per-record rate as an exact-mode result and is marked results_truncated, since other entities with matching names may sit past the cap; a miss remains the same uncharged "too broad" answer.

For company search (searchBy: "company", the default), provide companyName and/or companyNames — at least one is required.

Reverse search: companies by registered agent, officer or address

Start with an agent name, an officer name or a street address instead of a company name. Reverse search lists the companies that name that registered agent, the companies a person or firm is listed on as an officer, or the companies using that address in a state's business register. Use it to assemble a company's related registrations or a list of companies sharing an agent or office.

Example inputs

Registered agent: companies represented by an agent

{
  "searchBy": "registeredAgent",
  "partyName": "Example Agent Services LLC",
  "states": ["FL", "CO"],
  "maxResults": 100
}

Officer: companies a person or firm is listed on as an officer

{
  "searchBy": "officer",
  "partyName": "Jane Smith",
  "states": ["FL"],
  "matchMode": "exact",
  "maxResults": 100
}

Address: companies using a street line and ZIP code

{
  "searchBy": "address",
  "streetAddress": "7901 4th St N Ste 300",
  "streetZip": "33702",
  "states": ["FL"],
  "maxResults": 100
}

Filtered list: active companies formed or registered since a date

{
  "searchBy": "registeredAgent",
  "partyName": "Example Agent Services LLC",
  "states": ["FL"],
  "entityStatus": "active",
  "formedFrom": "2026-10-01",
  "maxResults": 100
}

For agent and officer searches, partyName is required. matchMode: "contains" (the default) matches all words in any order; "exact" matches the whole name. "starts" is not available for reverse search. Address search requires both streetAddress and the five-digit streetZip; it matches principal, mailing and registered-agent office addresses. Street-type spellings such as Street/St are folded, but a suite number must match.

Reverse-search coverage

Omit states to search all states covered for the selected mode, or name the states you want. This is a smaller coverage set than company-name search.

State	Registered agent	Officer	Address
Alaska (AK)	Yes	Yes	Yes
Colorado (CO)	Yes	No	Yes
Connecticut (CT)	Yes	Yes	Yes
District of Columbia (DC)	Yes	No	Yes
Florida (FL)	Yes	Yes	Yes
Illinois (IL)	Yes	Yes	Yes
Iowa (IA)	Yes	No	Yes
Kentucky (KY)	Yes	No	Yes
Mississippi (MS)	No	No	Yes
New York (NY)	Yes	Yes	Yes
Oregon (OR)	Yes	Yes	Yes
Pennsylvania (PA)	No	Yes	Yes
Rhode Island (RI)	Yes	No	Yes
Texas (TX)	No	No	Yes
Vermont (VT)	Yes	Yes	Yes
Virginia (VA)	Yes	Yes	Yes
West Virginia (WV)	Yes	Yes	Yes

• Texas address search matches the mailing address the state publishes.
• Illinois officer lists cover only the president and secretary slots, published for about half of its corporations and LLCs. Fewer than half of Illinois records carry a principal address; registered-agent office addresses are also searched.
• About two in three West Virginia records name a registered agent; those without one cannot appear in agent lists. About a quarter of West Virginia records carry no address with a usable ZIP code, so they cannot appear in address lists.
• Kentucky addresses are split inconsistently in the register, so some address matches may be missed.
• Iowa, New York, Oregon and Pennsylvania list active companies only; Alaska lists currently registered companies only. Rhode Island does not support the entityStatus filter.
• New York agent lists also include each company's service-of-process recipient; New York officers are the CEO of business corporations only (about one in nine records).
• Pennsylvania publishes no registered agent. Connecticut addresses are business addresses only.
• Oregon lists registered agents and principal and mailing addresses; authorized representatives are on file for assumed business names only, so an Oregon officer search lists those names free in near_matches and returns no companies.
• The District of Columbia publishes its full register with each company's standing, registered agent and business address, but no officers.
• Agent and officer names match whole words as each register spells them. Some registers space out initials — Alaska, for example, files some agent firms as "C T …" rather than "CT …" — so if a list comes back empty, retry with the register's spelling.

Filters, limits and continuing a list

entityStatus accepts any (default), active or inactive. States describe standing differently; ambiguous standings such as delinquent match neither active nor inactive. entityTypes keeps the selected types (llc, corporation, nonprofit, partnership, other); an empty array keeps all types. formedFrom and formedTo are inclusive formation/registration dates in YYYY-MM-DD form. For agent and officer lists only, city and zipFilter narrow the company's principal address, or its mailing address when there is no principal address. A filter the state's register cannot support produces an uncharged row explaining which settings to change, rather than an empty list that looks like no matches.

maxResults limits company rows across all states (default 100, maximum 10,000). maxResultsPerState is an optional per-state limit within that total, so one large state cannot consume the whole run. Each company row bills like a company-search record. companyName, companyNames, includeLiens and maxRecordsPerCompany do not control reverse lists; use reportType: "standard".

When a total cap stops a longer list, its last company row carries results_truncated: true and resume_cursor. A per-state cap marks that state's last row truncated and the run's OUTPUT supplies the continuation cursor. A maximum charge or time limit produces an uncharged stop row with a cursor. OUTPUT.resume_cursor is the run-level continuation: paste it as resumeCursor in another run with the same mode, name or address, match mode, filters and states. Within one chain of continuation runs, companies already delivered are not repeated. Raise a maximum charge that stopped the earlier run before continuing. Limits apply anew to each continuation run.

Reading the results

Company rows carry match_role (registered_agent, officer or address) and matched_name, plus matched_title for an officer and matched_address_kinds (principal, mailing, registered_agent) for an address. These fields explain why the company appears; they are absent on company-search rows.

States not covered for the selected mode return uncharged not_covered rows; temporarily unavailable states return uncharged failed rows explaining how to retry. No matches in a searched state produce an uncharged no_match row. If the register was refreshed mid-list, a row asks for a new search without resumeCursor: the delivered rows remain valid, but starting over may return them again. The list is never silently restarted. A billing error after delivery stops the list with an uncharged explanation row and a cursor after the delivered batch.

Lien filings are not joined on list rows: liens_checked is false and lien_coverage is not_requested, with a field note. To retrieve filings for a listed company, run a separate company search using its legal name and state.

UCC search by an individual debtor's name

searchBy: "individualDebtor" searches UCC filings by an individual debtor's name: one named person per run, in 1 to 5 states named in states.

{
  "searchBy": "individualDebtor",
  "debtorLastName": "Johnson",
  "debtorFirstName": "Darren",
  "debtorMiddleName": "W",
  "states": ["AR"],
  "securedParty": "Kubota Credit"
}

Field	Required	Description
debtorLastName	yes	Surname. Letters, spaces, hyphens, apostrophes and periods; at least 2 letters.
debtorFirstName	yes	First name, matched exactly (no nicknames).
debtorMiddleName	no	Middle name or initial. Keeps filings whose middle name starts with that letter, or that list none.
debtorSuffix	no	JR, SR, II, III, IV or V; must match when a filing also lists one.
securedParty	no	Keep only that lender's filings.
states	yes	1 to 5 two-letter codes.

• One row per state. completed when at least one filing names this person as debtor (match_role: "ucc_debtor", the person in matched_name, the filings in ucc_filings, entity fields null). Otherwise an uncharged no_match, not_covered or failed row says why.
• Exact match. A filing is returned only when its debtor's last and first name equal the ones searched. A filing listing only a first initial is counted in a note, never returned. When more than 5 people share the first and last name, the row asks for debtorMiddleName instead of listing them.
• Lapsed filings are included while the filing office still holds them, which is usually about a year after they lapse.
• No addresses. No address or other contact detail of an individual debtor is returned, and nothing is enriched.
• Billing. One completed row per state bills one record; nothing else is billed.

State	Individual debtor search	Lender filter
Arkansas (AR)	Yes	Yes
Florida (FL)	Yes	Yes
Hawaii (HI)	Yes	Yes
Michigan (MI)	Yes, Michigan's own name matches (debtor names not published; flagged name_unverified)	Note: secured party not published
New Mexico (NM)	Yes	Yes
District of Columbia (DC)	Not available for individuals	—
Washington (WA)	Business debtors only	—
Other states	Not yet	—

Results are public UCC filing records, for lien and collateral due diligence. They are not a consumer report: do not use them for credit, employment, tenant screening or any other purpose covered by the Fair Credit Reporting Act, or to solicit or market to the people named.

Output

One dataset record per matched entity. Example (completed, with a lien join):

{
  "query": "Tesla Electric Company",
  "input_index": 0,
  "status": "completed",
  "state": "CO",
  "legal_name": "Tesla Electric Company LLC",
  "entity_id": "20141524018",
  "entity_type": "DLLC",
  "entity_status": "Good Standing",
  "formation_date": "2014-08-27",
  "jurisdiction": "CO",
  "registered_agent_name": "Felix Keil",
  "principal_address": "9750 Hilldale Dr, Morrison, CO, 80465",
  "officers": [],
  "liens_checked": true,
  "lien_coverage": "joined",
  "ucc_filings": [
    {
      "filing_number": "20192017103",
      "filing_type": "UCC financing statement",
      "status": "active",
      "filed_date": "2019-03-01",
      "lapse_date": "2024-03-01",
      "secured_party": "US BANK NA",
      "collateral": "All equipment now owned or hereafter acquired",
      "debtor_name": "TESLA ELECTRIC COMPANY LLC"
    }
  ],
  "ucc_summary": { "total": 6, "active": 6, "filings_truncated": false },
  "results_truncated": false,
  "source": "Colorado Secretary of State (Business Entities)",
  "source_url": "https://www.coloradosos.gov/biz/BusinessEntityCriteriaExt.do",
  "fetched_at": "2026-07-09T14:03:11Z",
  "field_notes": []
}

Key fields: status (resolution outcome), error_class (machine-routable failure class on non-completed rows — see the failure taxonomy below), retry (what to do about that class: later, with_changes, or never; null on completed rows), entity_status (registration standing, verbatim from the state), liens_checked (whether a covered lien source was queried), lien_coverage (joined, no_lien_source, unavailable, or not_requested), ucc_filings (the join), ucc_summary ({total, active, filings_truncated}), results_truncated (whether the entity cap dropped matches), and field_notes (why any field is structurally absent). Entity coverage is broader than lien-join coverage: an uncovered-for-liens state still returns the entity with liens_checked=false and a coverage note. A run also writes a COVERAGE key-value record listing the authoritative live entity-search and lien-join state sets. A possible_individual field note marks filings whose debtor name reads as an individual with the same name as the company: a standard search keeps them, and a due_diligence check leaves them out.

Due diligence check

Set reportType to "due_diligence" to get, for each resolved company:

• Current registry status. The state's status is read at run time (or from the state's own published register when it was refreshed within the last 24 hours), with status_as_of, status_source_type, and a normalized standing (active, not_in_good_standing, inactive, or unknown — the registry's own wording stays in entity_status, and wording we have not mapped is unknown, never guessed). Illinois publishes its register as a daily file; its status counts as current for 48 hours from the start of the file's date.
• Recent financing. From the UCC join: original financing statements filed in the last 12 months and how many distinct secured parties filed them (ucc_stacking). Where a state does not publish a field needed to count, the count is null with the reason — never a zero. financing_positions gives both windows; filings by a secured party listed "as representative" count in filing_agent_filings.
• Time in business. Whole months from formation to the run date (time_in_business); for a company formed in another state, from its registration here (date_basis).
• Sanctions-list screen. The legal name and the entity entries of the U.S. Treasury SDN and consolidated non-SDN lists, each as of its own publication date (sanctions_screen). Similar names come back as potential matches with a score for you to review; an empty result means no potential matches against the lists of those dates.
• Recorded liens (lien_bundle). The county recorder for the company's principal-office ZIP code, searched for the company's legal name; a filing is listed only when the lien is against the company. Also California tax liens from the state's UCC index and Florida federal liens from the state's federal lien registry. Each source says whether it was searched, not covered, or unavailable on the run; lien types whose debtor side a recorder's records do not establish are counted, not listed. Creditors are named as filed. A filing whose debtor reads as an individual with the company's name is left out (see possible_individual). Maryland companies: money judgments against the company from the court judgment index (circuit courts), matched by exact name on the debtor side, with status, amount and expiration. Expired judgments and criminal cases are left out. Judgments that began in District Court cannot be told apart. State tax liens are identified by creditor, and how many appear varies by county.
• A link to the source record where the registry publishes one.

A record becomes a due diligence check (due_diligence.available: true) when it is confirmed to be the business you named, its status was confirmed current at run time, and it was screened. Otherwise you get the standard record at the standard rate, with the reason in due_diligence.reason and a code in due_diligence.reason_code. When a state's status cannot be confirmed current at run time, the code is status_not_current; when the screen did not run, not_screened. Lien coverage never decides the charge.

Confirming the business

Business names can be shared, so a name alone does not show which registered business you mean. A record gets the check only when one of these holds:

• You confirmed it. Add an entry to confirmations for the company, and one of its details agrees with the record: entityNumber (the state's entity or file number; case, spaces and punctuation are ignored), address (street number and street name, then a city or ZIP, comma-separated, e.g. "1417 Quarry Ln, Norfolk, VA 23502"; it agrees with an address on the record when every part both give matches: street number, the whole street name (St and Street are the same), unit, city, state and ZIP), or officer (an officer's or the registered agent's full name; every name you give must be on the record, and a middle initial matches a full middle name).
• You typed its full legal name. With no confirmation, the name you typed includes its legal form (LLC, Inc., ...), equals the registered legal name, and no other entity in that state has that name.

Any other record is the standard record at the standard price. Its due_diligence.reason says why the check was not run and how to get it, and due_diligence.reason_code is one of:

• identity_unconfirmed: the name was typed without a legal form, the registered name has none, or it was matched through a rewrite of the name you typed. Add the company's entity number, address or an officer's name and run again.
• identity_ambiguous: several registered businesses in the state match the name (each comes back, up to the per-company record cap), or your confirmation fits more than one. Add a detail that picks out the one you mean.
• confirmation_mismatch: a detail you gave does not match this record, so it may be a different business with the same name. A detail that disagrees outweighs one that agrees.
• confirmation_uncheckable: the state's register does not publish the address or officers needed to check the detail you gave. Give the entity number instead.
• billed_as_standard: the same business was already returned in the run for another name that nothing confirmed, and billed as the standard record; run this name alone to get the check.

due_diligence.matched_on says what the record's identity rests on: confirmed_entity_number, confirmed_address, confirmed_officer, legal_name_exact, bare_name (typed without a legal form), name_without_legal_form (the registered name has none), name_variant (a rewrite of the name you typed), or ambiguous. With maxRecordsPerCompany: 1 a twin cannot be ruled out, so a typed legal name alone does not get the check; a confirmation still does.

What a due diligence check is not

• Not a certificate of good standing. Order that from the state.
• Not an identity or TIN check. It does not confirm who controls the company or match a tax ID.
• Not a consumer report. It covers business entities only and must not be used for decisions about individuals governed by the Fair Credit Reporting Act.
• Not a complete lien search. One county recorder and the listed state sources are searched; liens recorded elsewhere are not covered.
• Not a sanctions determination. Potential matches are leads to review, and no result means only no potential matches against the lists of the stated dates.

Batch API Quickstart

The synchronous endpoint returns dataset items directly. These examples submit the same three-company batch and branch on both the entity outcome and the independent lien outcome.

states in these examples is illustrative: set it to the states where the companies are registered, or omit it to search every default-covered state.

curl -X POST "https://api.apify.com/v2/acts/shelvick~business-entity-lien-search/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"companyNames":["Acme Holdings LLC","Northstar Freight LLC","Riverbend Manufacturing LLC"],"states":["CO","CT"],"includeLiens":true}'

import requests

items = requests.post(
    "https://api.apify.com/v2/acts/shelvick~business-entity-lien-search/run-sync-get-dataset-items",
    params={"token": APIFY_TOKEN},
    json={
        "companyNames": ["Acme Holdings LLC", "Northstar Freight LLC", "Riverbend Manufacturing LLC"],
        "states": ["CO", "CT"],
        "includeLiens": True,
    },
    timeout=900,
).json()
for row in items:
    if row["status"] != "completed":
        print(row["query"], row["status"])
    elif row["lien_coverage"] == "joined":
        print(row["query"], row["ucc_summary"])
    else:
        print(row["query"], "entity delivered; lien outcome:", row["lien_coverage"])

const url = new URL("https://api.apify.com/v2/acts/shelvick~business-entity-lien-search/run-sync-get-dataset-items");
url.searchParams.set("token", process.env.APIFY_TOKEN);
const items = await fetch(url, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    companyNames: ["Acme Holdings LLC", "Northstar Freight LLC", "Riverbend Manufacturing LLC"],
    states: ["CO", "CT"],
    includeLiens: true,
  }),
}).then((response) => response.json());
for (const row of items) {
  if (row.status !== "completed") console.log(row.query, row.status);
  else if (row.lien_coverage === "joined") console.log(row.query, row.ucc_summary);
  else console.log(row.query, "entity delivered; lien outcome:", row.lien_coverage);
}

Result and correlation contract

Names from companyName and companyNames are trimmed, deduplicated case-insensitively, and processed in first-seen order. input_index is the zero-based position in that accepted order. One name may produce several entity rows, so group records by query or input_index; results_truncated=true means maxRecordsPerCompany excluded additional entity matches.

When multiple names resolve to the same state and entity ID within a run, each name still receives a completed answer. same_record_as is set to the earlier query string whose registry record was already returned and charged; this repeated answer has no additional charge, including extended records and due-diligence checks. It does not consume the run's remaining charge budget. Otherwise the field is null. Entity IDs are compared after trimming surrounding whitespace and uppercasing only; punctuation and leading zeros remain significant. Records without an entity ID are not deduplicated. This applies within one run, not across retries.

Retries are at-least-once. Consumers should deduplicate completed records by query + state + entity_id, and terminal misses by query + state + status.

Entity and lien coverage

Entity-search coverage and lien-join coverage are separate capabilities. A completed entity remains useful when its lien outcome is no_lien_source, unavailable, or not_requested; inspect lien_coverage on every completed row rather than inferring coverage from the entity state. The run's COVERAGE artifact is authoritative.

Records come straight from official state registry and UCC systems, as-is. Registries can lag recent filings and occasionally contain clerk-side errors — for anything with legal weight, verify against the official record at the source.

Clean lien joins cover AK, AL, AR, CO, CT, FL, ID, KY, MS, NM, OK, RI, SC, and WI. Oklahoma's and South Carolina's entity searches are explicit-request, so their clean-tier joins are delivered only when the state is named. Extended joins cover CA, DC, HI, IA, MD, MI, MT, NC, NJ, NY, OH, OR, PA, TN, VA, VT, and WA only when the state is explicitly requested with liens enabled. Hawaii's, the District of Columbia's and Oregon's joins bill the standard per-record rate. New York's join bills the standard rate when it finds no filings and the extended rate when it delivers filings. Extended entity searches cover AZ, CA, IN, KS, MI, MO, MT, NC, NV, OH, OK, SC, SD, TN, UT, WA, and WY only when explicitly requested; AZ, GA, IN, MO, LA, NV, MA, SD, UT, DE and WY currently have entity coverage but no lien join. VA entity searches bill the standard per-record rate unless a lien join is delivered. NH and MT are also searched by default, at the standard per-record rate, from copies of each state's business search results; naming either searches the state's live register instead (a named MT search answered live bills extended). When the live register cannot be reached, a named NH, MT or VA search is answered from that copy instead: at the standard rate, dated by source_as_of, with a message saying the live register was unreachable. A name the copy does not hold stays a failed row: the copy is not proof that no such entity exists. GA, DE, LA, MA and MD are searched only when named as well, but they bill the standard per-record rate (MD unless a lien join is delivered): they need a browser, not a metered connection, and you are not charged for a cost the lookup does not incur. WY is searched only when named in states and bills the extended per-record rate. IN returns the entity under its current legal name, including foreign legal names. A search that matches an entity's assumed business name or former name returns that entity under its legal name, with a field_notes entry naming the name that matched; name reservations are excluded. Indiana has no lien join. It is searched only when named in states and bills the extended per-record rate. SC is searched only when named in states and bills the extended per-record rate. SD returns current registry rows with the state's own status. South Dakota has no lien join. It is searched only when named in states and bills the extended per-record rate. KS returns the Secretary of State's business entity record with its filing history; Kansas publishes no officers and has no lien join. It is searched only when named in states and bills the extended per-record rate. Kansas records may not be used to market to the people or businesses listed (K.S.A. 45-230).

Coverage by state name

Searched by default at the standard rate: Alabama, Alaska, Arkansas, Colorado, Connecticut, District of Columbia, Florida (the Division of Corporations' Sunbiz register, inactive and dissolved entities included), Hawaii, Idaho, Iowa (active entities only), Illinois, Kentucky, Minnesota, Mississippi, New Jersey, New Mexico, New York (Department of State active corporations), North Dakota, Oregon, Pennsylvania, Rhode Island, Texas (the Comptroller's franchise-tax register), Vermont (inactive and dissolved entities included), West Virginia, and Wisconsin. A Florida business search, a New York business entity search, a Colorado business entity search, or a Texas business entity search is the same call scoped with states.

Searched only when named in states: Arizona, California, Delaware, Georgia, Indiana, Kansas, Louisiana, Maine, Maryland, Massachusetts, Michigan, Missouri, Nevada, North Carolina, Ohio, Oklahoma, South Carolina, South Dakota, Tennessee, Utah, Washington, and Wyoming. Virginia is searched by default from the State Corporation Commission's weekly business-entity file, including registered agents and corporate officers, and supports reverse search by agent, officer and address. New Hampshire and Montana are searched by default from copies of each state's business search results; naming them searches the live register. A California SOS business search bills the extended rate; a Virginia SOS business search bills the standard rate unless a lien join is delivered; the coverage table above says which fields each state withholds.

Not covered: Nebraska. A lookup scoped to Nebraska returns an explicit not-covered result and is never charged.

Calling from an AI agent

Tell us what's missing. If a run doesn't give you what you need, add a feedback note to your next run: what was missing or wrong, or which tool you're switching to and why. A run with only a note isn't charged for results, and the maintainers read every note.

Agents are the primary customer. Three ways to call it:

• Apify MCP server (mcp.apify.com): expose shelvick/business-entity-lien-search as a tool; the input schema and per-field descriptions are advertised to the model.

• Apify Python SDK:

  from apify_client import ApifyClient
  
  client = ApifyClient("<APIFY_TOKEN>")
  run = client.actor("shelvick/business-entity-lien-search").call(
      run_input={"companyName": "Acme Holdings", "includeLiens": True}
  )
  for record in client.dataset(run["defaultDatasetId"]).iterate_items():
      print(record["legal_name"], record["entity_status"], record["ucc_summary"])
  

• REST: POST /v2/acts/shelvick~business-entity-lien-search/run-sync-get-dataset-items for a synchronous call, or the async /runs endpoint plus polling for large batches.

Agent decision guide

• completed + joined + ucc_summary.total == 0: the covered source was searched and returned zero matching filings; check filings_truncated before treating the count as exhaustive.
• no_lien_source: the entity was delivered, but this state has no integrated lien source.
• unavailable: the entity was delivered, but the lien search failed at request time; retry later.
• not_requested: the entity was delivered without a lien search: includeLiens=false, a list row, or a state whose lien search runs only when named in states (the field note says which).
• no_match: covered entity sources were searched but no entity matched; this says nothing about liens.
• failed: the stated search did not complete; never interpret it as no entity or no liens.

Never collapse these outcomes into a single "no liens" result.

Failure taxonomy: when to retry

Every non-completed record carries error_class, a stable machine-routable value. Branch on it rather than on the prose in error, which may be reworded at any time.

Retry the same request later, unchanged:

• source_error — the official registry could not be reached. Registries have scheduled maintenance and unplanned outages, sometimes lasting a day; this is the source being unavailable, not a problem with the query.
• source_walled — the registry refused an automated search. Usually temporary.
• budget_exhausted — the run deadline arrived before this company finished, or the run reached its Max cost per run before this company (or some of its records) could be delivered. For the cost case, raise Max cost per run first.
• lien_join_error — the entity was found, but its lien filings could not be retrieved; the entity fields on other rows for this company are still good.

Do not retry unchanged; the answer will not differ:

• no_match — the registry answered and no entity matched the name.
• not_covered — the requested state is not yet supported.
• internal_error — the search could not be completed.

error_class is null on completed records. Each row also carries retry, the same advice as a single value (later / with_changes / never, null on a result), so an agent can route without holding this table.

Retry only what failed. A failed row is free, but re-running the whole company re-searches — and re-bills — every state that succeeded. Each failed row's message names the one-state retry (states: ["MN"]), and the run's key-value store OUTPUT carries failed_states (state → companies) plus retry_input, a ready-to-submit input that fetches only the missing states. The run status message summarizes the same.

Single lookups over HTTP

You can also call this Actor over HTTP as a REST API: one company in one state per request, with no run to start or dataset to fetch. Send a JSON body to POST /search_company on https://shelvick--business-entity-lien-search.apify.actor:

• companyName and state (two-letter code) are required;
• optional: includeLiens (default true), matchMode (default contains), maxRecords (default 10, maximum 25), reportType (standard or due_diligence; default standard), confirm (due_diligence only: any of entityNumber, address, officer, as in Confirming the business).

curl -X POST "https://shelvick--business-entity-lien-search.apify.actor/search_company" \
  -H "Authorization: Bearer <APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"companyName": "Tesla", "state": "CO"}'

Each response is {"status": "ok", "records": [...]} in the same record shape as the batch dataset. Records are billed exactly as in batch runs, and no_match, not_covered and failed results are free. Branch on each record's status as in the batch examples.

Lookups that can't finish in about a minute and a half come back as {"status": "use_normal_run", "runInput": {...}}, free of charge. The runInput is the same search as a ready batch input. Searches in North Carolina and Ohio, whose registries can't reliably answer that fast, always take this route. Several companies, several states and reverse search run as normal batch runs. A due_diligence lookup here returns the registry status, sanctions screen, financing summaries and time in business of the due diligence check; county recorder liens, Florida federal liens and Maryland court judgments are searched only in a normal run.

Pricing and billing outcomes

Billing occurs only when a completed entity record has first been delivered to the dataset. no_match, not_covered, and failed rows are never billed. A completed entity remains billable when a lien join was not requested, is not covered, or was temporarily unavailable; the entity result itself was still delivered.

A run stops delivering at its Max cost per run. A completed record is delivered only if it can be charged; once the limit is reached, the rest come back as uncharged failed rows with error_class: "budget_exhausted" (one per company and state, or one per company not yet searched), OUTPUT.budget_clamped counts the records withheld, and OUTPUT.retry_input is a ready-to-submit input naming the companies and states that were withheld. Raise Max cost per run before re-running it. Where a company and state had some records delivered before the limit, that re-run returns (and charges for) those records again. The Store Pricing tab is the authoritative source for current rates and discounts.

A due_diligence run bills one due diligence check per record that earned it, and that record bills nothing else. Companies the run's maximum charge cannot cover are not searched; each gets an uncharged row saying so.

Batch size, latency, and partial runs

A run accepts at most 20 unique company names and processes up to four companies concurrently. Clean-path lookups generally finish in seconds to under a minute; explicit extended coverage may need a longer startup and can take several minutes. Split larger batches across runs.

Completed records are pushed and charged as each company finishes. If the internal run deadline arrives, completed work remains available, each unfinished company gets an uncharged failed row with error="run_deadline_exceeded", and OUTPUT.partial=true with OUTPUT.pending_companies showing the count.

Schedules and retries

For recurring batch execution, use scheduled asynchronous runs and consume each run's dataset after completion. Retry whole or partial inputs using the correlation keys above. Searches are point-in-time lookups, not monitoring or change alerts.

High-volume needs

Running a large KYB pipeline or planning sustained batch volume? Open a conversation on the Actor's Issues tab with your target states and workload shape. Volume feedback directly drives state-coverage priorities.

Behavior

• Statuses: completed (entity found + normalized), no_match (covered states searched, nothing matched — a clear "not found"), not_covered (a requested state isn't supported yet), failed (a covered state's registry could not be reached; see error). Only completed is billed.
• acknowledged: the run (or request) carried only a note; nothing was searched and no results were charged.
• Graceful degradation: if one state's registry is briefly unavailable, that state yields a failed record while the rest of the run completes — a source hiccup never fails the whole batch or charges you for it.
• Source freshness: lien data is only as current as each state's published index. Florida lien data is indexed from the state's official public UCC data files on a periodic refresh cycle, so a very recently filed Florida lien may not appear until the next refresh; those files publish filing images rather than collateral text. Kentucky's UCC index in particular publishes on roughly a two-week lag, so a very recently filed Kentucky lien may not appear yet. Iowa's and Rhode Island's lien searches cover active filings plus those lapsed within roughly the past year — older lapsed history is not published, so lien totals there describe the current picture rather than all history. Rhode Island publishes no per-filing lapse date; each filing's status is derived from the state's own active/lapsed indexes and its filing history instead.
• South Carolina liens: the free UCC grid publishes filing number, type, filed date and lapse date only; status, secured_party and collateral are not exposed and arrive as null.
• Missouri liens: the state's UCC index lists filing number, debtor, filed date, status and lapse date, but not the secured party. For up to 10 active filings per company (newest first) the secured party is read from the filing image itself and marked secured_party_source: "filing_image" with a secured_party_confidence (0-1); a read that is not confident enough arrives as null with a field_notes entry. Only the secured party is taken from the image; collateral is not published.
• Current-only sources: a few states publish only their currently registered entities — dissolved and withdrawn ones are absent from the source. For those, a no_match means no currently registered entity matched the name, not that it never existed; the record carries a field_notes entry saying so. Iowa reports every returned entity as active (its bulk file has no status column); Alaska keeps each entity's real standing (e.g. Good Standing, Non-Compliant) but still omits dissolved entities. Florida is the opposite: its register includes inactive and dissolved entities with their real status, so an FL record can come back Inactive — useful when you need to know a counterparty was dissolved rather than never registered. Mississippi also includes the full register and preserves state standing values such as Good and Dissolved, but its source does not publish registered-agent or officer data. Rhode Island Department of State — Corporate Database and West Virginia Secretary of State — Business Organization Search also cover the full register, including inactive and dissolved entities. Rhode Island searches match an entity's current legal name, so find a renamed company under its current name or check the state portal at https://business.sos.ri.gov/CorpWeb/CorpSearch/CorpSearch.aspx .
• Kentucky assumed and former names: Kentucky Secretary of State (Business Entity Search) records cover the full register, including inactive entities. A search that matches an entity's assumed name (DBA) or former name returns the entity under its legal name, with a field_notes entry naming the name that matched.
• Rhode Island status: entity_status can be null when the Rhode Island Department of State — Corporate Database does not return a current standing for the entity; the record carries a field_notes entry saying so, and you can verify the entity directly at https://business.sos.ri.gov/CorpWeb/CorpSearch/CorpSearch.aspx .
• Telemetry: to improve coverage and reliability, this Actor reports anonymous usage metrics and diagnostic events to the developer — run outcome counts, the states queried, and, only when something goes wrong, the relevant input fields. No account identifiers are collected, and telemetry never affects a run.

FAQ

• Which states are covered? Entity search covers 49 states plus DC: AK, AL, AR, CO, CT, DC, FL, HI, IA, ID, IL, KY, ME, MN, MS, MT, ND, NH, NJ, NM, NY, OR, PA, RI, TX, VT, WI, and WV by default, plus AZ, CA, DE, GA, IN, KS, LA, MA, MD, MI, MO, NC, NV, OH, OK, SC, SD, TN, UT, WA, and WY when named in states. Virginia is searched by default from the State Corporation Commission's weekly business-entity file, including registered agents and corporate officers, and supports reverse search by agent, officer and address. Clean lien joins cover AK, AL, AR, CO, CT, FL, ID, KY, MS, NM, OK, RI, SC, and WI; Oklahoma's and South Carolina's entity searches are explicit-request, so their joins are delivered only when the state is named. Extended joins cover CA, DC, HI, IA, MD, MI, MT, NC, NJ, NY, OH, OR, PA, TN, VA, VT, and WA only when explicitly requested; Hawaii's, the District of Columbia's and Oregon's joins bill the standard per-record rate. New York's join bills the standard rate when it finds no filings and the extended rate when it delivers filings. Entities from other covered states return without a lien join, clearly flagged with lien_coverage="no_lien_source". The run's COVERAGE record is the authoritative live list as coverage expands.
• Why do AZ, CA, IN, KS, MI, MT, NC, NV, OH, OK, SC, SD, TN, UT, WA, and WY bill extended when I name them? They are extended-coverage states billed at the extended per-record rate (see the Pricing tab). Keeping them out of the search-everywhere default means you are never charged the extended rate for a state you didn't ask about — naming them in states is the opt-in. Montana is also searched by default, at the standard rate, from a copy of its business search results; only a named Montana search answered live bills extended.
• Why didn't my Massachusetts search find a company I know is registered? Massachusetts matches from the start of the name, so a search for a word in the middle of a company's name will not find it — search the beginning of the legal name instead. Records and empty results from MA both say so.
• Can I use this for a registered agent lookup? Yes — every completed record carries registered_agent_name (and the agent's address where the state publishes it), so a registered agent lookup by company name is a single call.
• Can I look up a company's officers and directors? Where the state publishes them, yes — officers carries the roster (name and title) on the same record, so a corporate officers search costs nothing beyond the entity record. States that don't publish officers say so explicitly in field_notes.
• What if a company has no liens? For a lien-covered state, liens_checked is true, lien_coverage is joined, and ucc_summary.total is 0 with filings_truncated=false — a confident "no liens found," not a gap. If the state lacks a lien join, liens_checked is false, lien_coverage is no_lien_source, and the entity record includes a coverage note instead.
• How precise is the entity→lien match? Filings are attached only when the UCC debtor's core legal name matches the entity's, so a lien against a similarly-named company is not misattributed. Descriptive words (Company, Trust) are kept; only legal-form suffixes (LLC, Inc.) are normalized away for matching.
• Can I verify a list of companies at once? Yes — pass up to 20 names in companyNames; each is resolved independently.
• Is this official / real-time? Data comes from the official state registries — Secretary of State / corporations-division records and state open-data portals; it is as current as those sources publish.

What this doesn't do

• No paywalled or login-gated sources. It uses only free, public registry data; it does not cross any state's paid detail lookup.
• No consumer / personal-PII lookups. Business-entity public records, plus UCC filings searched by an individual debtor's name — not people search, not skip tracing, and no addresses or contact details of individuals.
• No document images or filed PDFs — structured fields, not scanned filings.
• Not every state yet. Uncovered states return not_covered; it is not a 50-state guarantee.
• Not a monitoring service — it answers a point-in-time query, it does not watch an entity for changes.

Use a dedicated people-search or identity-verification tool for individuals, a document-retrieval service for filed images/PDFs, and a court-records or enforcement tool for litigation history — this Actor is for the business-entity record and its UCC lien exposure.

Data is sourced from public government registries and open-data portals and is provided for lawful business, compliance, and diligence use; verify against the official source of record before relying on it for a regulatory decision, and use it in accordance with the Apify Terms of Service and applicable law.

Related Actors

Actor	Use it when
Business Entity List Export: LLCs & Corporations by State	you need a filtered list rather than named companies: every active LLC in a state, companies formed between two dates, or every company in a city or ZIP, exported in bulk
Enforcement Record Profiler	you've verified the entity and want its enforcement and violation history from official US sources
County Property Records API	the entity owns US real estate and you need owner, assessed value, and tax records
Property Deed & Lien Records Search	you need what the entity recorded at county recorder offices — deeds, mortgages, and real-estate liens by company name
Company Registry Search — Companies House, SIRENE +9 (KYB)	the company is registered outside the US and you need its entry in the UK, French, Nordic, Baltic, Swiss, Czech, Polish, Australian or Singapore official register — same normalized record shape, no API key
Property Owner Portfolio — Property Records by Owner Name	you need the owner's public-record real-estate footprint — parcel counts and assessed totals by county — rather than registration and UCC lien detail.