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

# Resolve

> Get one stable Agentic ID for a person or a company.

`POST /v1/resolve` answers one question: which Agentic ID does this record belong to? Send what you know about one person or one company and get back its ID, how it was matched, and what the call cost. Use it to key your own records, to remove duplicates before you spend on other calls, and to get the ID that [Feedback](https://docs-agentic-id.icustomer.ai/products/feedback.md) and [Find](https://docs-agentic-id.icustomer.ai/products/find.md) accept.

```bash curl theme={null}
curl -X POST https://YOUR_AGENTIC_ID_HOST/v1/resolve \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b6f3c1e-7a52-4d0e-9a55-2f1c8e4d9b10" \
  -d '{
    "identifiers": { "company_domain": "acme.example" },
    "max_credits": 1
  }'
```

```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.resolve({
  identifiers: { company_domain: 'acme.example' },
  max_credits: 1,
});
console.log(reply.id, reply.outcome);
```

```bash CLI theme={null}
agentic-id resolve --domain acme.example --max-credits 1
```

```json 200 theme={null}
{
  "request_id": "req_5d0c1b9e-2f4a-4a7b-8c3d-6e1f0a9b7c21",
  "summary": "Agentic ID already had this ID; it is new to your workspace. 1 credit charged.",
  "cost": { "quoted_credits": 1, "charged_credits": 1 },
  "id": "ic-7Kq2mXv9RtB4nWc8Zp1LdE",
  "matched_on": "domain",
  "confidence": 1,
  "subject": { "kind": "company", "company_domain": "acme.example" },
  "outcome": "known"
}
```

> [!NOTE]
>
> The domains on this page are reserved for documentation. Use a real record to see a match.

## Request

**identifiers** `object` *required*

What you know about the record. Every field is optional; send as many as you have.

**properties**

**email** `string`

The person's email. Up to 320 characters.

**linkedin\_url** `string`

The person's profile link. Up to 500 characters.

**name** `string`

The person's full name. Used as a hint next to an email, a profile link or a company. Up to 200 characters.

**company\_name** `string`

The company's name. A hint, not an identifier. Up to 200 characters.

**company\_domain** `string`

The company's website domain. For a company, this is the identifier. For a person, it is a hint about the employer. Up to 253 characters.

**kind** `string`

`person` or `company`. When omitted it is inferred: a person if `email`, `linkedin_url` or `name` is sent, otherwise a company.

**spend** `boolean` (default: false)

When `true`, paid sources are asked if Agentic ID's own records cannot resolve the record. Applies to people only. See [Behaviour](#behaviour).

**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 saying what happened and what was charged.

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

**outcome** `string` *required*

One of:

| Value | Meaning |
| - | - |
| `known` | An Agentic ID already existed for this record. |
| `new` | An Agentic ID was created for it. |
| `review` | A possible match needs review. Nothing was linked. |
| `conflict` | The record matches more than one ID. It is held for review. |
| `unresolvable` | Not enough to resolve it. |

**id** `string`

The Agentic ID. Present for `known` and `new` when the call was allowed to charge for it.

**matched\_on** `string`

What the match was made on, for example `work_email`, `linkedin`, `domain`, or `source` when a paid source resolved it.

**confidence** `number`

Confidence of the link, from 0 to 1.

**reason** `string`

Why the outcome is what it is, when there is something to say.

**subject** `object`

What the ID stands for, as far as the request said. Present when `id` is present. A person is never described here.

**properties**

**kind** `string` *required*

`person` or `company`.

**company\_domain** `string`

For a company, the domain it was resolved from.

**related** `object[]`

Companies that may belong with this one, such as a regional site or a brand. Linked for review, never merged.

**properties**

**id** `string` *required*

The related company's Agentic ID.

**reason** `string` *required*

`same_name_other_domain` or `redirects_to`.

## What it costs

| Result | Credits |
| - | - |
| `known` or `new` | 1 |
| `known`, for an ID your workspace already holds, while your workspace contributes | 0 |
| `review`, `conflict`, `unresolvable` | 0 |

* `quoted_credits` is 1, or `max_credits` if that is lower.
* If `max_credits` is reached, the ID is withheld, `reason` says so, and nothing is charged.
* A record resolved through a paid source (`spend: true`) is charged at the same rate.

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. `issues` lists each problem. | No. Fix the body. |
| 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 | `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

* **One record per call.** Send one person or one company.
* **`spend` is off by default.** Without it, only Agentic ID's own records are used. With `spend: true`, a person that comes back `unresolvable` is looked up in paid sources. Companies are not looked up this way: they resolve by domain.
* **People and companies use different fields.** A person is identified by `email` or `linkedin_url`; `name`, `company_name` and `company_domain` are hints. A company is identified by `company_domain`; `company_name` is a hint.
* **Ambiguous records are not linked.** `review` and `conflict` return no ID and no charge.
* **IDs your workspace holds.** A resolved ID is held by your workspace. [Feedback](https://docs-agentic-id.icustomer.ai/products/feedback.md) and the facts and ledger endpoints accept only IDs your workspace holds.


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