> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agentic-id.icustomer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Find

> Find people in a role inside one company.

`POST /v1/find` answers: who holds this role at this company? Name one company and the titles or seniority you want, and get back people with a work email that passed verification. Use it when you know the account and need the contact. To find new companies, use [Discover](https://docs-agentic-id.icustomer.ai/products/discover.md).

```bash curl theme={null}
curl -X POST https://YOUR_AGENTIC_ID_HOST/v1/find \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6a1e8b34-2c7d-4e9f-b0a3-8d5c1f7e2b46" \
  -d '{
    "account": { "domain": "acme.example" },
    "roles": ["VP Marketing", "Head of Growth"],
    "limit": 2,
    "max_credits": 4
  }'
```

```typescript TypeScript theme={null}
import { AgenticId } from '@ic/agentic-id-sdk';

const client = new AgenticId({
  apiKey: process.env.AGENTIC_ID_API_KEY,
  baseUrl: 'https://YOUR_AGENTIC_ID_HOST',
});

const reply = await client.find({
  account: { domain: 'acme.example' },
  roles: ['VP Marketing', 'Head of Growth'],
  limit: 2,
  max_credits: 4,
});
for (const p of reply.people) console.log(p.name, p.title, p.email);
```

```bash CLI theme={null}
agentic-id find acme.example --role "VP Marketing" --role "Head of Growth" --limit 2 --max-credits 4
```

```json 200 theme={null}
{
  "request_id": "req_c3f5a7b9-0d2e-4a6c-8e1f-3b5d7f9a1c24",
  "summary": "1 person found at acme.example. 2 credits charged.",
  "cost": { "quoted_credits": 4, "charged_credits": 2 },
  "account_id": "ic-7Kq2mXv9RtB4nWc8Zp1LdE",
  "people": [
    {
      "id": "ic-4Hn8sPq1VxC6yTb3Ku9MwR",
      "account_id": "ic-7Kq2mXv9RtB4nWc8Zp1LdE",
      "name": "Alex Rivera",
      "title": "VP Marketing",
      "email": "a******@acme.example",
      "level": "trusted"
    }
  ],
  "excluded": { "no_email": 1 },
  "rejected": []
}
```

> [!NOTE]
>
> Emails are returned masked today: the first character and the domain are kept.

## Request

**account** `object` *required*

The company to search in. Send `id` or `domain`.

**properties**

**id** `string`

The company's Agentic ID.

**domain** `string`

The company's website domain.

**roles** `string[]`

Titles to look for, for example `["VP Marketing", "Head of Growth"]`. Each up to 100 characters. Send `roles`, `seniority`, or both.

**seniority** `string | string[]`

Seniority to look for, for example `"director+"` or `["vp", "c_suite"]`.

**countries** `string[]`

Where the person is. This is the person's location, not the company's headquarters.

**limit** `integer` (default: 5)

The most people to return. 1 to 25.

**exclude\_seen** `boolean` (default: true)

Skip people already delivered to your workspace by Find or Discover.

**purpose** `string` (default: b2b\_outbound)

Why you are asking. One of `b2b_outbound`, `ad_audience`, `own_customer_enrichment`, `fraud_check`. The call is refused if your workspace has not allowed the purpose.

**max\_credits** `integer` *required*

The most this call may charge. 0 to 100000. Never charged past it.

## Response

**request\_id** `string` *required*

The ID of this call. The same value as the `X-Request-Id` header.

**summary** `string` *required*

One plain sentence: how many people were found, the charge, and why the search stopped early if it did.

**cost** `object` *required*

**properties**

**quoted\_credits** `number` *required*

The most the call could have charged.

**charged\_credits** `number` *required*

What it charged. Never more than quoted.

**account\_id** `string`

The Agentic ID of the company that was searched.

**people** `object[]` *required*

The people delivered.

**properties**

**id** `string` *required*

The person's Agentic ID.

**account\_id** `string` *required*

The Agentic ID of their company.

**name** `string`

Full name.

**title** `string`

Job title.

**email** `string` *required*

Work email, masked.

**level** `string` *required*

How the record as a whole was judged: `trusted` or `plausible`.

**excluded** `object` *required*

Why candidates were left out, as reason and count. For example `person_already_delivered`, `person_name_hidden_by_source`, `no_email`.

**rejected** `object[]` *required*

Filter values that could not be read. They are returned, never silently dropped.

**properties**

**field** `string` *required*

The filter the value was sent in.

**value** `string` *required*

The value that could not be read.

**stopped\_early** `string`

Set when the search stopped at one of Agentic ID's own limits on paid sources. See [What it costs](#what-it-costs).

## What it costs

| Result | Credits |
| - | - |
| Each person delivered | 2 |
| The company itself | 0 |
| Candidates listed in `excluded` | 0 |

* `quoted_credits` is 2 times `limit`, or `max_credits` if that is lower.
* `max_credits` is required. The search stops when the next person would not fit under it.
* If your balance covers only part of the request, the part it covers is delivered.

`stopped_early` values. In every case nothing is charged for what was not delivered.

| Value | Meaning | What to do |
| - | - | - |
| `source_budget` | Agentic ID's daily budget for paid sources is used up. | Try again after midnight UTC. |
| `request_source_budget` | This request reached the limit on paid-source spend per request. | Ask again for the rest. A new request starts with a fresh limit. |
| `source_call_limit` | The remaining paid source costs more for one lookup than Agentic ID allows. | Asking again will not change it. Contact support. |

See [Credits](https://docs-agentic-id.icustomer.ai/credits.md) for how holds and charges work.

## Errors

| Status | Code | Meaning | Retry |
| - | - | - | - |
| 400 | `request.invalid` | The body does not match the schema, `max_credits` is missing, or `account` has neither `id` nor `domain`. | No. Fix the body. |
| 400 | `find.persona_unreadable` | No readable title or seniority was sent. `rejected` lists the values that could not be read. | No. Send `roles` or a readable `seniority`. |
| 400 | `find.account_unknown` | `account.id` was sent and no domain is known for it. | No. Send `account.domain`. |
| 400 | `idempotency.key_invalid` | The `Idempotency-Key` is not 8 to 200 printable characters. | No. Fix the key. |
| 401 | `auth.invalid_key` | No valid credential was sent. | No. |
| 401 | `auth.token_expired` | Your sign-in has expired. | After you refresh the token. |
| 402 | `credits.insufficient` | No credits are available. Nothing was charged. | After adding credits. |
| 403 | `purpose.not_allowed` | Your workspace has not allowed this `purpose`. | No. |
| 409 | `idempotency.in_progress` | The first request with this key is still running. | Yes, after `Retry-After`, same key. |
| 422 | `find.account_unresolvable` | The domain could not be resolved to a company. | No. Check the domain. |
| 422 | `idempotency.key_reused` | The key was already used with a different body. | No. Use a new key. |
| 429 | `rate_limited` | Too many requests. | Yes, after `Retry-After`. |
| 502 | `service.error` | A fault on our side. | Yes, with the same `Idempotency-Key`. |
| 503 | `service.unavailable` | Temporarily unavailable. | Yes, after `Retry-After`, same key. |
| 504 | `service.timeout` | The call took too long. It may still have completed. | Yes, with the same `Idempotency-Key`. |

See [Errors](https://docs-agentic-id.icustomer.ai/errors.md) for the full list.

## Behaviour

* **A role is required.** Send `roles`, a readable `seniority`, or both.
* **`exclude_seen` is on by default.** Asking again returns different people, because those already delivered to your workspace are skipped and counted in `excluded` as `person_already_delivered`. Set it to `false` to get them again; they are charged again.
* **People need a full name or a profile link.** A candidate is only usable if an email can be looked up for it, which needs a first and last name or a profile link. Candidates without either are counted in `excluded` as `person_name_hidden_by_source`.
* **Only people with an email that passed verification are delivered.** A candidate with no email is counted as `no_email`. One whose email did not pass is counted under a reason starting with `email_`.
* **Fewer than `limit` is normal.** One call looks at a limited number of candidates. `excluded` says why the rest were left out.
* **One company per call.** For people across many companies, use [Discover](https://docs-agentic-id.icustomer.ai/products/discover.md) with `contact_filters`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.