# Instant search across legal and master entities

`GET /v2/search`

> Tag: Instant entity search

Fast dual-index search (<1 second) that searches both legal entity registrations (200M+ records, exact name matching) and master entity profiles (curated enriched records, fuzzy/phonetic matching) in parallel.

**Dual-ID pattern:** Every result has an `id` (always a legal entity ID, `le_xxx`) and an `entity_id` (master entity ID, `siq_xxx`) when the entity has been consolidated into the master graph. Results with a non-null `entity_id` are enriched profiles sourced from the master entities index and are returned first. Legal-entity-only results (null `entity_id`) follow.

If `entity_id` is null, trigger Entity Resolution to create a master record.

**Graceful degradation:** If the master entities index is temporarily unavailable, the endpoint silently falls back to legal entities only.

## Request

### Query parameters

- `name` (string, required) — Entity name to search for (minimum 2 characters)
- `country_code` (string) — Filter by ISO country code (e.g., US, GB, CA). Also filters master entities by primary legal entity jurisdiction and headquarters country.
- `region_code` (string) — Filter by region/state/province code for US state-level filtering (e.g., CA, NY, DE)
- `limit` (integer) — Maximum number of results to return (1–10, default 10)
- `bypass_cache` (boolean) — Bypass the response cache and force a fresh query

### Example request

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

## Responses

### 200 — OK

- `results` (array<object>) — Array of matching entities. Master entity results (non-null entity_id) are returned first (higher quality curated matches), followed by legal-entity-only results.
  - `id` (string) — Legal entity ID. Always an `le_xxx` identifier.
  - `entity_id` (string) — Master entity ID (`siq_xxx`). Non-null when this entity has been consolidated into the master graph. Null for legal-entity-only results.
  - `name` (string) — Entity name
  - `status` (string) — Current status
  - `is_branch` (boolean) — Indicates if this is likely a branch/foreign qualification of another entity
  - `jurisdiction` (object)
    - `country` (string)
    - `country_code` (string)
    - `jurisdiction_code` (string) — Combined country/state jurisdiction code (e.g. us_de for Delaware)
- `metadata` (object)
  - `total` (integer) — Total number of results returned
  - `returned` (integer) — Number of results in this response
  - `query_time_ms` (integer) — Query execution time in milliseconds
- `request_id` (string) — Unique request identifier

```json
{
  "results": [
    {
      "id": "le_2Zp3YaC1I4wgYZpQDPgx8",
      "entity_id": "siq_2ZYEAh7VdPkWsvlsqW9lG",
      "name": "Google",
      "status": "active",
      "is_branch": false,
      "jurisdiction": {
        "country": "United States of America",
        "country_code": "US",
        "jurisdiction_code": "us_de"
      }
    },
    {
      "id": "le_2ZoQ891RD9mDRM1E8bnDf",
      "entity_id": "siq_2ZYEAh7VdPkWsvlsqW9lG",
      "name": "Google LLC",
      "status": "active",
      "is_branch": true,
      "jurisdiction": {
        "country": "United States of America",
        "country_code": "US",
        "jurisdiction_code": "us_sc"
      }
    },
    {
      "id": "le_2ZARUQAF1lba0EhCFyRfl",
      "entity_id": null,
      "name": "GOOGLE LLC",
      "status": "active",
      "is_branch": false,
      "jurisdiction": {
        "country": "United States of America",
        "country_code": "US",
        "jurisdiction_code": "us_ct"
      }
    }
  ],
  "metadata": {
    "total": 5,
    "returned": 5,
    "query_time_ms": 42
  },
  "request_id": "req_31ffecAT4FNPZDDVD1gZw"
}
```

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