# Get status of deep research request

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

> Tag: Entity resolution

Retrieve the status and result of an async deep research request. Poll every 5-10 seconds.
Polls are free.

Returns **202** while `PENDING`, and **200** once the job is terminal — `COMPLETED` *or*
`FAILED`. A failure is reported in the body with HTTP 200, not as an error status.

`COMPLETED` does not mean a match was found. Branch on whether `data.entity` or
`data.candidate` is populated — they are never both set, and on `no_match` / `not_found`
neither is.

See also: [Handling responses](/docs/handling-responses) ·
[Confidence and explainability](/docs/concepts/confidence-and-explainability) ·
[Batch processing](/docs/guides/batch-processing)

## 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 — The job is terminal. `status` is `COMPLETED` or `FAILED` — both return 200.

- `request_id` (string, required)
- `status` (string (enum), required) — Job lifecycle state. * `PENDING` — still researching; HTTP 202, `data` is `null` * `COMPLETED` — finished; read `data.status` for the outcome * `FAILED` — did not complete; `data` is `null` and the request is refunded
- `data` (object) — The resolution result. `null` while `PENDING` and on `FAILED`.
  - `request_id` (string) — The request ID for this API call
  - `status` (string (enum)) — Outcome of the resolution. Distinct from the job lifecycle `status` on the polling envelope — a `COMPLETED` job carrying `no_match` is still a successful call. * `matched` - confidence 80 or above; `entity` is populated * `partial_match` - resolved to a known business, confidence below 80; `entity` is populated * `inconclusive` - multiple possible matches, or an entity type not fully supported; `candidate` may hold a best guess * `no_match` - no matches found; both `entity` and `candidate` are `null` * `not_found` - the query did not correspond to a resolvable business; both `entity` and `candidate` are `null` `entity` and `candidate` are never both populated, but they can both be `null` — that is how "we found nothing" is represented. Always handle the neither-present case.
  - `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) — Whether the resolution engine answered from its query cache instead of running fresh research. Specific to the research layer, not a general "response was cached" flag.
    - `updated_at` (string <date-time>)
    - `resolved_at` (string <date-time>)
    - `cache_hit_type` (string (enum)) — How the cache was hit when `from_cache` is true; `null` otherwise. * `exact` - the same query was resolved before * `similar` - a semantically equivalent query was reused * `domain_cache` - answered from a previous domain lookup

```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
    }
  }
}
```

### 202 — Still processing. `status` is `PENDING`, `data` is `null`. Keep polling.

- `request_id` (string, required)
- `status` (string (enum), required) — Job lifecycle state. * `PENDING` — still researching; HTTP 202, `data` is `null` * `COMPLETED` — finished; read `data.status` for the outcome * `FAILED` — did not complete; `data` is `null` and the request is refunded
- `data` (object) — The resolution result. `null` while `PENDING` and on `FAILED`.
  - `request_id` (string) — The request ID for this API call
  - `status` (string (enum)) — Outcome of the resolution. Distinct from the job lifecycle `status` on the polling envelope — a `COMPLETED` job carrying `no_match` is still a successful call. * `matched` - confidence 80 or above; `entity` is populated * `partial_match` - resolved to a known business, confidence below 80; `entity` is populated * `inconclusive` - multiple possible matches, or an entity type not fully supported; `candidate` may hold a best guess * `no_match` - no matches found; both `entity` and `candidate` are `null` * `not_found` - the query did not correspond to a resolvable business; both `entity` and `candidate` are `null` `entity` and `candidate` are never both populated, but they can both be `null` — that is how "we found nothing" is represented. Always handle the neither-present case.
  - `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) — Whether the resolution engine answered from its query cache instead of running fresh research. Specific to the research layer, not a general "response was cached" flag.
    - `updated_at` (string <date-time>)
    - `resolved_at` (string <date-time>)
    - `cache_hit_type` (string (enum)) — How the cache was hit when `from_cache` is true; `null` otherwise. * `exact` - the same query was resolved before * `similar` - a semantically equivalent query was reused * `domain_cache` - answered from a previous domain lookup

```json
{
  "request_id": "reqa_2ZUKmavJxCx4GHMnpJsc9",
  "status": "COMPLETED",
  "data": {
    "request_id": "reqa_2ZUKmavJxCx4GHMnpJsc9",
    "status": "matched",
    "type": "business",
    "subtype": "incorporated_entity",
    "confidence": 98,
    "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"
      },
      "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"
      },
      "primary_legal_entity": {
        "id": "le_2ZoRp6I3EUgebkUBHaDdk",
        "name": "APPLE INC.",
        "state_code": null,
        "country_code": "US",
        "jurisdiction": "California"
      }
    },
    "candidate": {
      "name": "Apple Inc.",
      "legal_name": "Apple Inc.",
      "jurisdiction": "Delaware",
      "status": "active",
      "description": "Technology company that designs and manufactures consumer electronics",
      "primary_address": {
        "full_address": "1 Apple Park Way, Cupertino, CA 95014, USA",
        "state_code": "CA",
        "country_code": "US"
      }
    },
    "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."
      }
    ],
    "actions": [
      {
        "code": "provide_full_legal_name",
        "description": "Use the complete legal name, including any location or additional identifiers in the official name (e.g., 'Vast US Inc.')."
      }
    ],
    "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"
}
```

### 404 — No such `request_id` for this account. IDs are account-scoped, so another account's `request_id` returns 404 rather than revealing that it exists. A malformed `request_id` returns 500, not 404.

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

```json
{
  "error": {
    "message": "The requested resource could not be found.",
    "type": "not_found"
  }
}
```

### 429 — Rate limit exceeded — 600 requests/minute per account on this endpoint. See [rate limits](/docs/rate-limits).

- `message` (string) — The error message

```json
{
  "message": "API rate limit exceeded"
}
```

### 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"
  }
}
```

### 504 — Gateway Timeout — retry the poll with backoff.

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

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