# Resolve a company name

`GET /v3/entity-resolution/async`

> Tag: Entity Resolution

Starts a resolution job and returns immediately with a job ID. Research typically takes one
to five minutes; poll `GET /v3/jobs/{job_id}` for the result.

Resolution finds the company through government registries and live web research, then
anchors it to an official registration. Use `context` to say *which* company you mean when
a name is ambiguous.

## Request

### Query parameters

- `name` (string, required) — Company name, legal or brand. At least 2 characters.
- `location` (string) — Free-text location hint: city, state, country, or any combination. Narrows an ambiguous name considerably.
- `context` (string) — Free text describing which company you mean: industry, products, customers, anything distinguishing. Used only to choose between same-name candidates. It never overrides government-registry evidence and never changes what is searched. `name=Delta` on its own is ambiguous. `name=Delta` with `context=major commercial passenger airline` resolves to Delta Air Lines, Inc.
- `include` (string (enum)) — Set to `basis` to attach the provenance plane to the result: per-field confidence, reasoning, and citations back to the sources. **Pass it on the poll as well.** Asking here is what makes the job record provenance; asking again on `GET /v3/jobs/{job_id}` is what puts it in the response body. A job kicked off without `basis` cannot gain it later, and a poll without `basis` omits the plane even when the job recorded one.

### Example request

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

## Responses

### 202 — Job accepted.

- `status` (string (enum))
- `job_id` (string) — Job identifier, accepted by `GET /v3/jobs/{job_id}`.
- `request_id` (string) — The `reqa_` form of the same job. Also accepted by `GET /v3/jobs/{job_id}`, and useful as a correlation ID in support requests.

```json
{
  "status": "pending",
  "job_id": "019fe975-186e-707c-b59a-b0a6c9914221",
  "request_id": "reqa_344tSxhAVACWbuENINJ9D"
}
```

### 400 — Invalid or missing parameters.

- `error` (object)
  - `type` (string) — Stable, machine-readable error code.
  - `message` (string) — Human-readable explanation. Do not match on this.

```json
{
  "error": {
    "type": "bad_request",
    "message": "Name is required"
  }
}
```

### 401 — Missing or invalid API key.

- `error` (object)
  - `type` (string) — Stable, machine-readable error code.
  - `message` (string) — Human-readable explanation. Do not match on this.

```json
{
  "error": {
    "type": "string",
    "message": "string"
  }
}
```

### 402 — Credit balance exhausted.

- `error` (object)
  - `type` (string) — Stable, machine-readable error code.
  - `message` (string) — Human-readable explanation. Do not match on this.

```json
{
  "error": {
    "type": "insufficient_credits",
    "message": "Insufficient credits"
  }
}
```

### 403 — This account is not enabled for the v3 API.

- `error` (object)
  - `type` (string) — Stable, machine-readable error code.
  - `message` (string) — Human-readable explanation. Do not match on this.

```json
{
  "error": {
    "type": "no_pricing_configured",
    "message": "No pricing configured for this API"
  }
}
```

### 429 — Rate limit exceeded.

- `error` (object)
  - `type` (string) — Stable, machine-readable error code.
  - `message` (string) — Human-readable explanation. Do not match on this.

```json
{
  "error": {
    "type": "string",
    "message": "string"
  }
}
```

### 500 — Something went wrong on our side.

- `error` (object)
  - `type` (string) — Stable, machine-readable error code.
  - `message` (string) — Human-readable explanation. Do not match on this.

```json
{
  "error": {
    "type": "string",
    "message": "string"
  }
}
```