> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thehog.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrich Contacts with Emails and Phone Numbers

> Get verified email addresses and phone numbers for your prospects. Control enrichment depth and choose sync or async delivery for bulk batches.

Contact enrichment turns a LinkedIn URL, email address, X handle, or GitHub username into verified email addresses and phone numbers. You can enrich contacts one at a time for immediate results, or submit large batches asynchronously and poll for completion.

## Endpoint overview

| Endpoint               | Method | What it does                                     |
| ---------------------- | ------ | ------------------------------------------------ |
| `/api/enrichments`     | POST   | Enrich one or more contacts with email and phone |
| `/api/enrichments/:id` | GET    | Poll the status of an async enrichment job       |

***

## Enrichment request

```text theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://developer.thehog.ai/api/enrichments
```

### Input modes

You can enrich a single person immediately or submit a batch. Use exactly one of `identifier` or `identifiers`.

<Tabs>
  <Tab title="Single contact">
    Pass one `identifier` object with one of the supported identity fields.

    ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "identifier": {
        "linkedin_url": "https://www.linkedin.com/in/jordan-rivera"
      },
      "fields": ["contact.email", "contact.phone"]
    }
    ```
  </Tab>

  <Tab title="Batch">
    Pass an `identifiers` array with up to 100 identity objects. Batch requests are queued and return an operation to poll.

    ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "identifiers": [
        { "linkedin_url": "https://www.linkedin.com/in/jordan-rivera" },
        { "email": "alex@example.com" },
        { "x_handle": "alex_sales" }
      ],
      "fields": ["contact.email", "signals"]
    }
    ```
  </Tab>
</Tabs>

### Request fields

| Field            | Type                | Default | Description                                                                          |
| ---------------- | ------------------- | ------- | ------------------------------------------------------------------------------------ |
| `identifier`     | PersonIdentifier    | —       | Single contact to enrich. Use this or `identifiers`, not both.                       |
| `identifiers`    | PersonIdentifier\[] | —       | Batch of up to 100 contacts. Use this or `identifier`, not both.                     |
| `fields`         | string\[]           | —       | Required enrichment fields, such as `contact.email`, `contact.phone`, and `signals`. |
| `signals_config` | object              | —       | Optional signal collection settings when `fields` includes `signals`.                |

### PersonIdentifier fields

Each identifier object should include one of these fields:

| Field             | Type   | Example                                     |
| ----------------- | ------ | ------------------------------------------- |
| `linkedin_url`    | string | `https://www.linkedin.com/in/jordan-rivera` |
| `email`           | string | `jordan@example.com`                        |
| `x_handle`        | string | `jordan_sales`                              |
| `github_username` | string | `jordanrivera`                              |

## Examples

<CodeGroup>
  ```bash Sync contact enrichment theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://developer.thehog.ai/api/enrichments \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "identifier": {
        "linkedin_url": "https://www.linkedin.com/in/jordan-rivera"
      },
      "fields": ["contact.email", "contact.phone"]
    }'
  ```

  ```bash Async batch enrichment theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://developer.thehog.ai/api/enrichments \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "identifiers": [
        { "linkedin_url": "https://www.linkedin.com/in/jordan-rivera" },
        { "email": "alex@example.com" },
        { "github_username": "sam-dev" }
      ],
      "fields": ["contact.email", "contact.phone", "signals"],
      "signals_config": {
        "platforms": ["linkedin", "x"],
        "since_days": 30
      }
    }'
  ```

  ```bash Poll async result theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://developer.thehog.ai/api/enrichments/op_01hxyz \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

***

## Responses

### Sync enrichment (HTTP 200)

Single LinkedIn contact requests that only ask for `contact.email` and/or `contact.phone` can complete synchronously.

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "contact": {
      "email": ["jordan@acme.com"],
      "phone": ["+14155550100"]
    }
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}
```

### Async completed result

When a batch enrichment succeeds, the poll response contains item-level statuses.

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "op_01hxyz",
  "status": "succeeded",
  "progress": 100,
  "result": {
    "items": [
      {
        "identifier": {
          "linkedin_url": "https://www.linkedin.com/in/jordan-rivera"
        },
        "status": "success",
        "data": {
          "contact": {
            "email": ["jordan@acme.com"],
            "phone": ["+14155550100"]
          }
        }
      }
    ],
    "partial": false
  },
  "error": null
}
```

### Async accepted (HTTP 202)

Batch requests and signal requests return a job reference immediately.

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "op_01hxyz",
  "operationId": "op_01hxyz",
  "status": "queued",
  "pollUrl": "/api/enrichments/op_01hxyz",
  "meta": {
    "requestId": "req_01habc"
  }
}
```

Poll `GET /api/enrichments/:id` until `status` is `"succeeded"`. The enriched records are in `result`.

## Enrichment result fields

| Field                | Type   | Description                                                 |
| -------------------- | ------ | ----------------------------------------------------------- |
| `data.contact.email` | array  | Verified email addresses when `contact.email` was requested |
| `data.contact.phone` | array  | Verified phone numbers when `contact.phone` was requested   |
| `data.signals`       | object | Signal output when `signals` was requested                  |
| `items[].identifier` | object | Original identifier for a batch item                        |
| `items[].status`     | string | `"success"` or `"failed"` for a batch item                  |
| `items[].data`       | object | Enrichment data for a successful batch item                 |
| `items[].error`      | object | Safe error message for a failed batch item                  |