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

# Enrich

> Fill in missing facts about people and companies, each with its level and source.

`POST /v1/enrich` answers: what else is known about this person or company? Send the identifiers you have and get back the missing fields. Every field carries a level (how sure Agentic ID is) and the source it came from. Use it when you have a record and need more on it. To find new people, use [Find](https://docs-agentic-id.icustomer.ai/products/find.md) or [Discover](https://docs-agentic-id.icustomer.ai/products/discover.md).

```bash curl theme={null}
curl -X POST https://YOUR_AGENTIC_ID_HOST/v1/enrich \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9c2d7f10-5e3a-4b8c-a6d1-4f0e2b7c9a35" \
  -d '{
    "contact": { "name": "Alex Rivera", "company_domain": "acme.example" },
    "fields": ["work_email", "title"],
    "max_credits": 2
  }'
```

```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.enrich({
  contact: { name: 'Alex Rivera', company_domain: 'acme.example' },
  fields: ['work_email', 'title'],
  max_credits: 2,
});
for (const f of reply.results[0].fields) console.log(f.field, f.value, f.level);
```

```bash CLI theme={null}
agentic-id enrich --name "Alex Rivera" --domain acme.example --fields work_email,title --max-credits 2
```

```json 200 theme={null}
{
  "request_id": "req_2b7e4d91-6c0a-4f3b-b8e5-1a9d3c5f7e02",
  "summary": "1 of 1 record enriched. 2 credits charged.",
  "cost": { "quoted_credits": 2, "charged_credits": 2 },
  "results": [
    {
      "id": "ic-4Hn8sPq1VxC6yTb3Ku9MwR",
      "status": "outreach_ready",
      "reason": "Found by name + company domain; email verified and the name confirmed.",
      "fields": [
        {
          "field": "work_email",
          "value": "a******@acme.example",
          "level": "verified",
          "source": "agentic-id",
          "observed_at": "2026-11-13T09:30:00.000Z"
        },
        {
          "field": "title",
          "value": "VP Marketing",
          "level": "corroborated",
          "source": "agentic-id",
          "observed_at": "2026-11-13T09:30:00.000Z"
        }
      ]
    }
  ]
}
```

> [!NOTE]
>
> Contact values are returned masked today. An email keeps its first character and its domain (`a******@acme.example`), a phone keeps its last four digits (`+*******0123`), and a profile link keeps the first two characters of its handle.

## Request

Send at least one of `contact`, `contacts` or `company`.

**contact** `object`

One person. Same fields as each entry of `contacts`.

**contacts** `object[]`

Up to 100 people. Every field is optional; send what 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. Up to 200 characters.

**company\_name** `string`

The employer's name. Up to 200 characters.

**company\_domain** `string`

The employer's website domain. Up to 253 characters.

**company** `object`

One company.

**properties**

**domain** `string`

The company's website domain.

**name** `string`

The company's name.

**fields** `string[]`

Return only these fields. Applies to every record in the request; a name that does not exist for a record's kind is ignored.

* Person fields: `work_email`, `linkedin_url`, `title`, `seniority`, `company_name`, `company_domain`, `country`, `city`, `mobile_phone`.
* Company fields: `name`, `domain`, `industry`, `employees`, `country`, `description`.
* Accepted aliases: `email` (`work_email`), `job_title` (`title`), `company` (`company_name`), `linkedin` (`linkedin_url`), `phone` and `mobile` (`mobile_phone`).

When omitted, a person gets `work_email`, `linkedin_url`, `title`, `seniority`, `company_name`, `company_domain` and `country`; a company gets all six company fields. `mobile_phone` and `city` are returned only when asked for.

**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 records were enriched 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.

**results** `object[]` *required*

One entry per record, in request order: `contact` first, then `contacts`, then `company`.

**properties**

**id** `string`

The record's Agentic ID, when one is known.

**status** `string` *required*

| Value | Meaning |
| - | - |
| `outreach_ready` | Enriched, with a verified work email and a confirmed name. |
| `enriched` | At least one field was delivered. |
| `held` | Something was found but not verified, so it is held back. |
| `not_found` | Nothing trustworthy to deliver. |
| `skipped` | Not looked up: the input was not enough, or it was searched recently with no result. |
| `rejected` | What was found contradicts the input. |

**reason** `string` *required*

A plain sentence explaining the status.

**fields** `object[]` *required*

The delivered fields. Empty unless the status is `outreach_ready` or `enriched`.

**properties**

**field** `string` *required*

The field name, for example `work_email` or `title`.

**value** `any` *required*

The value. Contact values (emails, phones, profile links) are masked.

**level** `string` *required*

`verified`, `corroborated`, `claimed`, `contradicted` or `unknown`. See [Verification](https://docs-agentic-id.icustomer.ai/concepts/verification.md).

**source** `string` *required*

Where the value came from. `agentic-id` when it was served from Agentic ID's own verified records; otherwise a label for the source that supplied it.

**observed\_at** `string`

When the value was observed, ISO 8601.

## What it costs

| Result | Credits |
| - | - |
| A person with at least one field delivered | 2 |
| A person with a phone delivered | 2 + 5 |
| A company with at least one field delivered | 1 |
| A record with nothing delivered (`held`, `not_found`, `skipped`, `rejected`) | 0 |

* The charge is per record, not per field.
* `quoted_credits` is 2 per person plus 1 for the company, or `max_credits` if that is lower. It is never below what was charged.
* `max_credits` is required. A record whose price does not fit under what is left is returned with no fields and is not charged.
* If your balance covers only part of the request, the part it covers is delivered.

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 none of `contact`, `contacts`, `company` was sent. | 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

* **Batch limit.** Up to 100 people in `contacts`, plus one in `contact`, plus one `company`, in one call.
* **Match results by position.** Results carry no row key. They come back in request order.
* **Only values that pass are delivered.** A value with a single source is delivered as `claimed`. An unverified email, phone or profile link is held back, and the record's status is `held`.
* **Phones cost more.** `mobile_phone` is returned only when you ask for it in `fields`.
* **The CLI enriches one person per call.** Use the API or SDK for batches and for companies.


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