All docs

Start here

API basics

SDK

CLI

MCP

Agent setups

Resources

Data pipeline

Webhooks

What's new

Lists

Create, manage, and populate contact lists

Lists organize contacts into groups for campaigns, exports, and segmentation.

Lists are also how data moves from the open data index into your workspace. When you call /search/contacts/save or /search/companies/save, graph8 creates a new list and populates it with matching records. Those contacts and companies then become part of your first-party data, accessible through the /contacts and /companies endpoints.

List All Lists

GET /lists

Returns a paginated list of all lists in your organization.

Query Parameters

ParameterTypeDefaultDescription
pageinteger1Page number (1-indexed)
limitinteger50Items per page (1-200)

Example

cURL

curl "https://be.graph8.com/api/v1/lists?limit=20" \
  -H "Authorization: Bearer $API_KEY"

Python

response = requests.get(
    f"{BASE_URL}/lists",
    headers=HEADERS,
    params={"limit": 20}
)
lists = response.json()

TypeScript

const response = await fetch(`${BASE_URL}/lists?limit=20`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const lists = await response.json();

Response

{
  "data": [
    {
      "id": 10,
      "title": "Enterprise Prospects Q1",
      "type": "contacts",
      "source": "graph8",
      "status": "completed",
      "total": 1250,
      "is_dynamic": false,
      "tags": ["enterprise", "q1-2026"],
      "created_at": "2026-01-15T10:00:00Z",
      "created_by": "user_abc123",
      "updated_at": "2026-02-20T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "has_next": false
  }
}

Create List

POST /lists

Create a new empty list. Add contacts to it afterward using the Add Contacts endpoint.

Request Body

FieldTypeRequiredDefaultDescription
titlestringYes—Name of the list
typestringNo"contacts"List type: contacts, companies, suppressions, deals, leads

Example

cURL

curl -X POST "https://be.graph8.com/api/v1/lists" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Enterprise Prospects Q1", "type": "contacts"}'

Python

response = requests.post(
    f"{BASE_URL}/lists",
    headers=HEADERS,
    json={"title": "Enterprise Prospects Q1", "type": "contacts"}
)
new_list = response.json()["data"]

TypeScript

const response = await fetch(`${BASE_URL}/lists`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ title: "Enterprise Prospects Q1", type: "contacts" })
});
const { data: newList } = await response.json();

Response 201 Created

{
  "data": {
    "id": 11,
    "title": "Enterprise Prospects Q1",
    "type": "contacts",
    "status": "completed",
    "total": 0
  }
}

Errors

StatusMeaning
400Invalid list type

Delete List

DELETE /lists/{list_id}

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

Path Parameters

ParameterTypeDescription
list_idintegerList ID

Example

cURL

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

Python

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

TypeScript

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

Response

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

Errors

StatusMeaning
404List not found

Get List Contacts

GET /lists/{list_id}/contacts

Returns the contacts in a specific list.

Path Parameters

ParameterTypeDescription
list_idintegerList ID

Query Parameters

ParameterTypeDefaultDescription
pageinteger1Page number (1-indexed)
limitinteger50Items per page (1-200)

Example

cURL

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

Python

response = requests.get(
    f"{BASE_URL}/lists/10/contacts",
    headers=HEADERS,
    params={"limit": 25}
)
contacts = response.json()["data"]

TypeScript

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

Response

{
  "data": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Smith",
      "full_name": "Jane Smith",
      "work_email": "[email protected]",
      "job_title": "VP of Engineering",
      "seniority_level": "VP",
      "direct_phone": "+1-555-0100",
      "linkedin_url": "https://linkedin.com/in/janesmith",
      "city": "San Francisco",
      "state": "CA",
      "country": "US"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1250,
    "has_next": true
  }
}

Add Contacts to List

POST /lists/{list_id}/contacts

Add one or more contacts to a list by their IDs.

Path Parameters

ParameterTypeDescription
list_idintegerList ID

Request Body

FieldTypeRequiredDescription
contact_idsinteger[]YesContact IDs to add

Example

cURL

curl -X POST "https://be.graph8.com/api/v1/lists/10/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_ids": [1, 2, 3, 4, 5]}'

Python

response = requests.post(
    f"{BASE_URL}/lists/10/contacts",
    headers=HEADERS,
    json={"contact_ids": [1, 2, 3, 4, 5]}
)
result = response.json()["data"]

TypeScript

const response = await fetch(`${BASE_URL}/lists/10/contacts`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ contact_ids: [1, 2, 3, 4, 5] })
});
const { data: result } = await response.json();

Response 201 Created

{
  "data": {
    "added": 5
  }
}

Remove Contacts from List

DELETE /lists/{list_id}/contacts

Remove one or more contacts from a list. The contacts are not deleted — they are only removed from this list.

Path Parameters

ParameterTypeDescription
list_idintegerList ID

Request Body

FieldTypeRequiredDescription
contact_idsinteger[]YesContact IDs to remove

Example

cURL

curl -X DELETE "https://be.graph8.com/api/v1/lists/10/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_ids": [3, 4]}'

Python

response = requests.delete(
    f"{BASE_URL}/lists/10/contacts",
    headers=HEADERS,
    json={"contact_ids": [3, 4]}
)
result = response.json()["data"]

TypeScript

const response = await fetch(`${BASE_URL}/lists/10/contacts`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ contact_ids: [3, 4] })
});
const { data: result } = await response.json();

Response

{
  "data": {
    "removed": 2
  }
}
Build with graph8