Skip to main content
Human guide: work with your agent → Inspect one DropLeads action before starting provider-backed work. Your first result is a verified input and output contract.

​
Provider-specific requirements

Dropleads is hidden from tool discovery because of upstream reliability issues. Choose another provider for new workflows. Exact calls and existing Plays remain supported. The guidance below applies to those existing integrations. Use Dropleads as a two-phase flow: low-cost contact discovery first, paid enrichment second. Do not use Dropleads people search as the first step for account discovery.

​
1) Start with low-cost discovery

  • Use dropleads_get_lead_count to size the audience before any paid call.
  • Use dropleads_search_people to inspect masked contacts and validate ICP filters (free).
  • Use dropleads_search_people after you already have target account domains, by passing filters.companyDomains. It is a contact search primitive, not a dependable way to discover target accounts.
  • Do not build joins or account-discovery flows that depend on every returned lead having companyDomain. Treat returned companyDomain as optional. if you need account domains as the source of truth, use a company-native search/enrichment tool first.
  • Tighten filters until sample rows clearly match role, industry, and geo expectations.
  • Key filter fields: filters.jobTitles, filters.seniority (VP/Director/Manager/Senior/Entry/Intern), filters.industries, filters.departments, filters.companyDomains, filters.employeeRanges, filters.personalCountries, filters.personalStates, filters.personalCities, filters.organizationCountries, filters.organizationStates, filters.organizationCities, pagination.page, pagination.limit. Use personal* for the contact’s location and organization* for company HQ. A person’s location is not necessarily their employer’s HQ. Use title terms like CEO, CTO, or Founder for C-level searches. do not pass C-Level as a Dropleads seniority value — Dropleads’ own API docs list it, but live validation rejects it. filters.seniorityExclude and filters.departmentsExclude take the same exact values as their include twins.

​
Filter best practices

All Dropleads filters nest under the filters object. Pagination nests under pagination. The canonical payload shape:
Quick reference — correct filter keys:

​
Exclude filters use the same vocabulary as their include twin

seniorityExclude and departmentsExclude accept the same values as seniority and departments. Prime-DB silently ignores an unknown exclude value. It can still return HTTP 200 and change the result set because the filter key exists. Deepline instead rejects unknown values with HTTP 422. Also note that sending seniorityExclude at all drops leads that carry no seniority in Prime-DB, so it narrows results beyond the levels you name. On a sephora.com sample: 1514 leads with no seniority filter, 1058 with all six levels included, 94 with all six excluded.

​
Geo filters are best-effort, not verified

Dropleads location filters match self-reported LinkedIn location text. They do not verify a contact’s actual location. This applies to personalCountries, personalStates, personalCities, organizationCountries, organizationStates, and organizationCities. Check the returned location before accepting a match:
  • City filters can return mismatches. personalCities can return contacts outside the requested city or country. A US-city filter can return a non-US contact. Country and state filters are more reliable, but still require review.
  • Person vs. company location are different fields. personal* filters the contact’s own location. organization* filters the company HQ. Don’t conflate them — filtering a remote employee by company HQ city (or vice versa) drops or leaks legitimate matches.
  • Verify location when precision matters. Combine personalCountries and personalStates with personalCities. Then check returned country, state, and city values. Exclude mismatches before further enrichment. A filter alone does not prove location.

​
2) Escalate paid calls only for shortlisted targets

  • Run dropleads_email_finder for contacts that passed the discovery pass.
  • Run dropleads_mobile_finder only when phone is required for the workflow.
  • For larger or uncertain authorized enrichment, use a small representative pilot and check quality before scaling. Do not add a pilot run or repeat approval for a small supplied Play. inspect its existing results without paid repair.

​
3) Gate outbound with verifier status

  • Treat invalid, catch_all, and unknown as non-send by default.
  • Treat valid as the only status that passes automatic send gates.
  • Respect credits_charged in responses for post-execution billing accuracy.

​
4) Practical sequencing

  1. Count segment (dropleads_get_lead_count).
  2. Sample segment (dropleads_search_people).
  3. Pre-score titles with run_javascript if looking for a specific profile (e.g. founders, GTM engineers).
  4. Validate work history and signals against data from an authorized source or a user-provided export.
  5. Extract signals with run_javascript from that data (e.g. founder detection, hiring signals).
  6. Enrich emails via waterfall (dropleads_email_finder first, then other providers).
  7. Verify candidate emails (dropleads_email_verifier or leadmagic_email_validation).
  8. For larger or uncertain work, expand within the authorized scope after the sample quality is confirmed. This sequence is planning guidance, not a requirement to run extra discovery or enrichment when inspecting a supplied Play or its results.

​
5) Account discovery boundary

For account-based pipelines, start with a company-native source that returns account domains as first-class results. Feed those domains into Dropleads via filters.companyDomains to find contacts at known accounts. Dropleads may include companyDomain on returned people, but it is not guaranteed enough to be the join key that creates the account universe.

​
Find an applicable action

Confirm your effective workspace, then search the live catalog:
Search returns candidates. Check the returned provider and operation rather than selecting a similar title automatically.

​
Inspect the selected contract

Replace <returned-tool-id> with the identifier returned by discovery:
These commands do not execute the selected provider action. Read its required inputs, supported access mode, pricing unit, outputs, and limits. A connection does not establish that every action supports BYOK. Follow the provider-specific requirements above and the live action contract.

​
Prepare one reviewed input

Use one authorized record that matches the inspected schema. Preserve its source identity and define the result you will accept. Open the action reference for its payload and response shape. Provider-backed execution can incur usage or external effects. For reusable logic, follow Write Plays. For direct-call recovery, use Tool execution recovery.
Continue only when the workspace, provider, required fields, acceptance rule, and applicable price are understood. Keep unavailable access separate from no-result evidence.