Getting Started

Quick Start Guide

This guide walks you through making your first enrichment request to GraphADV. Every code sample is presented in cURL, Python, JavaScript, and TypeScript.

Prerequisites

Before you begin, you’ll need:

An API key (get one at graphadv.com)
Basic knowledge of REST APIs and HTTP requests

Step 1: Get Your API Key

Visit graphadv.com
Click Get API Key
Sign in with your email address or Google account
Your API key will be generated and displayed immediately
Copy and securely store your API key

Step 2: Set Your Environment

Set these values once and reuse them across every snippet:

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

All requests use the same header for authentication:

X-Api-Key: YOUR_API_KEY

Step 3: Enrich Your First Company

Enrichment is async. You submit a request, get a job ID, then poll for results.

Submit an Enrichment Request

curl -X POST "$BASE_URL/enrich/company" \
  -H "X-Api-Key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "stripe.com"
  }'

import os
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",
}

response = requests.post(
    f"{BASE_URL}/enrich/company",
    headers=headers,
    json={"domain": "stripe.com"}
)
job = response.json()
print(f"Task ID: {job['task_id']}")

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

const response = await fetch(`${BASE_URL}/enrich/company`, {
  method: 'POST',
  headers: {
    'X-Api-Key': API_KEY ?? '',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ domain: 'stripe.com' })
});

const job = await response.json();
console.log(`Task ID: ${job.task_id}`);

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

type EnrichmentJob = {
  task_id: string;
  status: string;
  units_charged: number;
  units_remaining: number;
};

const response = await fetch(`${BASE_URL}/enrich/company`, {
  method: 'POST',
  headers: {
    'X-Api-Key': API_KEY ?? '',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ domain: 'stripe.com' })
});

const job = (await response.json()) as EnrichmentJob;
console.log(`Task ID: ${job.task_id}`);

Response

{
  "task_id": "job_abc123",
  "status": "queued",
  "message": "Enrichment queued for stripe.com",
  "units_charged": 1,
  "units_remaining": 99
}

Poll for Results

curl "$BASE_URL/tasks/job_abc123" \
  -H "X-Api-Key: $GRAPHADV_API_KEY"

import time

task_id = job["task_id"]

while True:
    status_response = requests.get(
        f"{BASE_URL}/tasks/{task_id}",
        headers=headers
    )
    status = status_response.json()

    if status["status"] == "completed":
        # Get the result
        result_response = requests.get(
            f"{BASE_URL}/tasks/{task_id}/result",
            headers=headers
        )
        company = result_response.json()
        print(f"Enriched: {company['name']}")
        break
    elif status["status"] == "failed":
        print(f"Job failed: {status.get('error')}")
        break

    time.sleep(2)  # Poll every 2 seconds

const taskId = job.task_id;

const pollForResult = async () => {
  while (true) {
    const statusResponse = await fetch(`${BASE_URL}/tasks/${taskId}`, {
      headers: { 'X-Api-Key': API_KEY ?? '' }
    });
    const status = await statusResponse.json();

    if (status.status === 'completed') {
      const resultResponse = await fetch(`${BASE_URL}/tasks/${taskId}/result`, {
        headers: { 'X-Api-Key': API_KEY ?? '' }
      });
      return await resultResponse.json();
    } else if (status.status === 'failed') {
      throw new Error(status.error);
    }

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

const company = await pollForResult();
console.log(`Enriched: ${company.name}`);

type JobStatus = {
  task_id: string;
  status: 'queued' | 'processing' | 'completed' | 'failed';
  error?: string;
};

type EnrichedCompany = {
  domain: string;
  name: string;
  linkedin_url: string;
  industry: string;
  employee_count: number;
  headquarters_city: string;
  headquarters_state: string;
};

const pollForResult = async (taskId: string): Promise<EnrichedCompany> => {
  while (true) {
    const statusResponse = await fetch(`${BASE_URL}/tasks/${taskId}`, {
      headers: { 'X-Api-Key': API_KEY ?? '' }
    });
    const status = (await statusResponse.json()) as JobStatus;

    if (status.status === 'completed') {
      const resultResponse = await fetch(`${BASE_URL}/tasks/${taskId}/result`, {
        headers: { 'X-Api-Key': API_KEY ?? '' }
      });
      return (await resultResponse.json()) as EnrichedCompany;
    } else if (status.status === 'failed') {
      throw new Error(status.error);
    }

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

const company = await pollForResult(job.task_id);
console.log(`Enriched: ${company.name}`);

Enriched Company Response

{
  "domain": "stripe.com",
  "name": "Stripe",
  "linkedin_url": "https://linkedin.com/company/stripe",
  "industry": "Financial Services",
  "employee_count": 8000,
  "employee_range": "5001-10000",
  "headquarters_city": "San Francisco",
  "headquarters_state": "CA",
  "headquarters_country": "USA",
  "enrichment_status": "complete",
  "enriched_at": "2026-01-15T10:30:00Z"
}

Step 4: Read Your Enriched Data (Free)

Once enriched, you can read company and person data for free.

# Get a specific company by domain
curl "$BASE_URL/companies/stripe.com" \
  -H "X-Api-Key: $GRAPHADV_API_KEY"

# Search companies
curl "$BASE_URL/companies?query=fintech&state=CA&limit=10" \
  -H "X-Api-Key: $GRAPHADV_API_KEY"

# Get a specific company
company = requests.get(
    f"{BASE_URL}/companies/stripe.com",
    headers=headers
).json()

# Search companies
companies = requests.get(
    f"{BASE_URL}/companies",
    headers=headers,
    params={"query": "fintech", "state": "CA", "limit": 10}
).json()

// Get a specific company
const companyResponse = await fetch(`${BASE_URL}/companies/stripe.com`, {
  headers: { 'X-Api-Key': API_KEY ?? '' }
});
const company = await companyResponse.json();

// Search companies
const searchParams = new URLSearchParams({ query: 'fintech', state: 'CA', limit: '10' });
const searchResponse = await fetch(`${BASE_URL}/companies?${searchParams}`, {
  headers: { 'X-Api-Key': API_KEY ?? '' }
});
const companies = await searchResponse.json();

// Get a specific company
const companyResponse = await fetch(`${BASE_URL}/companies/stripe.com`, {
  headers: { 'X-Api-Key': API_KEY ?? '' }
});
const company = (await companyResponse.json()) as EnrichedCompany;

// Search companies
const searchParams = new URLSearchParams({ query: 'fintech', state: 'CA', limit: '10' });
const searchResponse = await fetch(`${BASE_URL}/companies?${searchParams}`, {
  headers: { 'X-Api-Key': API_KEY ?? '' }
});
const companies = (await searchResponse.json()) as { data: EnrichedCompany[] };

Unit Usage

Company enrichment: 1 unit
Person enrichment: 1 unit
Leadership research: 5 units
Data reads: Free (rate-limited)

Check your current usage:

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

Response:

{
  "plan": "trial",
  "units_remaining": 98,
  "units_used_this_period": 2,
  "period_ends_at": "2026-01-31T00:00:00Z"
}

Next Steps

Now that you’ve made your first enrichment request, explore:

Pricing - Understand unit costs and plans
API Reference - Complete endpoint documentation
Examples - Real-world use cases and patterns

Troubleshooting

401 Unauthorized: Check that your API key is correct and the X-Api-Key header is properly formatted.

404 Not Found: Verify the endpoint URL is correct.

402 Payment Required: You’ve run out of units. Upgrade your plan or wait for the next billing period.

429 Too Many Requests: You’ve hit the rate limit. Wait a moment and retry.