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

Get All Lists

Returns all lists for an organization.

Method: GET
Path: /lists/\{organization_id\}

Path Parameters

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

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

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

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

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

Export ChatGPT Ads Audience

Downloads a UTF-8 CSV ready to upload in ChatGPT Ads Manager as a Custom Audience. Does not sync automatically — export and upload manually until OpenAI exposes an Audiences API.

Uses enriched emails from the list filter (deduplicated, SHA-256 hashed once — Bullseye never double-hashes). Plaintext emails are not included in the file.

Method: GET
Path: /lists/\{id\}/chatgpt-ads-export

Path Parameters

Query Parameters

Response

• Content-Type: text/csv; charset=utf-8
• Body: CSV with header email_sha256 and one lowercase hex SHA-256 digest per row
• Header: X-Unique-Email-Count — deduplicated hashed email count

Error codes

Example

curl -X GET "https://api.app.bullseye.so/api/v1/lists/list_xyz789/chatgpt-ads-export?organizationId=org_abc123" 
  -H "X-API-Key: bsk_live_your_api_key_here" 
  -o chatgpt-audience.csv

See ChatGPT Ads for Ads Manager upload steps and audience limits.