Lists

The lists endpoints let you create, list, retrieve, refresh, and delete saved lists. Lists are filtered contact sets that can be synced to integrations or exported.

Endpoints

Method	Path	Description
GET	/lists/{organization_id}	Get all lists for organization
GET	/lists/{id}	Get specific list details
POST	/lists/save	Create or update a list (with filters)
POST	/lists/refresh/{id}	Refresh list data
DELETE	/lists/{id}	Delete a list

---

Get All Lists

Returns all lists for an organization.

Method: GET Path: /lists/{organization_id}

Path Parameters

Parameter	Type	Description
organization_id	string	Organization ID

Response Body

Returns an array of list objects, each with id, name, organizationId, usedFilter, contactsNum, matchedContactsNum, autoUpdateStatus, lastSyncedTime, and connectedIntegration.

Example

curl -X GET "https://api.app.bullseye.so/api/v1/lists/org_abc123" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json"

---

Get List

Returns details for a specific list.

Method: GET Path: /lists/{id}

Path Parameters

Parameter	Type	Description
id	string	List ID

Response Body

Returns the list object with full details including the filter used to create it.

Example

curl -X GET "https://api.app.bullseye.so/api/v1/lists/list_xyz789" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json"

---

Create or Update List

Creates a new list or updates an existing one using a filter. The filter defines company and contact criteria (industries, job titles, locations, etc.).

Method: POST Path: /lists/save

Request Body

Field	Type	Required	Description
organizationId	string	Yes	Organization ID
listName	string	Yes	Name for the list
contacts_found	integer	Yes	Number of contacts matching the filter
filter	object	Yes	Filter criteria (company filters, contact filters, etc.)

The filter object can include fields such as industries, job_titles, countries, company_sizes, domains, and many others. See the platform filter documentation for full filter options.

Response Body

Returns the created or updated list object.

Example

curl -X POST "https://api.app.bullseye.so/api/v1/lists/save" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "listName": "Marketing Leaders",
    "contacts_found": 150,
    "filter": {
      "job_titles": ["VP Marketing", "CMO"],
      "industries": ["Technology"]
    }
  }'

---

Refresh List

Triggers a refresh of the list data. The list is recalculated based on the stored filter.

Method: POST Path: /lists/refresh/{id}

Path Parameters

Parameter	Type	Description
id	string	List ID

Request Body

May include optional parameters (e.g., organizationId) depending on API requirements.

Response Body

Returns the list object with updated lastSyncedTime and contact counts.

Example

curl -X POST "https://api.app.bullseye.so/api/v1/lists/refresh/list_xyz789" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

---

Delete List

Permanently deletes a list.

Method: DELETE Path: /lists/{id}

Path Parameters

Parameter	Type	Description
id	string	List ID

Request Body

May require a body with organizationId or other fields for validation.

Response Body

Returns 200 on success. No content body.

Example

curl -X DELETE "https://api.app.bullseye.so/api/v1/lists/list_xyz789" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'