# Search and Enrich Contacts

Find decision makers and influencers at companies you care about, then enrich them with email and phone to reach out.

## How It Works

Contacts follow a two-step workflow, similar to [Search or Match Companies](/v2/guides/find-companies):

1. **Search** — Find contacts by company, job function, seniority, location, or time in role. Returns contact IDs and firmographic/role details, but no email or phone.
2. **Enrich** — Pass contact IDs from search to get email and phone.


Search doesn't consume credits. Enrich does, based on the fields you request.

## Search Contacts

```
POST /data-api/v2/contacts/search
```

### Request

```json
{
  "filters": {
    "companies": {
      "ids": ["1698C53EBC888758570396E0334965C1"]
    },
    "contact_location": {
      "countries": ["US"]
    },
    "job_functions": ["Engineering"],
    "job_seniority": ["Director"],
    "time_in_current_role": ["company_veteran"]
  },
  "limit": 10,
  "offset": 0
}
```

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `filters` | object | Yes | Filter criteria (see below) |
| `limit` | integer | No | Max contacts to return (1-20, default 10) |
| `offset` | integer | No | Contacts to skip for pagination (max 99, default 0) |


### Filters

All filters are inclusion-only and combine with AND logic.

| Filter | Description |
|  --- | --- |
| `companies.ids` | HG company IDs. Either `ids` or `domains`, not both. |
| `companies.domains` | Company domains. Either `ids` or `domains`, not both. |
| `contact_location.countries` | ISO 3166-1 alpha-2 country codes |
| `job_functions` | Job function names, e.g. `Engineering`, `Operations` |
| `job_seniority` | Job seniority names, e.g. `Director`, `Founder` |
| `time_in_current_role` | One or more of `new_change_maker` (< 6 months), `rising_contributor` (6mo-1yr), `established_performer` (1-2yr), `stable_operator` (3-5yr), `company_veteran` (5+ years) |


### Response

```json
{
  "contacts": [
    {
      "id": "7a932d2ae5dab0ca88348198c9129c9167ff34f92c4abd47f291f5d1c35d237a",
      "full_name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "job_title": "Co-Founder",
      "job_functions": ["Operations"],
      "job_seniority": "Founder",
      "company_id": "1488903ED478F8C51D09F2EC5F2DCDA2",
      "company_name": "Acme",
      "company_domain": "acme.com",
      "contact_location_city": "Vancouver",
      "contact_location_region": "British Columbia",
      "contact_location_country": "Canada",
      "linkedin_url": "https://www.linkedin.com/in/john-dow"
    }
  ],
  "count": 1
}
```

`count` is the total number of matching contacts before pagination. Use `id` from each result to enrich the contact in the next step.

## Enrich Contacts

Get email and phone for contacts by ID. Accepts up to 20 IDs per request.

```
POST /data-api/v2/contacts/enrich
```

### Request

```json
{
  "ids": [
    "820b11e9bff6183dbefdf3d29c16202f85fe366f7569d0ca0ddfc7e10d372451",
    "5f09a1f4b151848e12aa9fbfa1884ea0e5b6a35a6bb280ca88049529c6ecfbd4"
  ],
  "fields": ["email", "phone"]
}
```

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `ids` | array | Yes | Contact IDs to enrich (max 20) |
| `fields` | array | Yes | `email`, `phone`, or both |


### Response

```json
{
  "contacts": [
    {
      "id": "820b11e9bff6183dbefdf3d29c16202f85fe366f7569d0ca0ddfc7e10d372451",
      "full_name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "email_status": "Unverified",
      "phone": "+15550000000",
      "company_id": "02F00022696877390B077DE05D7918CA",
      "company_name": "AppNexus",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe-820b11e9",
      "status": "enriched"
    },
    {
      "id": "5f09a1f4b151848e12aa9fbfa1884ea0e5b6a35a6bb280ca88049529c6ecfbd4",
      "company_id": "02F00022696877390B077DE05D7918CA",
      "company_name": "AppNexus",
      "status": "not_found"
    }
  ]
}
```

Each result includes a `status`:

| Status | Meaning |
|  --- | --- |
| `enriched` | Contact found — email/phone included for the fields you requested |
| `not_found` | Contact ID doesn't exist |
| `missing_pii` | Contact exists but the requested PII isn't available |


Only enriched contacts are charged credits — `not_found` and `missing_pii` results are free.

## Preview Credit Cost

Before enriching, preview the cost with the same request body:

```
POST /data-api/v2/contacts/enrich/estimate
```

No credits are consumed and no data is returned — just the estimated cost. See [Credits and Usage](/v2/guides/credits-and-usage#estimating-cost-before-you-call) for the general estimate response shape.

## Common Workflow

Find engineering directors at a target account, then get their contact info:

```json
// 1. Search for engineering directors at a company
{
  "filters": {
    "companies": {"ids": ["1698C53EBC888758570396E0334965C1"]},
    "job_functions": ["Engineering"],
    "job_seniority": ["Director"]
  },
  "limit": 20
}
```

```json
// 2. Enrich the returned contact IDs with email and phone
{
  "ids": ["7a932d2ae5dab0ca88348198c9129c9167ff34f92c4abd47f291f5d1c35d237a"],
  "fields": ["email", "phone"]
}
```