Lead Finder: add people to a campaign (spends credits)
add_lead_finder_prospectsSPENDS CREDITS, AND BY DEFAULT METERED EMAIL VERIFICATION. Adds people from the Lead Finder contact database to a campaign as leads, revealing their contact details, in the background. Pass refs (from search_lead_finder results; up to 1,000 different people by default) to add exactly those people, or pass filters and count (1 to 5,000 by default) to add count people matching the filters who are not in the workspace yet. A filters add always walks the matches from the top and skips anyone already a lead, free and not counted, so repeating the same add adds the NEXT count people and charges again. Never repeat an add to retry: after an error or a timeout, call list_lead_finder_imports to see whether it started. A filters add stops early when the audience runs out or once it has looked at five people for every one requested (at least 1,000). People already added count toward that limit even though skipping them is free, so after an add of more than about 1,000 people a small follow-up can stop with nobody added. Every person a filters add looks at, added or skipped, also uses the account's daily allowance for filters adds (25,000 people by default). Each person added costs 1 credit ($0.033 at list), reported as creditsPerProspect; the response reports estimatedCredits, the most the add can cost in credits, and the wallet must hold that much for it to start. People already in the workspace, blocklisted, without a usable address, on a personal mailbox when the campaign only takes business addresses, or marked invalid by verification are skipped and cost no credits. verifyEmails (on by default) checks every screened address with the paid email verification waterfall, including the ones it marks invalid: one or two checks per address, billed as metered usage on the next invoice (price per check: GET /email-verification/rates in the REST API), within the account's monthly verification spend limit. Catch-all and unconfirmed addresses are added and charged, and so is every address once that limit is reached; verification.limitReached and verification.unknown on get_lead_finder_import count them. Leads added to a running or paused campaign get their emails at once (a paused campaign sends them when resumed); adding to a completed campaign resumes it, so it starts sending again; in a draft campaign the emails are created at launch. At most 3 adds run at once in a workspace. A refusal names its reason, and a 429 also says when to retry (reason running_imports, daily_import_limit, daily_budget, monthly_budget or fair_use_floor). Poll get_lead_finder_import with the importId until finishedAt is set. Check get_credit_balance first; buy credits with purchase_credits.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| refs | No | Refs of the people to add, from search_lead_finder results. Duplicates and blanks are dropped before sending; up to 1,000 different people per add by default (get_lead_finder_filters has the limit that applies). Use either refs, or filters with count | |
| count | No | How many people not yet in the workspace to add with filters (1 to 5,000 by default; get_lead_finder_filters has the limit that applies) | |
| filters | No | Add people matching these filters (same shape as search_lead_finder). Needs count. The matches are walked from the top every time and people already in the workspace are skipped, so a repeat adds the next count people | |
| campaignId | Yes | The numeric campaign ID (from list_campaigns) | |
| verifyEmails | No | Check each address with the paid email verification waterfall before adding it (default true): one or two checks per address, billed on the next invoice, including addresses that turn out invalid. Invalid addresses are skipped and cost no credits; catch-all and unconfirmed ones are still added and charged, and so is every address once the monthly verification spend limit is reached. false skips verification |