# Get status of deep research request

`GET /v2/entity-resolution/status/{request_id}`

> Tag: Entity resolution

Retrieve status and results of async deep research. Poll every 5-10 seconds until status is "COMPLETED".

## Request

### Path parameters

- `request_id` (string, required) — ID of the resolution request

### Example request

```bash
curl --request GET \
  --url 'https://api.savvyiq.ai/v2/entity-resolution/status/reqa_2ZUKmavJxCx4GHMnpJsc9' \
  --header 'apikey: YOUR_API_KEY'
```

## Responses

### 200 — Successful response

- `request_id` (string, required)
- `status` (string (enum), required)
- `data` (object, required) — Response for entity resolution requests. **Important Notes:** - Either the `entity` or the `candidate` field will be populated, but never both. - The `entity` field is present when we have high confidence and have created a record in our system. - The `candidate` field is present when we have low confidence or the entity type is not fully supported yet. - Initially, only entities with type "business" and subtype "incorporated_entity" will be returned as `entity` objects. - The schema of the `entity` field may vary based on the `type` and `subtype` fields as support for different entity types is added.
  - `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": "reqa_2ZUKmavJxCx4GHMnpJsc9",
  "status": "COMPLETED",
  "data": {
    "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"
  }
}
```