REST API Overview

The REST API gives you direct HTTP access to contacts, companies, lists, enrichment, search, sequences, and webhooks. Any language, any platform.

Quick Reference

Base URL: https://be.graph8.com/api/v1
Auth: Authorization: Bearer YOUR_API_KEY (details)
Format: JSON request/response
Docs: Interactive Swagger →

Contacts

List, create, update, and delete contacts in your workspace. View reference →

Companies

List, update, and delete companies and their associated contacts. View reference →

Find contacts and companies in graph8’s 300M+ global database. View reference →

Enrichment

Look up people and companies, run waterfall enrichment, and verify emails. View reference →

Lists

Create lists, manage membership, and organize contacts for campaigns. View reference →

Sequences

List, run, and manage automated email sequences. View reference →

Reference: Pagination | Errors | Rate Limits

The graph8 Developer API lets you programmatically discover new prospects, manage your CRM data, and enrich contact information - all through a single REST API.

How Data Works in graph8

graph8 gives you access to two distinct pools of data. Understanding the difference is the key to using the API effectively.

Your data (first-party)

This is data you own — contacts and companies that live in your graph8 workspace. They got there through one of these paths:

You saved search results from the open data index (via /search/contacts/save)
You imported contacts from a CSV or CRM integration
You created them manually via the API (via POST /contacts)
They were auto-created during enrichment or campaign workflows

You have full read/write access to your data. Query it, update it, delete it, organize it into lists — no credit cost.

Endpoints: /contacts, /companies, /lists

Open data index

This is graph8’s global B2B database — millions of contacts and companies aggregated from multiple data providers. Think of it as a phonebook for the business world: names, titles, emails, phone numbers, company details, and more.

You can search this index with filters (job title, industry, company size, location, etc.) and save matching results into your workspace. Once saved, they become your data.

You can also look up a single person or company by email, LinkedIn URL, or domain.

Open data queries consume credits.

Endpoints: /search/contacts, /search/companies, /enrichment/lookup

The data flow

The typical workflow moves data from open → owned:

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   1. DISCOVER            2. SAVE              3. MANAGE         │
│                                                                 │
│   /search/contacts  ──►  /search/.../save  ──►  /contacts      │
│   /search/companies      (creates a list)       /companies      │
│   /enrichment/lookup                            /lists          │
│                                                                 │
│   Open data index        Moves into your        Full CRUD on    │
│   (read-only, credits)   workspace as a list    your data (free)│
│                                                                 │
│                          4. ENRICH                              │
│                          /enrichment/enrich                     │
│                          Fill missing fields                    │
│                          on your saved contacts                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Choosing the Right Endpoint

I want to…	Use	Credits
Find new contacts matching my ICP	`POST /search/contacts`	1 per record returned
Find new companies by industry, size, etc.	`POST /search/companies`	1 per record returned
Save search results to my workspace	`POST /search/contacts/save`	1 per record saved
Look up one person by email or LinkedIn	`POST /enrichment/lookup/person`	2 per lookup
Look up one company by domain	`POST /enrichment/lookup/company`	2 per lookup
List contacts I’ve already saved	`GET /contacts`	Free
List companies in my workspace	`GET /companies`	Free
Manage my lists	`GET /lists`	Free
Fill missing emails/phones on my contacts	`POST /enrichment/enrich`	2 per contact
Verify an email address	`POST /enrichment/verify-email`	1 per email

Base URL

https://be.graph8.com/api/v1

All endpoints are relative to this base URL. For example, to list contacts:

GET https://be.graph8.com/api/v1/contacts

Quick Start

export API_KEY="YOUR_API_KEY"

# 1. Search the open data index for CTOs at tech companies
curl -X POST "https://be.graph8.com/api/v1/search/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "job_title", "operator": "any_of", "value": ["CTO", "VP Engineering"]},
      {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
    ],
    "limit": 5
  }'

# 2. Save matching contacts to a list in your workspace
curl -X POST "https://be.graph8.com/api/v1/search/contacts/save" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "job_title", "operator": "any_of", "value": ["CTO", "VP Engineering"]},
      {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
    ],
    "list_title": "Tech CTOs"
  }'

# 3. Query your saved contacts (free, no credits)
curl "https://be.graph8.com/api/v1/contacts?list_id=42&limit=10" \
  -H "Authorization: Bearer $API_KEY"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://be.graph8.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Search the open data index for CTOs at tech companies
results = requests.post(
    f"{BASE_URL}/search/contacts",
    headers=HEADERS,
    json={
        "filters": [
            {"field": "job_title", "operator": "any_of", "value": ["CTO", "VP Engineering"]},
            {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
        ],
        "limit": 5
    }
).json()

print(f"Found {results['pagination']['total']} matches")

# 2. Save matching contacts to a list in your workspace
save = requests.post(
    f"{BASE_URL}/search/contacts/save",
    headers=HEADERS,
    json={
        "filters": [
            {"field": "job_title", "operator": "any_of", "value": ["CTO", "VP Engineering"]},
            {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
        ],
        "list_title": "Tech CTOs"
    }
).json()

list_id = save["data"]["list_id"]

# 3. Query your saved contacts (free, no credits)
contacts = requests.get(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    params={"list_id": list_id, "limit": 10}
).json()

for c in contacts["data"]:
    print(f"{c['first_name']} {c['last_name']} - {c['work_email']}")

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://be.graph8.com/api/v1";
const headers = { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" };

// 1. Search the open data index for CTOs at tech companies
const results = await fetch(`${BASE_URL}/search/contacts`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    filters: [
      { field: "job_title", operator: "any_of", value: ["CTO", "VP Engineering"] },
      { field: "company_employee_count", operator: "between", value: [50, 500] }
    ],
    limit: 5
  }),
}).then(r => r.json());

console.log(`Found ${results.pagination.total} matches`);

// 2. Save matching contacts to a list in your workspace
const save = await fetch(`${BASE_URL}/search/contacts/save`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    filters: [
      { field: "job_title", operator: "any_of", value: ["CTO", "VP Engineering"] },
      { field: "company_employee_count", operator: "between", value: [50, 500] }
    ],
    list_title: "Tech CTOs"
  }),
}).then(r => r.json());

// 3. Query your saved contacts (free, no credits)
const contacts = await fetch(
  `${BASE_URL}/contacts?list_id=${save.data.list_id}&limit=10`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
).then(r => r.json());

contacts.data.forEach(c =>
  console.log(`${c.first_name} ${c.last_name} - ${c.work_email}`)
);

Endpoint Reference

Discover (open data — credits)

Find contacts and companies in graph8’s global B2B database using filters like job title, industry, company size, and location. View reference

Enrichment

Look up a single person or company, run waterfall enrichment across providers, and verify email deliverability. View reference

Manage (your data — free)

Contacts

List, create, update, and delete contacts in your workspace. View reference

Companies

List, update, and delete companies and their associated contacts. View reference

Lists

Create lists, manage list membership, and organize contacts for campaigns. View reference

Reference

Authentication

Create API keys and authenticate your requests. Get started

Pagination

Response envelope and pagination patterns. Learn more

Errors

Error codes and handling strategies. Learn more

Rate Limits

Request limits and backoff strategies. Learn more

Interactive API Reference

For a live, interactive view of all endpoints with request/response schemas, visit the OpenAPI docs:

Open Interactive API Docs →

You can test endpoints directly from the browser — authenticate with your API key and execute requests in real time.

Response Format

All responses use a standard envelope:

{
  "data": { ... },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 243,
    "has_next": true
  }
}

Single-resource responses include data without pagination. See Pagination for details.