Examples

Examples & Use Cases

These examples demonstrate common workflows with the GraphADV enrichment API.

export BASE_URL="https://api.graphadv.com/v2"
export GRAPHADV_API_KEY="YOUR_API_KEY"

Enrich a Company and Poll for Results

The most common workflow: enrich a company, wait for completion, and retrieve the result.

cURL

# 1. Start enrichment
TASK_ID=$(curl -s -X POST "$BASE_URL/enrich/company" \
  -H "X-Api-Key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "notion.so"}' | jq -r '.task_id')

echo "Job ID: $TASK_ID"

# 2. Poll until complete
while true; do
  STATUS=$(curl -s "$BASE_URL/jobs/$TASK_ID" \
    -H "X-Api-Key: $GRAPHADV_API_KEY" | jq -r '.status')

  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ]; then
    # 3. Get result
    curl -s "$BASE_URL/jobs/$TASK_ID/result" \
      -H "X-Api-Key: $GRAPHADV_API_KEY" | jq
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Job failed"
    break
  fi

  sleep 2
done

Python

import os
import time
import requests

BASE_URL = os.getenv("BASE_URL", "https://api.graphadv.com/v2")
API_KEY = os.getenv("GRAPHADV_API_KEY")
headers = {"X-Api-Key": API_KEY, "Content-Type": "application/json"}

# 1. Start enrichment
job = requests.post(
    f"{BASE_URL}/enrich/company",
    headers=headers,
    json={"domain": "notion.so"}
).json()

print(f"Job ID: {job['task_id']}, Units charged: {job['units_charged']}")

# 2. Poll until complete
while True:
    status = requests.get(
        f"{BASE_URL}/jobs/{job['task_id']}",
        headers=headers
    ).json()

    print(f"Status: {status['status']}")

    if status["status"] == "completed":
        # 3. Get result
        result = requests.get(
            f"{BASE_URL}/jobs/{job['task_id']}/result",
            headers=headers
        ).json()
        print(f"Enriched: {result['name']} ({result['industry']})")
        break
    elif status["status"] == "failed":
        print(f"Failed: {status.get('error')}")
        break

    time.sleep(2)

JavaScript

const BASE_URL = process.env.BASE_URL ?? 'https://api.graphadv.com/v2';
const API_KEY = process.env.GRAPHADV_API_KEY;

async function enrichCompany(domain) {
  // 1. Start enrichment
  const job = await fetch(`${BASE_URL}/enrich/company`, {
    method: 'POST',
    headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ domain })
  }).then(r => r.json());

  console.log(`Job ID: ${job.task_id}, Units charged: ${job.units_charged}`);

  // 2. Poll until complete
  while (true) {
    const status = await fetch(`${BASE_URL}/jobs/${job.task_id}`, {
      headers: { 'X-Api-Key': API_KEY }
    }).then(r => r.json());

    console.log(`Status: ${status.status}`);

    if (status.status === 'completed') {
      // 3. Get result
      const result = await fetch(`${BASE_URL}/jobs/${job.task_id}/result`, {
        headers: { 'X-Api-Key': API_KEY }
      }).then(r => r.json());

      return result;
    } else if (status.status === 'failed') {
      throw new Error(status.error);
    }

    await new Promise(r => setTimeout(r, 2000));
  }
}

const company = await enrichCompany('notion.so');
console.log(`Enriched: ${company.name} (${company.industry})`);

Find Decision-Makers at Target Accounts

Enrich a company, then get its leadership team with verified contact info.

cURL

# Get leadership for a company (assumes company is already enriched)
curl "$BASE_URL/companies/stripe.com/persons" \
  -H "X-Api-Key: $GRAPHADV_API_KEY" | jq '.data[] | {name: .full_name, title: .title, email: .email}'

Python

# Get leadership for an enriched company
leadership = requests.get(
    f"{BASE_URL}/companies/stripe.com/persons",
    headers=headers
).json()["data"]

for person in leadership:
    print(f"{person['full_name']} - {person['title']}")
    print(f"  Email: {person.get('email', 'N/A')}")
    print(f"  LinkedIn: {person.get('linkedin_url', 'N/A')}")

JavaScript

// Get leadership for an enriched company
const { data: leadership } = await fetch(`${BASE_URL}/companies/stripe.com/persons`, {
  headers: { 'X-Api-Key': API_KEY }
}).then(r => r.json());

leadership.forEach(person => {
  console.log(`${person.full_name} - ${person.title}`);
  console.log(`  Email: ${person.email ?? 'N/A'}`);
  console.log(`  LinkedIn: ${person.linkedin_url ?? 'N/A'}`);
});

Build and Enrich a Target Account List

Create a TAL, add companies, and enrich them in bulk.

cURL

CLIENT_ID="my-client-id"

# 1. Add companies to TAL (free)
curl -X POST "$BASE_URL/clients/$CLIENT_ID/tal/companies" \
  -H "X-Api-Key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["stripe.com", "notion.so", "figma.com", "linear.app", "vercel.com"],
    "source": "manual"
  }'

# 2. Enrich the entire TAL
curl -X POST "$BASE_URL/clients/$CLIENT_ID/tal/enrich" \
  -H "X-Api-Key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_age_days": 30}'

Python

CLIENT_ID = "my-client-id"
target_companies = ["stripe.com", "notion.so", "figma.com", "linear.app", "vercel.com"]

# 1. Add companies to TAL (free)
requests.post(
    f"{BASE_URL}/clients/{CLIENT_ID}/tal/companies",
    headers=headers,
    json={"domains": target_companies, "source": "manual"}
)

print(f"Added {len(target_companies)} companies to TAL")

# 2. Enrich the entire TAL
job = requests.post(
    f"{BASE_URL}/clients/{CLIENT_ID}/tal/enrich",
    headers=headers,
    json={"max_age_days": 30}
).json()

print(f"Enrichment job started: {job['task_id']}")
print(f"Units charged: {job['units_charged']}")

JavaScript

const CLIENT_ID = 'my-client-id';
const targetCompanies = ['stripe.com', 'notion.so', 'figma.com', 'linear.app', 'vercel.com'];

// 1. Add companies to TAL (free)
await fetch(`${BASE_URL}/clients/${CLIENT_ID}/tal/companies`, {
  method: 'POST',
  headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ domains: targetCompanies, source: 'manual' })
});

console.log(`Added ${targetCompanies.length} companies to TAL`);

// 2. Enrich the entire TAL
const job = await fetch(`${BASE_URL}/clients/${CLIENT_ID}/tal/enrich`, {
  method: 'POST',
  headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ max_age_days: 30 })
}).then(r => r.json());

console.log(`Enrichment job started: ${job.task_id}`);
console.log(`Units charged: ${job.units_charged}`);

Enrich CRM Contacts with Verified Emails

Enrich a list of people by email to get verified contact info.

cURL

# Batch enrich multiple people
curl -X POST "$BASE_URL/enrich/batch" \
  -H "X-Api-Key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "john@acme.com",
      "jane@example.com",
      "bob@startup.io"
    ]
  }'

Python

crm_contacts = [
    "john@acme.com",
    "jane@example.com",
    "bob@startup.io"
]

# Batch enrich all contacts
job = requests.post(
    f"{BASE_URL}/enrich/batch",
    headers=headers,
    json={"emails": crm_contacts}
).json()

print(f"Enriching {len(crm_contacts)} contacts")
print(f"Units charged: {job['units_charged']}")

# Poll and get results (see polling example above)

JavaScript

const crmContacts = [
  'john@acme.com',
  'jane@example.com',
  'bob@startup.io'
];

// Batch enrich all contacts
const job = await fetch(`${BASE_URL}/enrich/batch`, {
  method: 'POST',
  headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ emails: crmContacts })
}).then(r => r.json());

console.log(`Enriching ${crmContacts.length} contacts`);
console.log(`Units charged: ${job.units_charged}`);

// Poll and get results (see polling example above)

Check Your Usage

Monitor your unit balance and plan status.

cURL

curl "$BASE_URL/usage" \
  -H "X-Api-Key: $GRAPHADV_API_KEY" | jq

Python

usage = requests.get(
    f"{BASE_URL}/usage",
    headers=headers
).json()

print(f"Plan: {usage['plan']}")
print(f"Units remaining: {usage['units_remaining']}")
print(f"Units used this period: {usage['units_used_this_period']}")
print(f"Period ends: {usage['period_ends_at']}")

JavaScript

const usage = await fetch(`${BASE_URL}/usage`, {
  headers: { 'X-Api-Key': API_KEY }
}).then(r => r.json());

console.log(`Plan: ${usage.plan}`);
console.log(`Units remaining: ${usage.units_remaining}`);
console.log(`Units used this period: ${usage.units_used_this_period}`);
console.log(`Period ends: ${usage.period_ends_at}`);

Enrich a Person by LinkedIn URL

When you have a LinkedIn URL but not an email.

cURL

curl -X POST "$BASE_URL/enrich/person" \
  -H "X-Api-Key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkedin_url": "https://linkedin.com/in/patrickcollison"}'

Python

job = requests.post(
    f"{BASE_URL}/enrich/person",
    headers=headers,
    json={"linkedin_url": "https://linkedin.com/in/patrickcollison"}
).json()

print(f"Job ID: {job['task_id']}")
# Poll for result to get verified email, title, company, etc.

JavaScript

const job = await fetch(`${BASE_URL}/enrich/person`, {
  method: 'POST',
  headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ linkedin_url: 'https://linkedin.com/in/patrickcollison' })
}).then(r => r.json());

console.log(`Job ID: ${job.task_id}`);
// Poll for result to get verified email, title, company, etc.

Search for Executives at Target Companies (v2)

Find decision-makers using the v2 person search endpoint.

cURL

# Find all C-level executives at Stripe
curl "$BASE_URL/v2/persons?company_domain=stripe.com&seniority=executive" \
  -H "X-Api-Key: $GRAPHADV_API_KEY"

# Search for CTOs across all companies
curl "$BASE_URL/v2/persons?title=cto&seniority=executive&limit=20" \
  -H "X-Api-Key: $GRAPHADV_API_KEY"

# Find people by name
curl "$BASE_URL/v2/persons?query=john&include=contact,profile" \
  -H "X-Api-Key: $GRAPHADV_API_KEY"

Python

# Find all C-level executives at Stripe
executives = requests.get(
    f"{BASE_URL}/v2/persons",
    headers=headers,
    params={"company_domain": "stripe.com", "seniority": "executive"}
).json()["persons"]

for exec in executives:
    print(f"{exec['full_name']} - {exec['title']}")
    print(f"  Email: {exec.get('email', 'N/A')}")

# Search for CTOs across all companies
ctos = requests.get(
    f"{BASE_URL}/v2/persons",
    headers=headers,
    params={"title": "cto", "seniority": "executive", "limit": 20}
).json()["persons"]

JavaScript

// Find all C-level executives at Stripe
const params = new URLSearchParams({
  company_domain: 'stripe.com',
  seniority: 'executive'
});
const { persons: executives } = await fetch(`${BASE_URL}/v2/persons?${params}`, {
  headers: { 'X-Api-Key': API_KEY }
}).then(r => r.json());

executives.forEach(exec => {
  console.log(`${exec.full_name} - ${exec.title}`);
  console.log(`  Email: ${exec.email ?? 'N/A'}`);
});

Discover Leadership Team for Outreach (v2)

Use the leadership discovery endpoint to find and enrich an entire leadership team.

cURL

# Discover leadership at a single company (5 units)
curl -X POST "$BASE_URL/v2/search/leadership" \
  -H "X-Api-Key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["stripe.com"],
    "max_per_company": 10
  }'

# Get job ID, then poll for results
TASK_ID="..." # From response
curl "$BASE_URL/v2/tasks/$TASK_ID/result" \
  -H "X-Api-Key: $GRAPHADV_API_KEY"

Python

# Discover leadership at target companies
job = requests.post(
    f"{BASE_URL}/v2/search/leadership",
    headers=headers,
    json={
        "domains": ["stripe.com", "notion.so", "figma.com"],
        "max_per_company": 10
    }
).json()

print(f"Job ID: {job['task_id']}, Units charged: {job['units_charged']}")

# Poll for completion
while True:
    status = requests.get(
        f"{BASE_URL}/v2/tasks/{job['task_id']}",
        headers=headers
    ).json()

    if status["status"] == "completed":
        result = requests.get(
            f"{BASE_URL}/v2/tasks/{job['task_id']}/result",
            headers=headers
        ).json()

        for company in result["companies"]:
            print(f"\n{company['domain']} leadership:")
            for person in company["persons"]:
                print(f"  {person['full_name']} - {person['title']}")
                print(f"    Email: {person.get('email', 'N/A')}")
        break

    time.sleep(2)

JavaScript

// Discover leadership at target companies
const job = await fetch(`${BASE_URL}/v2/search/leadership`, {
  method: 'POST',
  headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    domains: ['stripe.com', 'notion.so', 'figma.com'],
    max_per_company: 10
  })
}).then(r => r.json());

console.log(`Job ID: ${job.task_id}, Units charged: ${job.units_charged}`);

// Poll for completion
while (true) {
  const status = await fetch(`${BASE_URL}/v2/tasks/${job.task_id}`, {
    headers: { 'X-Api-Key': API_KEY }
  }).then(r => r.json());

  if (status.status === 'completed') {
    const result = await fetch(`${BASE_URL}/v2/tasks/${job.task_id}/result`, {
      headers: { 'X-Api-Key': API_KEY }
    }).then(r => r.json());

    result.companies.forEach(company => {
      console.log(`\n${company.domain} leadership:`);
      company.persons.forEach(person => {
        console.log(`  ${person.full_name} - ${person.title}`);
        console.log(`    Email: ${person.email ?? 'N/A'}`);
      });
    });
    break;
  }

  await new Promise(r => setTimeout(r, 2000));
}

Enrich Company with Leadership in One Request (v2)

Combine company enrichment and leadership discovery for efficiency.

cURL

# Enrich company + leadership (6 units total)
curl -X POST "$BASE_URL/v2/enrich/company" \
  -H "X-Api-Key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "stripe.com",
    "include_leadership": true
  }'

Python

# Enrich company with leadership in one call
job = requests.post(
    f"{BASE_URL}/v2/enrich/company",
    headers=headers,
    json={"domain": "stripe.com", "include_leadership": True}
).json()

print(f"Job ID: {job['task_id']}")
print(f"Units charged: {job['units_charged']}  # 6 units (1 + 5)")
print(f"Units remaining: {job['units_remaining']}")

# Poll for completion
while True:
    status = requests.get(
        f"{BASE_URL}/v2/tasks/{job['task_id']}",
        headers=headers
    ).json()

    if status["status"] == "completed":
        # Get enriched company data
        company = requests.get(
            f"{BASE_URL}/v2/companies/stripe.com?include=leadership",
            headers=headers
        ).json()

        print(f"\nCompany: {company['name']}")
        print(f"Industry: {company['industry']}")
        print(f"Leadership: {len(company['leadership_summary'])} people")
        break

    time.sleep(2)

JavaScript

// Enrich company with leadership in one call
const job = await fetch(`${BASE_URL}/v2/enrich/company`, {
  method: 'POST',
  headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    domain: 'stripe.com',
    include_leadership: true
  })
}).then(r => r.json());

console.log(`Job ID: ${job.task_id}`);
console.log(`Units charged: ${job.units_charged} // 6 units (1 + 5)`);
console.log(`Units remaining: ${job.units_remaining}`);

// Poll for completion
while (true) {
  const status = await fetch(`${BASE_URL}/v2/tasks/${job.task_id}`, {
    headers: { 'X-Api-Key': API_KEY }
  }).then(r => r.json());

  if (status.status === 'completed') {
    // Get enriched company data
    const company = await fetch(
      `${BASE_URL}/v2/companies/stripe.com?include=leadership`,
      { headers: { 'X-Api-Key': API_KEY } }
    ).then(r => r.json());

    console.log(`\nCompany: ${company.name}`);
    console.log(`Industry: ${company.industry}`);
    console.log(`Leadership: ${company.leadership_summary.length} people`);
    break;
  }

  await new Promise(r => setTimeout(r, 2000));
}

Tips

• Use v2 person search: Free and fast way to find decision-makers before enriching
• Leadership discovery: 5 units gets you ~10 enriched executives (cheaper than enriching individually)
• Batch when possible: Use /enrich/batch to enrich multiple entities in one request
• Use TAL for ongoing campaigns: Add companies to your TAL, then re-enrich periodically with max_age_days to keep data fresh
• Check freshness: The enriched_at field tells you when data was last updated—skip re-enrichment if it’s recent
• Poll efficiently: Start with 2-second intervals; most enrichments complete within 5-10 seconds
• Monitor usage: Check /usage before large batch operations to ensure you have enough units