> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Use DropLeads in Deepline

> Use Prime-DB search/count for contact discovery at known accounts, then run finder/verifier steps only on shortlisted records.

[Human guide: work with your agent →](https://deepline.com/docs/human/providers/dropleads/guide.md)
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:

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "filters": {
    "companyDomains": ["microsoft.com"],
    "jobTitles": ["CTO", "VP Engineering"],
    "seniority": ["VP", "Director"],
    "personalCountries": { "include": ["United States"] }
  },
  "pagination": { "page": 1, "limit": 25 }
}
```

**Quick reference — correct filter keys:**

| Filter | Correct key | Why |
| - | - | - |
| Company | `filters.companyDomains` | Exact domain match for known accounts. Prefer this when you already have domains. do not rely on people-search results to discover a complete account-domain list. `companyNames` does fuzzy substring matching — "Microsoft" pulls in unrelated businesses. |
| Person geo | `filters.personalCountries`, `filters.personalStates`, `filters.personalCities` | Filters the contact's location. Each field uses an `{ "include": [...], "exclude": [...] }` object. |
| Company geo | `filters.organizationCountries`, `filters.organizationStates`, `filters.organizationCities` | Filters the company HQ, not the contact's location. Each field uses an `{ "include": [...], "exclude": [...] }` object. |
| Seniority | `filters.seniority`, `filters.seniorityExclude` | Exact values only: `VP`, `Director`, `Manager`, `Senior`, `Entry`, `Intern`. Use `jobTitles` terms like `CEO`, `CTO`, or `Founder` for C-level searches. |
| Department | `filters.departments`, `filters.departmentsExclude` | Exact values only: `Engineering`, `Sales`, `Marketing`, `Operations`, `Finance`, `HR`, `Product`, `Customer Success`, `Legal`, `IT`. |
| Industry | `filters.industries` | Exact strings from Dropleads. Pilot with a broad search first when unsure. |

#### 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:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline auth status --json
deepline search "DropLeads" --type tools --json
```

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:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline describe <returned-tool-id> --json
```

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](https://deepline.com/docs/sdk-v2/plays.md). For direct-call recovery, use [Tool execution recovery](https://deepline.com/docs/sdk-v2/tool-execution-recovery.md).

> [!TIP]
>
> Continue only when the workspace, provider, required fields, acceptance rule, and applicable price are understood. Keep unavailable access separate from no-result evidence.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.