# Owner research and contacts

> Documentation index: [llms.txt](https://westkite.com/docs/llms.txt). Every page is also at its URL plus `.md`.

Owner research identifies the people behind a property's owner of record, such as the managers of an LLC or the trustees of a trust. To retrieve an email, phone number or LinkedIn profile for a person it identifies, pass their `person_id` to `POST /v1/contacts` ([below](#retrieve-contact-details)).

Start owner research on up to 100 properties. West Kite traces each owner of record through deeds, state business registries, SEC filings and the web to the people who decide, and returns the people, companies and sources it found. Research costs $0.10 a property.

```endpoint
POST /v1/research
GET /v1/research/{id}
POST /v1/contacts
```

## Body

| Name | Type | Description |
|---|---|---|
| `property_ids` | array of strings | 1 to 100 property IDs, as `property:<uuid>` or bare UUIDs. Duplicates are dropped. |

Research needs a key with the `research` [scope](https://westkite.com/docs/api/authentication.md#scopes), for starting runs and for reading them. Through the API it runs without an approval step, so the key's [spend cap](https://westkite.com/docs/api/authentication.md#spend-caps) is your control.

## Start runs

```curl
curl https://api.westkite.com/v1/research \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hadley-2026-11-15" \
  -d '{ "property_ids": ["property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0"] }'
```

```typescript
const res = await fetch("https://api.westkite.com/v1/research", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WESTKITE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "hadley-2026-11-15",
  },
  body: JSON.stringify({ property_ids: ["property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0"] }),
});
const { data } = await res.json(); // 202 Accepted
```

```python
import os, requests

res = requests.post(
    "https://api.westkite.com/v1/research",
    headers={"Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}", "Idempotency-Key": "hadley-2026-11-15"},
    json={"property_ids": ["property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0"]},
)
runs = res.json()["data"]["runs"]
```

```json 202
{
  "data": {
    "runs": [
      {
        "id": "6c1f3a9e-…",
        "property_id": "property:3f2b9c1e-…",
        "status": "queued",
        "created_at": "2026-11-15T18:02:11.000Z",
        "completed_at": null,
        "charged_usd": 0,
        "result": null
      }
    ],
    "note": "Poll GET /v1/research/{id}?wait=60. Each run costs 0.1 USD; a run that names no person costs nothing."
  },
  "missing": [],
  "billing": { "operation_id": "op_2f61…", "operation": "research", "charged_usd": 0, "balance_usd": 9.98 },
  "request_id": "req_2f61…"
}
```

You get one run per property. Each run holds $0.10 of your balance while it works, so the balance must cover every run you start. When it finishes, the hold is settled at $0.10, less your plan's discount on purchased balance. Failed calls and lookups that find nothing cost nothing.

## Get a run

`wait` holds the request open for up to 60 seconds until the run finishes, so you can poll without a loop of quick calls. Reading a run is free.

```curl
curl "https://api.westkite.com/v1/research/6c1f3a9e-5b2d-4e8a-9f10-2a7c3d4b5e6f?wait=60" \
  -H "Authorization: Bearer $WESTKITE_API_KEY"
```

```json 200
{
  "data": {
    "id": "6c1f3a9e-…",
    "property_id": "property:3f2b9c1e-…",
    "status": "complete",
    "created_at": "2026-11-15T18:02:11.000Z",
    "completed_at": "2026-11-15T18:04:37.000Z",
    "charged_usd": 0.1,
    "result": {
      "names_person": true,
      "owner_of_record": "Hadley Brothers LLC",
      "people": [
        {
          "person_id": "person:3f2b9c1e-…:p2",
          "name": "Walt Hadley",
          "roles": ["manager"],
          "available": { "email": true, "phone": true, "linkedin": false }
        }
      ],
      "companies": [{ "name": "Hadley Brothers LLC", "kind": "company", "roles": ["recorded_owner"], "website": null }],
      "sources": [{ "title": "Statement of Information", "url": "https://bizfileonline.sos.ca.gov/…", "publisher": "California Secretary of State" }],
      "summary": ["Walt Hadley manages Hadley Brothers LLC, the owner of record since 1971."]
    }
  },
  "missing": [],
  "billing": { "operation_id": "op_b712…", "operation": "research", "charged_usd": 0, "balance_usd": 9.88 },
  "request_id": "req_b712…"
}
```

`status` is `queued`, `running`, `complete` or `failed`. A failed run carries an `error_code` and costs nothing. The run's own `charged_usd` is what the research cost; the poll's `billing` is the poll, which is free.

A run that names nobody completes with `names_person: false`, and `not_found` for `result.people` in `missing`. When West Kite has already found a phone number, email or LinkedIn for a person, `available` marks it `true`: call [contacts](https://westkite.com/docs/api/research.md#retrieve-contact-details) with the `person_id` and channel to get it, and it's charged then.

## Concurrency

Runs above your plan's limit of research at once wait as `queued` and start as others finish, on your next poll or within a few minutes. They never fail for being over the limit. See [Rate limits](https://westkite.com/docs/api/rate-limits.md).

## Errors

| Code | When |
|---|---|
| [`scope_missing`](https://westkite.com/docs/api/errors.md#scope_missing) | The key doesn't have the `research` scope. |
| [`insufficient_balance`](https://westkite.com/docs/api/errors.md#insufficient_balance) | The balance can't hold $0.10 for every run. |
| [`spend_limit_exceeded`](https://westkite.com/docs/api/errors.md#spend_limit_exceeded) | The key's monthly cap would be passed. |
| [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) | No IDs, more than 100, or an ID that isn't a property ID. |
| [`not_found`](https://westkite.com/docs/api/errors.md#not_found) | No run with that ID on your team. |
| [`service_unavailable`](https://westkite.com/docs/api/errors.md#service_unavailable) | Owner research isn't available right now. |

## Retrieve contact details

Find an email, phone number or LinkedIn profile for a person that owner research identified. An email is $0.50, a phone number $1 and a LinkedIn profile $0.50. Failed calls and lookups that find nothing cost nothing.
### Contact body

| Name | Type | Description |
|---|---|---|
| `person_id` | string | A person's `person_id` from a research result or a property's `owner` part, like `person:<property uuid>:<party id>`. |
| `channel` | string | `email`, `phone` or `linkedin`. |

Contacts need a key with the `contacts` [scope](https://westkite.com/docs/api/authentication.md#scopes).

### Contact request

```curl
curl https://api.westkite.com/v1/contacts \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "person_id": "person:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0:p2", "channel": "email" }'
```

```typescript
const res = await fetch("https://api.westkite.com/v1/contacts", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.WESTKITE_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ person_id: "person:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0:p2", channel: "email" }),
});
const { data, missing } = await res.json();
```

```python
import os, requests

res = requests.post(
    "https://api.westkite.com/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}"},
    json={"person_id": "person:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0:p2", "channel": "email"},
)
body = res.json()
```

### Contact response

```json 200
{
  "data": {
    "person_id": "person:3f2b9c1e-…:p2",
    "channel": "email",
    "value": "walt@example.com",
    "status": "deliverable",
    "verified_at": "2026-11-15T18:06:02.000Z",
    "found": true,
    "refetched": false,
    "revealed_at": "2026-11-15T18:06:02.000Z"
  },
  "missing": [],
  "billing": { "operation_id": "op_71b4…", "operation": "contact_email", "charged_usd": 0.5, "balance_usd": 9.38 },
  "request_id": "req_71b4…"
}
```

When nothing is found, `value` is `null`, `found` is `false`, and `missing` says `not_found` for the channel.

### Fetch a contact again

A contact your team has revealed is free to fetch again for a year: the answer comes back with `refetched: true` and no charge. Store the `person_id`, not just the value.

### Contact errors

| Code | When |
|---|---|
| [`scope_missing`](https://westkite.com/docs/api/errors.md#scope_missing) | The key doesn't have the `contacts` scope. |
| [`not_found`](https://westkite.com/docs/api/errors.md#not_found) | No research is on file for that property, or no person has that ID in it. |
| [`insufficient_balance`](https://westkite.com/docs/api/errors.md#insufficient_balance) | The balance can't cover the channel's price. |
| [`spend_limit_exceeded`](https://westkite.com/docs/api/errors.md#spend_limit_exceeded) | The key's monthly cap would be passed. |
