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

# Quickstart

> Resolve a company by its domain, then validate a work email. Five ways to make the same two calls.

You need two things before you start:

* **Your server address.** These pages write it as `https://YOUR_AGENTIC_ID_HOST`. Use the address your Agentic ID contact gave you.
* **A credential.** An [API key](https://docs-agentic-id.icustomer.ai/api-keys.md), or a [sign-in](https://docs-agentic-id.icustomer.ai/authentication.md) with your iCustomer account.

> [!NOTE]
>
> The examples use placeholder names and domains (`acme.example`, `alex.rivera@acme.example`). Replace them with a real company domain and a real work email. A placeholder domain does not resolve, and `validate` refuses addresses on `example.com` and on reserved endings such as `.example` and `.test` before any paid check, with nothing charged.

> [tab] curl
>
> **1. Set your key and server**
>
> ```bash theme={null}
> export AGENTIC_ID_URL="https://YOUR_AGENTIC_ID_HOST"
> export AGENTIC_ID_API_KEY="ic-live-..."
> ```
>
> **2. Resolve a company by domain**
>
> ```bash theme={null}
> curl -s "$AGENTIC_ID_URL/v1/resolve" \
>   -H "Authorization: Bearer $AGENTIC_ID_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "identifiers": { "company_domain": "acme.example" },
>     "max_credits": 1
>   }'
> ```
>
> ```json theme={null}
> {
>   "request_id": "5b0f6c1e-2a47-4d0b-9a57-3f0c1f6f2d11",
>   "summary": "new: an Agentic ID was created for it. 1 credit charged.",
>   "cost": { "quoted_credits": 1, "charged_credits": 1 },
>   "id": "ic-4kQ9xT2mB7nLp0Zr8VwYc3",
>   "matched_on": "domain",
>   "confidence": 1,
>   "subject": { "kind": "company", "company_domain": "acme.example" },
>   "outcome": "new"
> }
> ```
>
> Keep the `id`. You use it with enrich, find, facts and the ledger.
>
> **3. Validate a work email**
>
> ```bash theme={null}
> curl -s "$AGENTIC_ID_URL/v1/validate" \
>   -H "Authorization: Bearer $AGENTIC_ID_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "email": "alex.rivera@acme.example",
>     "max_credits": 1
>   }'
> ```
>
> ```json theme={null}
> {
>   "request_id": "9d3a7e52-61c8-4f1e-8b0a-7c2e94d1a6f0",
>   "summary": "1 email checked: 1 valid. 1 credit charged.",
>   "cost": { "quoted_credits": 1, "charged_credits": 1 },
>   "results": [
>     {
>       "email": "alex.rivera@acme.example",
>       "verdict": "valid",
>       "role": false,
>       "checked_at": "2026-11-13T10:42:07.000Z"
>     }
>   ]
> }
> ```
>
> To retry a paid call safely, add an `Idempotency-Key` header. See [Idempotency](https://docs-agentic-id.icustomer.ai/idempotency.md).

> [tab] TypeScript
>
> These steps call the REST API with `fetch` (Node.js 18 or later). For the typed client, see [SDK](https://docs-agentic-id.icustomer.ai/sdk.md).
>
> **1. Set your key and server**
>
> ```bash theme={null}
> export AGENTIC_ID_URL="https://YOUR_AGENTIC_ID_HOST"
> export AGENTIC_ID_API_KEY="ic-live-..."
> ```
>
> **2. Add a small helper**
>
> ```ts theme={null}
> const BASE = process.env.AGENTIC_ID_URL!;
> const KEY = process.env.AGENTIC_ID_API_KEY!;
>
> async function post<T>(path: string, body: unknown): Promise<T> {
>   const res = await fetch(`${BASE}${path}`, {
>     method: "POST",
>     headers: {
>       authorization: `Bearer ${KEY}`,
>       "content-type": "application/json",
>     },
>     body: JSON.stringify(body),
>   });
>   const json = await res.json();
>   if (!res.ok) throw new Error(`${json.status} ${json.code}: ${json.detail}`);
>   return json as T;
> }
> ```
>
> Errors come back as problem details with a stable `code`. See [Errors](https://docs-agentic-id.icustomer.ai/errors.md).
>
> **3. Resolve a company by domain**
>
> ```ts theme={null}
> const company = await post<{
>   request_id: string;
>   summary: string;
>   cost: { quoted_credits: number; charged_credits: number };
>   id?: string;
>   outcome: "known" | "new" | "review" | "conflict" | "unresolvable";
> }>("/v1/resolve", {
>   identifiers: { company_domain: "acme.example" },
>   max_credits: 1,
> });
>
> console.log(company.id, company.outcome, company.cost);
> ```
>
> ```json theme={null}
> {
>   "request_id": "5b0f6c1e-2a47-4d0b-9a57-3f0c1f6f2d11",
>   "summary": "new: an Agentic ID was created for it. 1 credit charged.",
>   "cost": { "quoted_credits": 1, "charged_credits": 1 },
>   "id": "ic-4kQ9xT2mB7nLp0Zr8VwYc3",
>   "matched_on": "domain",
>   "confidence": 1,
>   "subject": { "kind": "company", "company_domain": "acme.example" },
>   "outcome": "new"
> }
> ```
>
> **4. Validate a work email**
>
> ```ts theme={null}
> const check = await post<{
>   summary: string;
>   cost: { quoted_credits: number; charged_credits: number };
>   results: { email: string; verdict: string; reason?: string; role: boolean; checked_at: string }[];
> }>("/v1/validate", {
>   email: "alex.rivera@acme.example",
>   max_credits: 1,
> });
>
> console.log(check.results[0].verdict, check.cost);
> ```
>
> ```json theme={null}
> {
>   "request_id": "9d3a7e52-61c8-4f1e-8b0a-7c2e94d1a6f0",
>   "summary": "1 email checked: 1 valid. 1 credit charged.",
>   "cost": { "quoted_credits": 1, "charged_credits": 1 },
>   "results": [
>     {
>       "email": "alex.rivera@acme.example",
>       "verdict": "valid",
>       "role": false,
>       "checked_at": "2026-11-13T10:42:07.000Z"
>     }
>   ]
> }
> ```

> [tab] CLI
>
> The `agentic-id` command ships with the [Claude Code plugin](https://docs-agentic-id.icustomer.ai/claude-code-plugin.md). See [CLI](https://docs-agentic-id.icustomer.ai/cli.md) for setup outside Claude Code.
>
> **1. Point it at your server and get let in**
>
> ```bash theme={null}
> export AGENTIC_ID_URL="https://YOUR_AGENTIC_ID_HOST"
> ```
>
> Then either sign in with your iCustomer account:
>
> ```bash theme={null}
> agentic-id login
> ```
>
> or set an API key in your environment:
>
> ```bash theme={null}
> export AGENTIC_ID_API_KEY="ic-live-..."
> ```
>
> A key, when set, is used instead of a sign-in. Never put a key on a command line.
>
> **2. Resolve a company by domain**
>
> ```bash theme={null}
> agentic-id resolve --domain acme.example --max-credits 1 --json
> ```
>
> ```json theme={null}
> {
>   "request_id": "5b0f6c1e-2a47-4d0b-9a57-3f0c1f6f2d11",
>   "summary": "new: an Agentic ID was created for it. 1 credit charged.",
>   "cost": { "quoted_credits": 1, "charged_credits": 1 },
>   "id": "ic-4kQ9xT2mB7nLp0Zr8VwYc3",
>   "matched_on": "domain",
>   "confidence": 1,
>   "subject": { "kind": "company", "company_domain": "acme.example" },
>   "outcome": "new"
> }
> ```
>
> **3. Validate a work email**
>
> ```bash theme={null}
> agentic-id validate alex.rivera@acme.example --max-credits 1 --json
> ```
>
> ```json theme={null}
> {
>   "request_id": "9d3a7e52-61c8-4f1e-8b0a-7c2e94d1a6f0",
>   "summary": "1 email checked: 1 valid. 1 credit charged.",
>   "cost": { "quoted_credits": 1, "charged_credits": 1 },
>   "results": [
>     {
>       "email": "alex.rivera@acme.example",
>       "verdict": "valid",
>       "role": false,
>       "checked_at": "2026-11-13T10:42:07.000Z"
>     }
>   ]
> }
> ```
>
> Without `--json` the command prints the one-line summary and the rows that matter.

> [tab] MCP
>
> The MCP server runs on your machine over stdio and calls the API for you. It needs Node.js 18 or later and installs no packages. See [MCP server](https://docs-agentic-id.icustomer.ai/mcp-server.md).
>
> **1. Add the server to your MCP client**
>
> Point your client at `server/mcp.mjs` inside the plugin folder (`plugins/agentic-id/` in the plugin repository):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "agentic-id": {
>       "command": "node",
>       "args": ["/path/to/plugins/agentic-id/server/mcp.mjs"],
>       "env": {
>         "AGENTIC_ID_URL": "https://YOUR_AGENTIC_ID_HOST",
>         "AGENTIC_ID_API_KEY_FILE": "/path/to/a/file/that/holds/your/key"
>       }
>     }
>   }
> }
> ```
>
> `AGENTIC_ID_API_KEY_FILE` names a file that holds the key, so the key itself stays out of your config. Keep that file outside any repository, readable by you only.
>
> **2. Resolve a company by domain**
>
> Ask your agent, or call the tool `agentic_id_resolve` with:
>
> ```json theme={null}
> {
>   "identifiers": { "company_domain": "acme.example" },
>   "max_credits": 1
> }
> ```
>
> The tool answers with the one-line summary as text and the full answer as structured content:
>
> ```json theme={null}
> {
>   "request_id": "5b0f6c1e-2a47-4d0b-9a57-3f0c1f6f2d11",
>   "summary": "new: an Agentic ID was created for it. 1 credit charged.",
>   "cost": { "quoted_credits": 1, "charged_credits": 1 },
>   "id": "ic-4kQ9xT2mB7nLp0Zr8VwYc3",
>   "matched_on": "domain",
>   "confidence": 1,
>   "subject": { "kind": "company", "company_domain": "acme.example" },
>   "outcome": "new"
> }
> ```
>
> **3. Validate a work email**
>
> Call `agentic_id_validate` with:
>
> ```json theme={null}
> {
>   "email": "alex.rivera@acme.example",
>   "max_credits": 1
> }
> ```
>
> ```json theme={null}
> {
>   "request_id": "9d3a7e52-61c8-4f1e-8b0a-7c2e94d1a6f0",
>   "summary": "1 email checked: 1 valid. 1 credit charged.",
>   "cost": { "quoted_credits": 1, "charged_credits": 1 },
>   "results": [
>     {
>       "email": "alex.rivera@acme.example",
>       "verdict": "valid",
>       "role": false,
>       "checked_at": "2026-11-13T10:42:07.000Z"
>     }
>   ]
> }
> ```

> [tab] Claude Code plugin
>
> **1. Install the plugin**
>
> ```bash theme={null}
> claude plugin marketplace add icustomerai/agentic-id-plugin
> claude plugin install agentic-id@icustomer
> ```
>
> Claude Code asks for four options, all optional. Set **Agentic ID API URL** to `https://YOUR_AGENTIC_ID_HOST`. Leave **Agentic ID API key** empty to sign in with your account, or paste a key for CI and headless runs. Claude Code keeps the key in your system keychain.
>
> **2. Sign in**
>
> Type `/agentic-id-login`. Your browser opens the iCustomer sign-in page. When it says you are signed in, go back to Claude Code. Skip this step if you set an API key.
>
> **3. Check the connection**
>
> Type `/agentic-id-status`. It says which workspace you are connected as.
>
> **4. Resolve a company, then validate an email**
>
> Ask in plain words, with a budget:
>
> ```text theme={null}
> Resolve the company acme.example to its Agentic ID, then check whether
> alex.rivera@acme.example is a real mailbox. 2 credits at most.
> ```
>
> Claude calls `agentic_id_resolve` and `agentic_id_validate`. The answers have the same shape as the REST API:
>
> ```json theme={null}
> {
>   "request_id": "5b0f6c1e-2a47-4d0b-9a57-3f0c1f6f2d11",
>   "summary": "new: an Agentic ID was created for it. 1 credit charged.",
>   "cost": { "quoted_credits": 1, "charged_credits": 1 },
>   "id": "ic-4kQ9xT2mB7nLp0Zr8VwYc3",
>   "matched_on": "domain",
>   "confidence": 1,
>   "subject": { "kind": "company", "company_domain": "acme.example" },
>   "outcome": "new"
> }
> ```
>
> ```json theme={null}
> {
>   "request_id": "9d3a7e52-61c8-4f1e-8b0a-7c2e94d1a6f0",
>   "summary": "1 email checked: 1 valid. 1 credit charged.",
>   "cost": { "quoted_credits": 1, "charged_credits": 1 },
>   "results": [
>     {
>       "email": "alex.rivera@acme.example",
>       "verdict": "valid",
>       "role": false,
>       "checked_at": "2026-11-13T10:42:07.000Z"
>     }
>   ]
> }
> ```
>
> Never paste an API key into the chat. See [Claude Code plugin](https://docs-agentic-id.icustomer.ai/claude-code-plugin.md).

## Read the answer

Every paid answer has the same three fields first.

**request\_id** `string`

Quote it when you report a problem.

**summary** `string`

One plain line saying what happened and what was charged.

**cost** `object`

`quoted_credits` is the most the call could have charged. `charged_credits` is what it did charge, never more than quoted.

For `resolve`, read `outcome` before you use `id`:

| `outcome` | Meaning | `id` returned |
| - | - | - |
| `known` | Agentic ID already had this ID | Yes |
| `new` | An ID was created for it | Yes |
| `review` | A possible match needs review. Nothing was linked | No |
| `conflict` | The identifiers match more than one ID. Held for review | No |
| `unresolvable` | Not enough to resolve it. `reason` says why | No |

For `validate`, each result has a `verdict`:

| `verdict` | Meaning | Charged |
| - | - | - |
| `valid` | The mailbox accepts mail | 1 credit |
| `invalid` | The mailbox rejects mail | 1 credit |
| `catch-all` | The server accepts every address, so the mailbox is not proven | 1 credit |
| `unknown` | No answer this time. Not a verdict against the address | Not charged |
| `rejected` | Refused before any check. `reason` says why | Not charged |

## Next steps

> [card] [Credits](https://docs-agentic-id.icustomer.ai/credits.md)
>
> What each call charges, and how to cap it.

> [card] [What is an Agentic ID](https://docs-agentic-id.icustomer.ai/concepts/agentic-id.md)
>
> The ID format, and which identifiers resolve to it.

> [card] [Verification levels](https://docs-agentic-id.icustomer.ai/concepts/verification.md)
>
> How to read `verified`, `corroborated` and `claimed`.

> [card] [API reference](https://docs-agentic-id.icustomer.ai/api-reference/introduction.md)
>
> Every endpoint, field and limit.


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