# 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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 '{}'
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bullseye.so/api-reference/lists.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.