REST API Overview

The REST API gives you direct HTTP access to contacts, companies, lists, enrichment, search, sequences, webhooks, deals, tasks, notes, fields, quotes, pipelines, workflows, skills, voice, intent, studio, and more. 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
Rate limit: 5 rps per org (details)
Docs: Interactive Swagger →

30-second start

If you can paste a curl, you can start integrating:

# Will return your stored contacts (or [] if none yet)
curl 'https://be.graph8.com/api/v1/contacts?limit=3' \
  -H "Authorization: Bearer $G8_API_KEY"

import { g8 } from '@graph8/sdk';
g8.init({ apiKey: process.env.G8_API_KEY! });

const { data } = await g8.contacts.list({ limit: 3 });

import httpx, os
r = httpx.get(
    "https://be.graph8.com/api/v1/contacts",
    params={"limit": 3},
    headers={"Authorization": f"Bearer {os.environ['G8_API_KEY']}"},
)
print(r.json())

g8 login
g8 search-contacts --limit 3

Configure your AI client per MCP setup, then ask: “Show me my last 3 contacts.” → calls g8_search_contacts.

Claude Code

Cursor

Windsurf

Claude Desktop

ChatGPT

Don’t have an API key? Get one in 30 seconds →

API Surfaces

graph8 exposes two distinct HTTP surfaces. Only /api/v1/* is for developers — everything else is internal.

Surface	Mount	Auth	Use case
Developer API	`https://be.graph8.com/api/v1/*`	`Authorization: Bearer` (API key)	What every doc on this site refers to — SDK, CLI, and MCP server all proxy this surface
Internal Studio	`/v1/` and `/campaign-builder/`	PropelAuth session cookie	First-party UI in `app.graph8.com` — not for integrations
Public (write-key)	`/api/v1/public/*`	Write key (browser-safe)	Visitor tracking, public-form enrich, copilot chat (details)
Intent-search	`/intent-search/*` (no `/api/v1` prefix)	`Authorization: Bearer` (API key)	The one outlier — see Intent

Stick to /api/v1/* unless a doc explicitly tells you otherwise.

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 700M+ / 100M+ 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 →

CRM: Notes | Tasks | Fields | Deals | Assert/Upsert

Engage: Sequence Lifecycle | Inbox | Meetings | Voice & Dialer | Webhooks

Revenue: Quotes | Stage Checklist Pipelines

Automation: Workflows | Skills | Landing Pages

Intelligence: Intent & Signals | GTM Campaigns | GTM Context

Sync: Audience Syncs | CRM Syncs

Public (browser, write key): Public Endpoints

Reference: Pricing | Pagination | Errors | Rate Limits | REST API FAQ

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	PAYG	Platform
Find new contacts matching my ICP	`POST /search/contacts`	1 per record returned	Free (within 5 rps)
Find new companies by industry, size, etc.	`POST /search/companies`	1 per record returned	Free (within 5 rps)
Save search results to my workspace	`POST /search/contacts/save`	1 per record saved	Free (within 5 rps)
Look up one person by email or LinkedIn	`POST /enrichment/lookup/person`	2 per lookup	Free (within 5 rps)
Look up one company by domain	`POST /enrichment/lookup/company`	2 per lookup	Free (within 5 rps)
List contacts I’ve already saved	`GET /contacts`	Free	Free
List companies in my workspace	`GET /companies`	Free	Free
Manage my lists	`GET /lists`	Free	Free
Fill missing emails/phones on my contacts (waterfall)	`POST /enrichment/enrich`	Variable per contact	Variable per contact
Verify an email address (internal validator)	`POST /enrichment/verify-email`	1 per email	Free (within 5 rps)

See Pricing for the full bucket map and plan comparison.

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

Pricing

Plans, credit costs, the unlimited-API bundle, and auto-CRM-capture behavior. View pricing

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.