Contacts

Full CRUD operations for contacts in your graph8 workspace.

---

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

Example

cURL

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

Python

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

TypeScript

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

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",
      "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.