> ## 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.

# Discover

> Find new companies, and people in them, that match your filters.

`POST /v1/discover` answers: which companies match these filters, and who works there? Send account filters and, if you want people too, contact filters. Use it to build a new list. Use `count_only` first to see how many companies match before anything is delivered.

```bash curl theme={null}
curl -X POST https://YOUR_AGENTIC_ID_HOST/v1/discover \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: f4b8d2a6-1c3e-4f5a-9b7d-0e2c4a6f8b13" \
  -d '{
    "account_filters": {
      "industry": ["software"],
      "country": ["GB"],
      "employees_min": 100,
      "employees_max": 2000
    },
    "contact_filters": { "job_title": ["CTO"], "per_account": 1 },
    "max_accounts": 2,
    "max_credits": 6
  }'
```

```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.discover({
  account_filters: { industry: ['software'], country: ['GB'], employees_min: 100, employees_max: 2000 },
  contact_filters: { job_title: ['CTO'], per_account: 1 },
  max_accounts: 2,
  max_credits: 6,
});
console.log(reply.accounts.length, reply.contacts.length, reply.cost.charged_credits);
```

```bash CLI theme={null}
agentic-id discover --industry software --country GB --min 100 --max 2000 \
  --title CTO --per-account 1 --max-accounts 2 --max-credits 6
```

```json 200 theme={null}
{
  "request_id": "req_e7a9c1b3-5d4f-4e6a-8c0b-2f4d6a8c0e35",
  "summary": "2 accounts (1 not charged: size from one source only) and 1 contact delivered. 3 credits charged.",
  "cost": { "quoted_credits": 6, "charged_credits": 3 },
  "accounts": [
    {
      "id": "ic-7Kq2mXv9RtB4nWc8Zp1LdE",
      "name": "Acme Software",
      "country": "GB",
      "domain": "acme.example",
      "employees": { "min": 201, "max": 500 },
      "size_check": "confirmed",
      "charged": true
    },
    {
      "id": "ic-9Tz3bLw5NcF1rJd7Gh2QsY",
      "name": "Globex Systems",
      "country": "GB",
      "domain": "globex.example",
      "employees": { "min": 501, "max": 1000 },
      "size_check": "single",
      "charged": false
    }
  ],
  "contacts": [
    {
      "id": "ic-4Hn8sPq1VxC6yTb3Ku9MwR",
      "account_id": "ic-7Kq2mXv9RtB4nWc8Zp1LdE",
      "name": "Alex Rivera",
      "title": "CTO",
      "email": "a******@acme.example",
      "level": "trusted"
    }
  ],
  "excluded": { "size_mismatch": 3, "no_email": 1 },
  "rejected": [],
  "plan": [
    { "provider": "source-a", "why": "source-a applies countries, industries; we check size" }
  ]
}
```

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

## Request

**account\_filters** `object` *required*

Which companies to look for. At least one readable filter is needed.

**properties**

**industry** `string[]`

Industries, in plain words. `filters_read_as` in the reply shows how a word was read.

**country** `string[]`

Countries the company is in, for example `["GB", "DE"]`.

**employees\_min** `integer`

Smallest company size. At least 1.

**employees\_max** `integer`

Largest company size. At least 1.

**technologies** `string[]`

Technologies the company uses.

**keywords** `string[]`

Words in the company description. They rank results. They filter only with `keywords_required`, or when they are the only filter.

**keywords\_required** `boolean`

When `true`, every result must mention one of `keywords`.

**contact\_filters** `object`

Send this to also get people inside the companies delivered. Needs `job_title` or a readable `job_level`.

**properties**

**job\_title** `string[]`

Titles to look for.

**job\_level** `string | string[]`

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

**countries** `string[]`

Where the person is.

**per\_account** `integer` (default: 2)

The most people per company. 1 to 10.

**min\_company\_size** `integer`

Skip people at companies smaller than this. At least 1.

**max\_accounts** `integer` (default: 25)

The most companies to deliver. 1 to 500.

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

Skip companies and people already delivered to your workspace.

**count\_only** `boolean` (default: false)

When `true`, nothing is delivered and nothing is charged. The reply says how many companies match and which source would be asked.

**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`

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: what was delivered, what was charged, and why fewer came back than asked if that happened.

**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.

**accounts** `object[]` *required*

The companies delivered. Empty on a count.

**properties**

**id** `string` *required*

The company's Agentic ID.

**name** `string`

Company name.

**domain** `string` *required*

Website domain.

**country** `string`

Country.

**employees** `object`

Size range: `min` (number) and `max` (number or `null` for no upper bound).

**size\_check** `string`

`confirmed`: two independent sources agree the size is in range. `single`: one source only, so the company is not charged. `not_filtered`: no size filter was sent.

**charged** `boolean` *required*

Whether this company was charged.

**contacts** `object[]` *required*

The people delivered. Empty without `contact_filters` and on a count.

**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 `already_delivered`, `size_mismatch`, `size_unknown`, `country_disputed`, `credit_cap`.

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

Filter values that could not be read, each with `field` and `value`. They are returned, never silently dropped.

**plan** `object[]` *required*

Which source was asked and what it could filter itself, each with `provider` and `why`.

**total\_at\_provider** `number`

On a count: about how many companies match at the source.

**count\_is\_upper\_bound** `boolean`

On a count: the source did not apply every filter, so fewer will pass when delivered.

**filters\_read\_as** `object[]`

How a plain word in a filter was read, each with `field`, `given` and `read_as`. Check it when a word was read as something broader than you meant.

**fewer\_than\_asked** `string`

Why fewer companies were delivered than `max_accounts`, when that happened.

**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 company delivered | 1 |
| A company with `size_check: "single"` | 0 |
| Each person delivered | 2 |
| A count (`count_only: true`) | 0 |

* `quoted_credits` is `max_accounts` times (1 + 2 times `per_account`), or `max_credits` if that is lower. Without `contact_filters` it is `max_accounts`.
* When `max_credits` is reached the search stops. `fewer_than_asked` says so and `excluded` counts `credit_cap`.
* 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. | No. Fix the body. |
| 400 | `discovery.filter_unreadable` | No account filter could be read. `rejected` lists the values. | No. Send at least one readable country, industry, size, technology or keyword. |
| 400 | `discovery.persona_unreadable` | `contact_filters` has no readable title or level. | No. Send `job_title` or a readable `job_level`. |
| 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. Not returned for a count. | 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 | `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

* **Count first.** `count_only: true` returns `total_at_provider`, an empty `accounts` and `contacts`, and a cost of 0. When `count_is_upper_bound` is `true`, expect fewer on delivery. `contact_filters` is not used on a count.
* **`keywords` rank, `keywords_required` filters.** By default keywords only order the results: companies that mention more of them come first. Set `keywords_required: true` to make every result mention one. When keywords are the only filter, they always filter.
* **Words are read, and you are told how.** A plain word such as an industry name may be read as a broader category or as a description keyword. `filters_read_as` shows it. Check the first results before asking for many.
* **`exclude_seen` is on by default.** Asking again with the same filters returns the next companies: those already delivered to your workspace are skipped and counted in `excluded` as `already_delivered`.
* **Fewer than `max_accounts` is normal.** One call reads a limited number of result pages and drops candidates that fail a check. `fewer_than_asked` explains it. Ask again for more, or narrow the filters.
* **Size needs two sources to be charged.** With a size filter, a company whose size is confirmed by only one source is delivered with `size_check: "single"` and `charged: false`.
* **People follow the same rules as [Find](https://docs-agentic-id.icustomer.ai/products/find.md).** A person is delivered only with an email that passed verification, and only if the candidate came with a full name or a profile link.
* **Long calls.** A large search can take minutes. Set your client timeout to match and send an `Idempotency-Key`.


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