Skip to main content

Overview

A lead list is a reusable collection of leads in your workspace. Lists are useful when the same audience needs to be enriched, enrolled, or reported on more than once. The lead list endpoints let you:
  • Create, rename and delete named lists
  • Add leads to a list
  • List the leads in a list
  • Enrich every lead in a list
  • Enroll a whole list in a campaign
  • Delete a list without deleting the leads
Deleting a list removes the grouping, not the leads inside it. A list that is still attached to a campaign cannot be deleted (409).

Create a list

Save the returned id. It is the lead_list_id the other endpoints take.

List, get and update lists

Updating a list changes list metadata only. It does not change the leads already assigned to it.

Add and list leads

Create a lead inside a list by sending the list’s id with the lead:
List the leads currently in a list:
To bring in many leads at once, use rows on the same create endpoint. See Imports and prospecting. Use the Leads guide to update, enrich, or inspect an individual lead after it has been added.

Enrich a list

Enrichment of a list runs inside the request and returns counts under results.enrich: total, skipped, succeeded, failed and a failure_reason when the whole run was refused. method is database (connected providers) or web_search.
Enrichment can update lead fields and consume workspace enrichment credits. Start with a small list when validating a new enrichment workflow.

Use a list in a campaign

Update the campaign with the list’s id to enroll every lead in it:
The response carries an enrollment object with enrolled, skipped and total_requested. See Campaigns for individual-lead enrollment, preflight checks, and launch controls.

Delete a list

Deleting a list removes the grouping, not the leads inside it, and answers 409 while a campaign still uses the list. Delete individual leads through the Leads API when that is the intended operation.