Enrichment

The enrichment endpoints let you look up person and company data instantly, run async waterfall enrichment across multiple providers, and verify email deliverability.

---

Person Lookup

POST /enrichment/lookup/person

Instant person lookup. Provide at least one of: email, linkedin_url, or first_name + last_name + company_domain.

Request Body

Field	Type	Required	Description
email	string	No*	Work email address
linkedin_url	string	No*	LinkedIn profile URL
first_name	string	No*	First name (requires last_name + company_domain)
last_name	string	No*	Last name (requires first_name + company_domain)
company_domain	string	No*	Company domain (requires first_name + last_name)

*At least one lookup strategy is required.

Example

cURL

curl -X POST "https://be.graph8.com/api/v1/enrichment/lookup/person" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@acme.com"}'

Python

response = requests.post(
    f"{BASE_URL}/enrichment/lookup/person",
    headers=HEADERS,
    json={"email": "jane@acme.com"}
)

Response

{
  "data": {
    "found": true,
    "confidence": 0.95,
    "data": {
      "first_name": "Jane",
      "last_name": "Doe",
      "job_title": "VP of Sales",
      "company": "Acme Inc",
      "linkedin_url": "https://linkedin.com/in/janedoe",
      "work_email": "jane@acme.com"
    }
  }
}

---

Company Lookup

POST /enrichment/lookup/company

Instant company lookup by domain or name.

Request Body

Field	Type	Required	Description
domain	string	No*	Company domain
name	string	No*	Company name

*At least one of domain or name is required.

Example

cURL

curl -X POST "https://be.graph8.com/api/v1/enrichment/lookup/company" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.com"}'

Python

response = requests.post(
    f"{BASE_URL}/enrichment/lookup/company",
    headers=HEADERS,
    json={"domain": "acme.com"}
)

Response

{
  "data": {
    "found": true,
    "confidence": 0.98,
    "data": {
      "name": "Acme Inc",
      "domain": "acme.com",
      "industry": "Technology",
      "employee_count": 500,
      "annual_revenue": "$50M-$100M"
    }
  }
}

---

Start Enrichment Job

POST /enrichment/enrich

Start an async waterfall enrichment job. The job runs across multiple data providers and returns a job_id you can poll for results.

Returns 202 Accepted.

Request Body

Field	Type	Required	Description
contact_ids	integer[]	Yes	Contact IDs to enrich
list_id	integer	Yes	List ID the contacts belong to
fields_config	object	No	Fields to enrich and provider order (see below)

fields_config example:

{
  "work_email": ["prospeo", "dropcontact"],
  "direct_phone": ["cognism", "lusha"]
}

If omitted, defaults to {"work_email": ["prospeo", "dropcontact"]}.

Example

cURL

curl -X POST "https://be.graph8.com/api/v1/enrichment/enrich" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [101, 102, 103],
    "list_id": 5,
    "fields_config": {"work_email": ["prospeo", "dropcontact"]}
  }'

Python

response = requests.post(
    f"{BASE_URL}/enrichment/enrich",
    headers=HEADERS,
    json={
        "contact_ids": [101, 102, 103],
        "list_id": 5,
        "fields_config": {"work_email": ["prospeo", "dropcontact"]}
    }
)
job_id = response.json()["data"]["job_id"]

Response

{
  "data": {
    "job_id": "abc-123-def",
    "status": "queued"
  }
}

---

Poll Enrichment Job

GET /enrichment/jobs/{job_id}

Check the status of an enrichment job.

Status Values

Status	Description
queued	Job is waiting to start
running	Enrichment in progress
completed	All contacts processed
failed	Job failed

Example

cURL

curl "https://be.graph8.com/api/v1/enrichment/jobs/abc-123-def" \
  -H "Authorization: Bearer $API_KEY"

Python

response = requests.get(
    f"{BASE_URL}/enrichment/jobs/{job_id}",
    headers=HEADERS
)
status = response.json()["data"]["status"]

Response

{
  "data": {
    "job_id": "abc-123-def",
    "status": "completed"
  }
}

---

Verify Email

POST /enrichment/verify-email

Verify a single email address and check its deliverability status.

Request Body

Field	Type	Required	Description
email	string	Yes	Email address to verify

Example

cURL

curl -X POST "https://be.graph8.com/api/v1/enrichment/verify-email" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@acme.com"}'

Python

response = requests.post(
    f"{BASE_URL}/enrichment/verify-email",
    headers=HEADERS,
    json={"email": "jane@acme.com"}
)

Response

{
  "data": {
    "email": "jane@acme.com",
    "status": "valid",
    "sub_status": null,
    "is_valid": true
  }
}

Status	Description
valid	Deliverable email address
invalid	Undeliverable
catch-all	Domain accepts all addresses
unknown	Could not determine