Skip to content
Docs

Add List to Leads

Add the revealed people of a list to Leads.

POST/api/v1/lead-finder/lists/{list_id}/add-to-leads

Requires an API key with the write scope.

Free. Adds the people in the list whose email was found. Counts toward the contact limit, all or nothing. Only a people list can be added.

Path Parameters#

list_idstringpathrequired
The list id.

Body Parameters#

keysarraybody
Item keys to add. Omit for every person in the list.
campaignIdstringbody
Also place them in this campaign.

Response#

dataobject
Show data
addedinteger
New leads created.
restoredinteger
Deleted leads brought back.
alreadyInLeadsinteger
People who were already active leads.
blockedinteger
People skipped because they are on the block list.
skippedinteger
Items with no found email.
addedToCampaigninteger
People added to campaignId.

Errors#

StatusDescription
401Missing, invalid, revoked or expired API key
403API key does not have the required scope: write
404Lead Finder is not enabled while Lead Finder is switched off on this environment
503Lead Finder is not configured when it is enabled but has no data provider key
404List not found: the list does not exist in this workspace
402upgrade_required: adding them would pass the plan's contact limit
404Campaign not found when campaignId is not in this workspace
422The list is a company list

Rate Limit#

  • 100 requests per minute, shared by every bulk call in your workspace. Fixed 60-second window.
  • Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (bulk).
  • A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns, see Rate Limiting.

Was this page helpful?
View as MarkdownLast updated November 4, 2026