SavvyIQ
2026-03-11

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 entity field with the schema of that entity type.
  • For lower-confidence matches or entity types not fully supported yet, the response will contain a candidate field with best-guess information.
  • The response will never have both entity and candidate fields populated simultaneously.
  • We will continue to expand the set of entity types we support.

Query parameters

  • namestring required
    Entity name
  • locationstring
    Entity location

Responses

200 OK
  • request_idstring
    The request ID for this API call
  • statusstring (enum)
    matchedpartial_matchinconclusiveno_match

    Status 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)
    businessnonprofitgovernmentpersonotherunknown
    The 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_entityunknown
    The entity subtype. Currently the system only fully supports "incorporated_entity" subtypes. Other subtypes (like "unincorporated_entity", "government", "fund") will be returned as candidates only.
  • confidenceinteger
    The confidence score of the match (0-100). Higher scores generally correspond to entity records, while lower scores correspond to candidates.
  • entityobject
    The 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
    • idstring
    • namestring
    • statusstring (enum)
      activeinactive
    • websitestring
    • descriptionstring
    • headquartersobject
      Show 6 nested fieldsHide nested fields
      • citystring
      • statestring
      • addressstring
      • countrystring
      • state_codestring
      • country_codestring
    • matching_branchobject
      Show 5 nested fieldsHide nested fields
      • notesstring
      • addressstring
      • state_codestring
      • country_codestring
      • jurisdictionstring
    • primary_legal_entityobject
      Show 5 nested fieldsHide nested fields
      • idstring
      • namestring
      • state_codestring
      • country_codestring
      • jurisdictionstring
  • candidateobject

    Best 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:

    1. The confidence is too low to create a definitive record
    2. The entity type or subtype is not fully supported yet (e.g., unincorporated entities, governments, funds)
    Show 6 nested fieldsHide nested fields
    • namestring
    • legal_namestring
    • jurisdictionstring
    • statusstring (enum)
      activeinactive
    • descriptionstring
    • primary_addressobject
      Show 3 nested fieldsHide nested fields
      • full_addressstring
      • state_codestring
      • country_codestring
  • factorsarray<object>
    Factors contributing to the match decision
    Show 4 nested fieldsHide nested fields
    • codestring
    • typestring (enum)
      strengthlimitation
    • impactstring
    • descriptionstring
  • actionsarray<object>
    Suggested actions for the user
    Show 2 nested fieldsHide nested fields
    • codestring
    • descriptionstring
  • metadataobject
    Additional information about the request
    Show 5 nested fieldsHide nested fields
    • queryobject
      Show 5 nested fieldsHide nested fields
      • modestring
      • namestring
      • contextstring
      • locationstring
      • classificationstring
    • from_cacheboolean
    • updated_atstring <date-time>
    • resolved_atstring <date-time>
    • cache_hit_typestring
400 Bad Request
  • errorobject
    An error object.
    Show 2 nested fieldsHide nested fields
    • messagestring
      The error message
    • typestring
      The error code
401 Unauthorized
  • messagestring
    The error object.
  • request_idstring
    The request ID for the error.
500 Internal Server Error
  • errorobject
    An error object.
    Show 2 nested fieldsHide nested fields
    • messagestring
      The error message
    • typestring
      The error code
502 Request timeout
  • errorobject
    An error object.
    Show 2 nested fieldsHide nested fields
    • messagestring
      The error message
    • typestring
      The 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
  }
}