Entities and candidates

Every entity resolution response carries both an entity and a candidate key. Exactly one of them is populated, or neither if nothing matched.

Entities

A record in the SavvyIQ graph, anchored to a government registration. It has an id (siq_…) that stays stable and works across every API: pass it to /v3/entities/{id} for the full record, or to Entity Hierarchy for ownership.

Candidates

The best hypothesis we could form for a query that did not resolve to a record.

A candidate carries descriptive fields like name, legal_name, jurisdiction, status, description and primary_address, but no id. It cannot be enriched, referenced later, or passed to another endpoint, and resolving the same query again may return a different one.

You get a candidate when the match is too weak to commit to a record, or when the entity type is one we do not create records for. factors[] tells you which. Look for a limitation entry.

Which one you get

status	Meaning	Populated
matched	Confidence 80 or above	entity
partial_match	Resolved to a known business, confidence below 80	entity
inconclusive	Too weak to commit, or a type we do not record	candidate, if we formed one
no_match	Research finished and found nothing	neither
not_found	Research did not complete	neither

Branch on which key is non-null, not on match_confidence. A partial_match returns a full entity below 80.

no_match and not_found are not the same outcome. no_match is an answer: we researched the query and there was nothing to return. not_found means the research itself did not finish, so the query is worth retrying. On not_found, type and subtype are null as well, so guard for that before reading them.

Type and subtype

type and subtype sit at the top level of the response, beside entity and candidate. They are not inside the entity object.

{
  "status": "matched",
  "match_confidence": 100,
  "type": "business",
  "subtype": "incorporated_entity",
  "entity": { "id": "siq_33d67jj0wJESjEdFHMhuQ", "display_name": "Datadog", "legal_name": "DATADOG, INC." },
  "candidate": null
}

On GET /v3/entities/{id} the same two fields live inside the record instead.

type
business	Commercial entities
nonprofit	Nonprofit organizations
government	Agencies and departments at national, state and local level. Not international organizations
person	An individual, including sole proprietors
other	Trusts, funds, international organizations, other specialized structures
unknown	Could not determine

subtype
incorporated_entity	A separate legal entity such as a corporation or LLC
unincorporated_entity	Partnerships, sole proprietorships
nonprofit_entity	A nonprofit organization
government_entity	Government agencies and departments
natural_person	An individual, not a business entity
complex_business_structure	SPVs, joint ventures, professional corporations, mixed legal characteristics
trading_name_only	A DBA or trade name with no associated legal entity
other_entity	International organizations, trusts, funds
unknown	Could not determine

Coverage

Entity records today are almost entirely incorporated businesses: corporations, LLCs, and their equivalents in other jurisdictions. That focus is deliberate. It is the population we can resolve with the most confidence, so it is where we built coverage first.

The other organization types are still researched and classified, and you will see them in type and subtype. Most of them come back as candidates rather than records, and government entities always do, carrying unsupported_entity_type in factors[]. Broader type coverage is close behind.