Enrich Contacts with Emails and Phone Numbers

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

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.

Single contact
Batch

Pass one identifier object with one of the supported identity fields.

{
  "identifier": {
    "linkedin_url": "https://www.linkedin.com/in/jordan-rivera"
  },
  "fields": ["contact.email", "contact.phone"]
}

Pass an identifiers array with up to 100 identity objects. Batch requests are queued and return an operation to poll.

{
  "identifiers": [
    { "linkedin_url": "https://www.linkedin.com/in/jordan-rivera" },
    { "email": "alex@example.com" },
    { "x_handle": "alex_sales" }
  ],
  "fields": ["contact.email", "signals"]
}

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

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"]
  }'

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
    }
  }'

curl https://developer.thehog.ai/api/enrichments/op_01hxyz \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"

Responses

Sync enrichment (HTTP 200)

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

{
  "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.

{
  "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.

{
  "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

Get Started

Core Concepts

Guides

Reference

Enrich Contacts with Emails and Phone Numbers

Endpoint overview

Enrichment request

Input modes

Request fields

PersonIdentifier fields

Examples

Responses

Sync enrichment (HTTP 200)

Async completed result

Async accepted (HTTP 202)

Enrichment result fields

​Endpoint overview

​Enrichment request

​Input modes

​Request fields

​PersonIdentifier fields

​Examples

​Responses

​Sync enrichment (HTTP 200)

​Async completed result

​Async accepted (HTTP 202)

​Enrichment result fields

Endpoint overview

Enrichment request

Input modes

Request fields

PersonIdentifier fields

Examples

Responses

Sync enrichment (HTTP 200)

Async completed result

Async accepted (HTTP 202)

Enrichment result fields