# Search

> Find people and companies with an account's search, and turn hits into lead lists.

Run people and company searches on behalf of a connected account and save the results as reusable lead lists.

## Search people or companies

```http
POST /v1/search
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | yes | The account to search with. |
| `type` | string | yes | `people` or `company`. |
| `keywords` | string | yes | The search query. |
| `pages` | integer | no | Result pages to fetch, `1`–`3`. Default `1`. |

```bash
curl -X POST https://api.correctinbox.com/v1/search \
  -H "X-API-KEY: $CORRECTINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_8f21c0", "type": "people", "keywords": "head of sales", "pages": 2 }'
```

```js
const res = await fetch("https://api.correctinbox.com/v1/search", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.CORRECTINBOX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ account_id: "acc_8f21c0", type: "people", keywords: "head of sales", pages: 2 }),
});
const { results, total } = await res.json();
```

```python
res = requests.post(
    "https://api.correctinbox.com/v1/search",
    headers={"X-API-KEY": os.environ["CORRECTINBOX_API_KEY"]},
    json={"account_id": "acc_8f21c0", "type": "people", "keywords": "head of sales", "pages": 2},
)
data = res.json()
```

**Response**

```json
{
  "type": "people",
  "total": 18,
  "results": [
    {
      "id": "ACoAAB1x...",
      "name": "Priya Menon",
      "headline": "Head of Sales at Northwind",
      "company": "Northwind"
    }
  ]
}
```

> **Empty results.** If a real keyword returns `total: 0`, the account most likely has limited search access on the provider (common on new accounts), not a failed request. See [Connection status](/connection-status). Response also includes `"limited": true` in that case.

## Save a lead list

Persist selected results so campaigns can target them later.

```http
POST /v1/lead-lists
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | A name for the list. |
| `source` | string | no | `people_search`, `company_search` or `import`. |
| `leads` | array | yes | The lead objects to store (ids from a search). |

```bash
curl -X POST https://api.correctinbox.com/v1/lead-lists \
  -H "X-API-KEY: $CORRECTINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Heads of Sales — Feb",
    "source": "people_search",
    "leads": [{ "id": "ACoAAB1x...", "name": "Priya Menon" }]
  }'
```

```js
await fetch("https://api.correctinbox.com/v1/lead-lists", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.CORRECTINBOX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Heads of Sales — Feb",
    source: "people_search",
    leads: [{ id: "ACoAAB1x...", name: "Priya Menon" }],
  }),
});
```

```python
requests.post(
    "https://api.correctinbox.com/v1/lead-lists",
    headers={"X-API-KEY": os.environ["CORRECTINBOX_API_KEY"]},
    json={
        "name": "Heads of Sales — Feb",
        "source": "people_search",
        "leads": [{"id": "ACoAAB1x...", "name": "Priya Menon"}],
    },
)
```

## Manage lead lists

```http
GET    /v1/lead-lists            # list all lists (without leads)
GET    /v1/lead-lists/{list_id}  # one list, with its leads
DELETE /v1/lead-lists/{list_id}  # delete a list
```