# Deep research for entity by name (streaming)

`GET /v2/entity-resolution/stream`

> Tag: Entity resolution

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.

## Request

### Query parameters

- `name` (string, required) — Entity name
- `location` (string) — Entity location

### Example request

```bash
curl --request GET \
  --url 'https://api.savvyiq.ai/v2/entity-resolution/stream?name=value' \
  --header 'apikey: YOUR_API_KEY'
```

## Responses

### 200 — OK

- `request_id` (string) — The request ID for this API call
- `status` (string (enum)) — 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
- `type` (string (enum)) — The entity type. Currently the system only fully supports "business" types. Other types may be identified but will be returned as candidates only.
- `subtype` (string (enum)) — 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.
- `confidence` (integer) — The confidence score of the match (0-100). Higher scores generally correspond to entity records, while lower scores correspond to candidates.
- `entity` (object) — 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.
  - `id` (string)
  - `name` (string)
  - `status` (string (enum))
  - `website` (string)
  - `description` (string)
  - `headquarters` (object)
    - `city` (string)
    - `state` (string)
    - `address` (string)
    - `country` (string)
    - `state_code` (string)
    - `country_code` (string)
  - `matching_branch` (object)
    - `notes` (string)
    - `address` (string)
    - `state_code` (string)
    - `country_code` (string)
    - `jurisdiction` (string)
  - `primary_legal_entity` (object)
    - `id` (string)
    - `name` (string)
    - `state_code` (string)
    - `country_code` (string)
    - `jurisdiction` (string)
- `candidate` (object) — 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)
  - `name` (string)
  - `legal_name` (string)
  - `jurisdiction` (string)
  - `status` (string (enum))
  - `description` (string)
  - `primary_address` (object)
    - `full_address` (string)
    - `state_code` (string)
    - `country_code` (string)
- `factors` (array<object>) — Factors contributing to the match decision
  - `code` (string)
  - `type` (string (enum))
  - `impact` (string)
  - `description` (string)
- `actions` (array<object>) — Suggested actions for the user
  - `code` (string)
  - `description` (string)
- `metadata` (object) — Additional information about the request
  - `query` (object)
    - `mode` (string)
    - `name` (string)
    - `context` (string)
    - `location` (string)
    - `classification` (string)
  - `from_cache` (boolean)
  - `updated_at` (string <date-time>)
  - `resolved_at` (string <date-time>)
  - `cache_hit_type` (string)

```json
{
  "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
  }
}
```

### 400 — Bad Request

- `error` (object) — An error object.
  - `message` (string) — The error message
  - `type` (string) — The error code

```json
{
  "error": {
    "message": "Bad request",
    "type": "bad_request"
  }
}
```

### 401 — Unauthorized

- `message` (string) — The error object.
- `request_id` (string) — The request ID for the error.

```json
{
  "message": "No API key found in request",
  "request_id": "d6ed1709fa87777bb373fd60a810e717"
}
```

### 500 — Internal Server Error

- `error` (object) — An error object.
  - `message` (string) — The error message
  - `type` (string) — The error code

```json
{
  "error": {
    "message": "An unexpected error occurred.",
    "type": "api_error"
  }
}
```

### 502 — Request timeout

- `error` (object) — An error object.
  - `message` (string) — The error message
  - `type` (string) — The error code

```json
{
  "error": {
    "message": "Request timeout",
    "type": "timeout"
  }
}
```