Entity resolution
Deep research for entity by name (streaming)
GET
/v2/entity-resolution/stream AI-powered deep research (3-5 minutes) that finds and consolidates entities through intelligent web search. Holds the connection open until the research is complete.
Try Instant Search first for faster results (<1 second).
Note on Response Format:
- For high-confidence matches of supported entity types (currently only businesses that are incorporated entities),
the response will contain an
entityfield with the schema of that entity type. - For lower-confidence matches or entity types not fully supported yet, the response will contain
a
candidatefield with best-guess information. - The response will never have both
entityandcandidatefields populated simultaneously. - We will continue to expand the set of entity types we support.
Query parameters
namestring requiredEntity namelocationstringEntity location
Responses
200 OK
request_idstringThe request ID for this API callstatusstring (enum)matchedpartial_matchinconclusiveno_matchStatus of the resolution:
matched- High confidence match found (entity field will be populated)partial_match- Lower confidence match (candidate field will be populated)inconclusive- Multiple possible matches (candidate field may be populated with best guess)no_match- No matches found
typestring (enum)businessnonprofitgovernmentpersonotherunknownThe entity type. Currently the system only fully supports "business" types. Other types may be identified but will be returned as candidates only.subtypestring (enum)Show 9 possible valuesHide possible values
incorporated_entityunincorporated_entitynonprofit_entitygovernment_entitynatural_personcomplex_business_structuretrading_name_onlyother_entityunknownThe entity subtype. Currently the system only fully supports "incorporated_entity" subtypes. Other subtypes (like "unincorporated_entity", "government", "fund") will be returned as candidates only.confidenceintegerThe confidence score of the match (0-100). Higher scores generally correspond to entity records, while lower scores correspond to candidates.entityobjectThe matched entity details. This field is populated only for high-confidence matches of supported entity types. Will be null when the candidate field is populated. Currently only entities of type "business" and subtype "incorporated_entity" will have this field populated.Show 8 nested fieldsHide nested fields
idstringnamestringstatusstring (enum)activeinactivewebsitestringdescriptionstringheadquartersobjectShow 6 nested fieldsHide nested fields
citystringstatestringaddressstringcountrystringstate_codestringcountry_codestring
matching_branchobjectShow 5 nested fieldsHide nested fields
notesstringaddressstringstate_codestringcountry_codestringjurisdictionstring
primary_legal_entityobjectShow 5 nested fieldsHide nested fields
idstringnamestringstate_codestringcountry_codestringjurisdictionstring
candidateobjectBest matching candidate when no high-confidence match exists, or when the entity type is not fully supported yet. This field is populated when the entity field is null. This happens when:
- The confidence is too low to create a definitive record
- The entity type or subtype is not fully supported yet (e.g., unincorporated entities, governments, funds)
Show 6 nested fieldsHide nested fields
namestringlegal_namestringjurisdictionstringstatusstring (enum)activeinactivedescriptionstringprimary_addressobjectShow 3 nested fieldsHide nested fields
full_addressstringstate_codestringcountry_codestring
factorsarray<object>Factors contributing to the match decisionShow 4 nested fieldsHide nested fields
codestringtypestring (enum)strengthlimitationimpactstringdescriptionstring
actionsarray<object>Suggested actions for the userShow 2 nested fieldsHide nested fields
codestringdescriptionstring
metadataobjectAdditional information about the requestShow 5 nested fieldsHide nested fields
queryobjectShow 5 nested fieldsHide nested fields
modestringnamestringcontextstringlocationstringclassificationstring
from_cachebooleanupdated_atstring <date-time>resolved_atstring <date-time>cache_hit_typestring
400 Bad Request
errorobjectAn error object.Show 2 nested fieldsHide nested fields
messagestringThe error messagetypestringThe error code
401 Unauthorized
messagestringThe error object.request_idstringThe request ID for the error.
500 Internal Server Error
errorobjectAn error object.Show 2 nested fieldsHide nested fields
messagestringThe error messagetypestringThe error code
502 Request timeout
errorobjectAn error object.Show 2 nested fieldsHide nested fields
messagestringThe error messagetypestringThe error code
Example request
cURL
curl --request GET \
--url 'https://api.savvyiq.ai/v2/entity-resolution/stream?name=Apple%20Inc.&location=California%2C%20US' \
--header 'apikey: YOUR_API_KEY' Example response
High confidence match with entity record200
{
"request_id": "reqs_2ZUKocPbFCPLClZ5XtHlJ",
"status": "matched",
"confidence": 98,
"type": "business",
"subtype": "incorporated_entity",
"entity": {
"id": "siq_2ZUKocPbFCPLClZ5XtHlJ",
"name": "Apple",
"status": "active",
"website": "apple.com",
"description": "Designs, develops, and sells consumer electronics, computer software, and online services.",
"headquarters": {
"city": "Cupertino",
"state": "California",
"address": "ONE APPLE PARK WAY",
"country": "United States",
"state_code": "CA",
"country_code": "US"
},
"primary_legal_entity": {
"id": "le_2ZoRp6I3EUgebkUBHaDdk",
"name": "APPLE INC.",
"state_code": null,
"country_code": "US",
"jurisdiction": "California"
},
"matching_branch": {
"notes": "Headquarters is located in California",
"address": "ONE APPLE PARK WAY, CUPERTINO, CA, 95014, United States",
"state_code": "CA",
"country_code": "US",
"jurisdiction": "California"
}
},
"candidate": null,
"factors": [
{
"code": "name_close_match",
"type": "strength",
"impact": "High confidence that this is the correct entity due to brand recognition.",
"description": "The provided name 'Apple Inc.' closely matches the legal entity name 'Apple'. While not an exact match, the common usage of 'Apple' for 'Apple Inc.' makes this a strong indicator."
},
{
"code": "jurisdiction_match",
"type": "strength",
"impact": "Confirms this is the primary legal entity location.",
"description": "The provided location 'California, US' matches the entity's registered jurisdiction."
},
{
"code": "multiple_sources_corroboration",
"type": "strength",
"impact": "Very high confidence due to broad confirmation across sources.",
"description": "Multiple authoritative sources confirm this entity's details, increasing the confidence in the match."
},
{
"code": "legal_entity_confirmed",
"type": "strength",
"impact": "This ensures that the result is a properly registered business",
"description": "A valid legal entity was confirmed through official sources"
}
],
"actions": [],
"metadata": {
"query": {
"mode": "standard",
"name": "Apple Inc.",
"context": null,
"location": "California, US",
"classification": "specific"
},
"from_cache": false,
"updated_at": "2025-05-14T22:02:02.819Z",
"resolved_at": "2025-05-14T22:02:05.343Z",
"cache_hit_type": null
}
}Low confidence match with candidate
{
"request_id": "reqs_2ZVVNRjoqEh1cLBTGD86z",
"status": "inconclusive",
"confidence": 20,
"type": "business",
"subtype": "trading_name_only",
"entity": null,
"candidate": {
"name": "Umbrella Corporation",
"legal_name": null,
"jurisdiction": "US-IN",
"status": null,
"description": "Unknown business.",
"primary_address": {
"full_address": "2818 Lincoln East, Mishawaka, IN, 46544, United States",
"state_code": "IN",
"country_code": "US"
}
},
"factors": [
{
"type": "limitation",
"code": "location_mismatch",
"description": "The provided address does not match the registered address of the confirmed legal entity.",
"impact": "Reduces confidence in the accuracy of the search results.",
"severity": "medium"
},
{
"type": "limitation",
"code": "name_too_generic",
"description": "The name 'Umbrella Corporation' is relatively common, potentially leading to multiple possible matches.",
"impact": "Makes it difficult to pinpoint the exact entity without additional information.",
"severity": "medium"
}
],
"actions": [
{
"code": "verify_address",
"description": "Double-check the provided address for accuracy, including street number, street name, city, and ZIP code. Ensure it matches the entity's official registered address."
},
{
"code": "add_industry_context",
"description": "Include industry information in the search query (e.g., 'Umbrella Corporation pharmaceutical') to narrow down results and improve accuracy."
},
{
"code": "provide_full_legal_name",
"description": "Use the complete legal name including any entity type (Inc., LLC, GmbH, etc.)"
}
],
"metadata": {
"query": {
"name": "Umbrella Corporation",
"location": "2818 Lincoln East, Mishawaka, IN, 46544",
"context": null,
"mode": "standard",
"classification": "specific"
},
"updated_at": null,
"resolved_at": "2025-05-16T23:55:52.750Z",
"from_cache": false,
"cache_hit_type": null
}
}Match for currently unsupported entity type
{
"request_id": "reqs_2ZVVPGuv1FzTM06vuFMQl",
"status": "inconclusive",
"confidence": 99,
"type": "government",
"subtype": "government_entity",
"entity": null,
"candidate": {
"name": "FDA Birmingham Office",
"status": null,
"legal_name": null,
"description": "A regional office of the U.S. Food and Drug Administration located in Birmingham, Alabama.",
"jurisdiction": "US-AL",
"primary_address": {
"state_code": "AL",
"country_code": "US",
"full_address": "P.O. Box 830794, Birmingham, AL, 35283"
}
},
"factors": [
{
"code": "unsupported_entity_type",
"type": "limitation",
"impact": "Limited information can be extracted for government entities.",
"severity": "medium",
"description": "The US Food and Drug Administration is a government entity, which is not fully supported."
},
{
"code": "no_legal_entity_confirmed",
"type": "limitation",
"impact": "Lack of legal entity details may limit the depth of available information.",
"severity": "medium",
"description": "While the entity is confirmed, a distinct legal entity record isn't available."
}
],
"actions": [
{
"code": "verify_entity_type",
"description": "Confirm whether a government entity is the correct target, and if so, understand that information might be limited."
},
{
"code": "focus_on_available_data",
"description": "Focus on available data such as headquarters location, key personnel, and official announcements, rather than legal registration details."
}
],
"metadata": {
"query": {
"mode": "standard",
"name": "US Food and Drug Administration",
"context": null,
"location": "PO Box 830794, Birmingham, AL, 35283",
"classification": "specific"
},
"from_cache": false,
"updated_at": null,
"resolved_at": "2025-05-16T23:56:06.798Z",
"cache_hit_type": null
}
}