# Lead database

What the in-app Lead database searches, how emails are verified, what a search costs, and which parts are available over MCP and REST.

The Lead database is the in-app search that finds people to add to a campaign. It is separate from your own leads, which the REST API creates and reads.

## Searching

A search filters on job titles, seniority, locations, industries, company names, company domains and company size. A page holds at most 25 results.

Results are added to a campaign in 1 of 2 modes: email and LinkedIn, where an email is looked up for each person, or LinkedIn only, where no email lookup runs. A bulk add takes up to 500 leads at a time.

An email is kept only when the lookup rates it deliverable, high-probability or catch-all. Anything less is discarded, so a lead added in email mode either has an email that passed that check or has none.

## What it costs

A search costs about 0.8 credits per result returned, so a page of 25 is about 21 credits; a short page is refunded to what was returned. Finding an email costs about 3.3 credits per lead, reserved when the add starts and refunded when no email is found. LinkedIn-only adds cost only the search. [Credits](https://docs.versionseven.ai/guides/credits) explains what a credit is and how balances work.

## From a connected assistant

Two tools on the MCP server expose the database to a connected assistant, and they are the only programmatic way in:

- `find_leads` runs a search and returns a page of results.
- `add_leads_from_search` adds matches to a campaign, in `email` or `linkedin_only` mode.

Both quote their cost before the host asks you to approve, and both are refused at a zero balance and past the trial's lead cap; `add_leads_from_search` then answers a `suggested_count` that fits. [Connect your AI](https://docs.versionseven.ai/guides/connect-your-ai#credits) has the details, and [Where lead data comes from](https://docs.versionseven.ai/guides/connect-your-ai#where-lead-data-comes-from) covers the licence terms for what the search returns.

## Bringing your own leads by REST

The REST API has no search endpoint. It works with leads you bring:

| Task | Endpoint |
| - | - |
| Create a lead, or enrol an existing one in a campaign | [`POST /v1/leads`](https://docs.versionseven.ai/api-reference/leads/create-lead) |
| List your leads, filtered by campaign, industry, title, size or a search term | [`GET /v1/leads`](https://docs.versionseven.ai/api-reference/leads/list-leads) |
| Retrieve a lead | [`GET /v1/leads/{lead_id}`](https://docs.versionseven.ai/api-reference/leads/retrieve-lead) |
| Update a lead | [`PATCH /v1/leads/{lead_id}`](https://docs.versionseven.ai/api-reference/leads/update-lead) |
| Delete a lead, or remove it from one campaign | [`DELETE /v1/leads/{lead_id}`](https://docs.versionseven.ai/api-reference/leads/remove-lead-from-campaign) |

A lead needs a first name, a last name, and an email or LinkedIn URL. Leads added from the database appear in these endpoints like any other lead once they're in a campaign.

Two campaign fields touch the database from REST: [`PATCH /v1/campaigns/{campaign_id}`](https://docs.versionseven.ai/api-reference/campaigns/update-campaign) replaces a campaign's saved `lead_database_filters` and its `refill_policy` (send `{"enabled": false}` to turn auto-refill off), and [`GET /v1/campaigns/{campaign_id}/queue`](https://docs.versionseven.ai/api-reference/campaigns/get-campaign-queue) reports the most recent lead-database refill alongside the backlog and days of runway. Neither runs a search.