Skip to main content
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

EndpointMethodWhat it does
/api/enrichmentsPOSTEnrich one or more contacts with email and phone
/api/enrichments/:idGETPoll 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.
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"]
}

​
Request fields

FieldTypeDefaultDescription
identifierPersonIdentifier—Single contact to enrich. Use this or identifiers, not both.
identifiersPersonIdentifier[]—Batch of up to 100 contacts. Use this or identifier, not both.
fieldsstring[]—Required enrichment fields, such as contact.email, contact.phone, and signals.
signals_configobject—Optional signal collection settings when fields includes signals.

​
PersonIdentifier fields

Each identifier object should include one of these fields:
FieldTypeExample
linkedin_urlstringhttps://www.linkedin.com/in/jordan-rivera
emailstringjordan@example.com
x_handlestringjordan_sales
github_usernamestringjordanrivera

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

​
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

FieldTypeDescription
data.contact.emailarrayVerified email addresses when contact.email was requested
data.contact.phonearrayVerified phone numbers when contact.phone was requested
data.signalsobjectSignal output when signals was requested
items[].identifierobjectOriginal identifier for a batch item
items[].statusstring"success" or "failed" for a batch item
items[].dataobjectEnrichment data for a successful batch item
items[].errorobjectSafe error message for a failed batch item