- 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, or a sign-in with your iCustomer account.
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.- curl
- TypeScript
- CLI
- MCP
- Claude Code plugin
1
Set your key and server
export AGENTIC_ID_URL="https://YOUR_AGENTIC_ID_HOST"
export AGENTIC_ID_API_KEY="ic-live-..."
2
Resolve a company by domain
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
}'
{
"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"
}
id. You use it with enrich, find, facts and the ledger.3
Validate a work email
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
}'
{
"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"
}
]
}
Idempotency-Key header. See Idempotency.These steps call the REST API with Errors come back as problem details with a stable
fetch (Node.js 18 or later). For the typed client, see SDK.1
Set your key and server
export AGENTIC_ID_URL="https://YOUR_AGENTIC_ID_HOST"
export AGENTIC_ID_API_KEY="ic-live-..."
2
Add a small helper
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;
}
code. See Errors.3
Resolve a company by domain
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);
{
"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
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);
{
"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"
}
]
}
The Then either sign in with your iCustomer account:or set an API key in your environment:A key, when set, is used instead of a sign-in. Never put a key on a command line.Without
agentic-id command ships with the Claude Code plugin. See CLI for setup outside Claude Code.1
Point it at your server and get let in
export AGENTIC_ID_URL="https://YOUR_AGENTIC_ID_HOST"
agentic-id login
export AGENTIC_ID_API_KEY="ic-live-..."
2
Resolve a company by domain
agentic-id resolve --domain acme.example --max-credits 1 --json
{
"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
agentic-id validate alex.rivera@acme.example --max-credits 1 --json
{
"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"
}
]
}
--json the command prints the one-line summary and the rows that matter.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.
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):{
"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 The tool answers with the one-line summary as text and the full answer as structured content:
agentic_id_resolve with:{
"identifiers": { "company_domain": "acme.example" },
"max_credits": 1
}
{
"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:{
"email": "alex.rivera@acme.example",
"max_credits": 1
}
{
"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"
}
]
}
1
Install the plugin
claude plugin marketplace add icustomerai/agentic-id-plugin
claude plugin install agentic-id@icustomer
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:Claude calls
Resolve the company acme.example to its Agentic ID, then check whether
alex.rivera@acme.example is a real mailbox. 2 credits at most.
agentic_id_resolve and agentic_id_validate. The answers have the same shape as the REST API:{
"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"
}
{
"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"
}
]
}
Read the answer
Every paid answer has the same three fields first.quoted_credits is the most the call could have charged. charged_credits is what it did charge, never more than quoted.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 |
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
Credits
What each call charges, and how to cap it.
What is an Agentic ID
The ID format, and which identifiers resolve to it.
Verification levels
How to read
verified, corroborated and claimed.API reference
Every endpoint, field and limit.

