# Entity search (JSON body)

`POST /v2/search`

> Tag: Entity search

Same as `GET`, with the parameters in a JSON body.

## Request

### Body (application/json)

- `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 POST \
  --url 'https://api.savvyiq.ai/v2/search' \
  --header 'apikey: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{"name":"Google LLC","country_code":"US","region_code":"DE","limit":10,"bypass_cache":false}'
```

## 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)
  - `type` (string) — Stable, machine-readable error code.
  - `message` (string) — Human-readable explanation. Do not match on this.

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

### 401 — Unauthorized

- `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 — Internal Server Error

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