Contacts

Using the SDK or CLI?

The CLI supports g8 search-contacts, g8 create-contact, and g8 add-to-list. The JavaScript SDK tracks visitors and identifies users via g8.identify().

Manage contacts in your graph8 workspace — your first-party CRM data.

Contacts get into your workspace through several paths: saving results from the Search endpoints, importing from a CSV or CRM, creating manually via the API, or automatically during enrichment. Once a contact is in your workspace, these endpoints give you full read/write access at no credit cost.

Looking for new contacts?

These endpoints only return contacts you already have. To discover new contacts from graph8’s global B2B database, use the Search endpoints instead.

---

List Contacts

GET /contacts

Returns a paginated list of contacts.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
limit	integer	50	Items per page (1-200)
email	string	—	Filter by work email (exact match)
list_id	integer	—	Filter by list membership
name	string	—	Filter by first or last name (partial match, case-insensitive)
job_title	string	—	Filter by job title (partial match, case-insensitive)
seniority_level	string	—	Filter by seniority level (exact match)
company_name	string	—	Filter by company name (partial match, case-insensitive)
company_id	integer	—	Filter by company ID
country	string	—	Filter by country (exact match)
state	string	—	Filter by state (exact match)
city	string	—	Filter by city (partial match, case-insensitive)
job_department	string	—	Filter by job department (partial match, case-insensitive)
industry	string	—	Filter by company industry (partial match, case-insensitive)

All filters are optional and can be combined. When multiple filters are provided, results must match all of them (AND logic).

Example

cURL

# Basic pagination
curl "https://be.graph8.com/api/v1/contacts?limit=10&page=1" \
  -H "Authorization: Bearer $API_KEY"

# Search by name and company
curl "https://be.graph8.com/api/v1/contacts?name=jane&company_name=acme" \
  -H "Authorization: Bearer $API_KEY"

# Filter by seniority and country
curl "https://be.graph8.com/api/v1/contacts?seniority_level=VP&country=US" \
  -H "Authorization: Bearer $API_KEY"

# Filter by department and industry
curl "https://be.graph8.com/api/v1/contacts?job_department=Engineering&industry=SaaS" \
  -H "Authorization: Bearer $API_KEY"

Python

# Basic pagination
response = requests.get(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    params={"limit": 10, "page": 1}
)
contacts = response.json()

# Search by name and company
response = requests.get(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    params={"name": "jane", "company_name": "acme"}
)

# Filter by department and industry
response = requests.get(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    params={"job_department": "Engineering", "industry": "SaaS"}
)

TypeScript

// Basic pagination
const response = await fetch(`${BASE_URL}/contacts?limit=10&page=1`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const contacts = await response.json();

// Search by name and company
const filtered = await fetch(
  `${BASE_URL}/contacts?name=jane&company_name=acme`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

// Filter by department and industry
const deptFiltered = await fetch(
  `${BASE_URL}/contacts?job_department=Engineering&industry=SaaS`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

Response

{
  "data": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Smith",
      "work_email": "jane@acme.com",
      "direct_phone": "+1-555-0100",
      "mobile_phone": null,
      "job_title": "VP of Engineering",
      "job_department": "Engineering",
      "seniority_level": "VP",
      "linkedin_url": "https://linkedin.com/in/janesmith",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "company_id": 42
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 243,
    "has_next": true
  }
}

---

Get Contact

GET /contacts/{contact_id}

Returns detailed information about a single contact, including associated company data.

Path Parameters

Parameter	Type	Description
contact_id	integer	Contact ID

Example

cURL

curl "https://be.graph8.com/api/v1/contacts/1" \
  -H "Authorization: Bearer $API_KEY"

Python

response = requests.get(f"{BASE_URL}/contacts/1", headers=HEADERS)
contact = response.json()["data"]

TypeScript

const response = await fetch(`${BASE_URL}/contacts/1`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const { data: contact } = await response.json();

Response

{
  "data": {
    "id": 1,
    "first_name": "Jane",
    "last_name": "Smith",
    "full_name": "Jane Smith",
    "work_email": "jane@acme.com",
    "personal_emails": null,
    "direct_phone": "+1-555-0100",
    "mobile_phone": null,
    "job_title": "VP of Engineering",
    "job_department": "Engineering",
    "seniority_level": "VP",
    "linkedin_url": "https://linkedin.com/in/janesmith",
    "twitter_url": null,
    "facebook_url": null,
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "about": null,
    "confidence_score": 0.95,
    "company": {
      "id": 42,
      "name": "Acme Inc",
      "domain": "acme.com",
      "website": "https://acme.com",
      "industry": "Technology",
      "employee_count": "500",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "linkedin_url": "https://linkedin.com/company/acme",
      "logo_url": "https://logo.clearbit.com/acme.com"
    },
    "meta_data": null,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-01T14:20:00Z"
  }
}

Errors

Status	Meaning
404	Contact not found

---

Create Contact

POST /contacts

Create a new contact and add it to a list.

Request Body

Field	Type	Required	Description
list_id	integer	Yes	Target list to add the contact to
first_name	string	No	First name
last_name	string	No	Last name
work_email	string	No	Work email address
personal_emails	string	No	Personal email addresses
direct_phone	string	No	Direct phone number
mobile_phone	string	No	Mobile phone number
job_title	string	No	Job title
job_department	string	No	Department
seniority_level	string	No	Seniority level
linkedin_url	string	No	LinkedIn profile URL
city	string	No	City
state	string	No	State or province
country	string	No	Country
company_domain	string	No	Company domain for matching

Example

cURL

curl -X POST "https://be.graph8.com/api/v1/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": 5,
    "first_name": "John",
    "last_name": "Doe",
    "work_email": "john@techcorp.io",
    "job_title": "CTO",
    "company_domain": "techcorp.io"
  }'

Python

response = requests.post(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    json={
        "list_id": 5,
        "first_name": "John",
        "last_name": "Doe",
        "work_email": "john@techcorp.io",
        "job_title": "CTO",
        "company_domain": "techcorp.io"
    }
)
result = response.json()["data"]

TypeScript

const response = await fetch(`${BASE_URL}/contacts`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    list_id: 5,
    first_name: "John",
    last_name: "Doe",
    work_email: "john@techcorp.io",
    job_title: "CTO",
    company_domain: "techcorp.io"
  })
});
const { data: result } = await response.json();

Response 201 Created

{
  "data": {
    "status": "success",
    "count": 1,
    "validation_errors": []
  }
}

---

Update Contact

PATCH /contacts/{contact_id}

Update one or more fields on a contact. Only include the fields you want to change.

Path Parameters

Parameter	Type	Description
contact_id	integer	Contact ID

Request Body

All fields are optional. Include only the fields to update.

Field	Type	Description
first_name	string	First name
last_name	string	Last name
work_email	string	Work email address
direct_phone	string	Direct phone number
mobile_phone	string	Mobile phone number
job_title	string	Job title
job_department	string	Department
seniority_level	string	Seniority level
linkedin_url	string	LinkedIn profile URL
city	string	City
state	string	State or province
country	string	Country

Example

cURL

curl -X PATCH "https://be.graph8.com/api/v1/contacts/1" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_title": "CTO", "city": "New York"}'

Python

response = requests.patch(
    f"{BASE_URL}/contacts/1",
    headers=HEADERS,
    json={"job_title": "CTO", "city": "New York"}
)

TypeScript

const response = await fetch(`${BASE_URL}/contacts/1`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ job_title: "CTO", city: "New York" })
});

Response

{
  "data": {
    "updated": 1
  }
}

Errors

Status	Meaning
400	No fields provided to update
404	Contact not found

---

Delete Contact

DELETE /contacts/{contact_id}

Soft-delete a contact. The contact is marked as deleted but not permanently removed.

Path Parameters

Parameter	Type	Description
contact_id	integer	Contact ID

Example

cURL

curl -X DELETE "https://be.graph8.com/api/v1/contacts/1" \
  -H "Authorization: Bearer $API_KEY"

Python

response = requests.delete(f"{BASE_URL}/contacts/1", headers=HEADERS)

TypeScript

const response = await fetch(`${BASE_URL}/contacts/1`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${API_KEY}` }
});

Response

{
  "data": {
    "deleted": true
  }
}

Errors

Status	Meaning
404	Contact not found

Caution

Deleted contacts cannot be restored via the API. Contact support if you need to recover deleted data.