# Manual search

> Filter the Happierleads contact database by job title, seniority, industry, location and company size, then add the people you want to your leads.

Every section below does the same job: in the dashboard (Guide), from your code (API) or through an AI assistant (MCP).

## Guide — In the dashboard

Source: /docs/leads/prospector/search-prospects/manual-search

Manual search finds people who aren’t on your website yet. Set filters, see who matches, add the ones you want. Each person you add costs **1 credit**, charged only when their email verifies. Looking is free.

<DemoFrame guide="prospector-manual" to="/identify/{workspace}?tab=prospector" />

1. **Leads → Prospector → Manual search.**
2. **Filter** by job title, seniority, industry, location (the company’s headquarters) and company size.
3. **Tick** the people you want, then **Add N to Leads**.
4. **Export:** Export to CSV → Export from: Prospector.

Want new matches every day instead? Use [Auto Search](/docs/leads/prospector/search-prospects/auto-search).

### Every control on this screen [#every-control-on-this-screen]

Every button, field and switch, with what it does.

<ScreenControls screens={["leads-prospector", "leads-manual-search", "leads-search-database"]} />


---

## API — From your code

Source: /docs/leads/prospector/search-prospects/manual-search/api

Two REST endpoints on `https://rest-admin.happierleads.com`, authenticated with `?privateKey=YOUR_KEY`, like every other endpoint. Your keys are in **Integrations → API** (see [Authentication](/docs/authentication)).

| Endpoint | Does | Cost |
| --- | --- | --- |
| `POST /admin/prospector/people/search` | Finds people by title, seniority, industry, location and company size | Free |
| `POST /admin/prospector/people/reveal` | Shows the email and phone of one person | 1 credit |

<Endpoints ops={["POST /admin/prospector/people/search", "POST /admin/prospector/people/reveal", "POST /v3/prospector/people/find-email"]} />

<ApiPlayground
  ops={["POST /admin/prospector/people/search", "POST /admin/prospector/people/reveal", "POST /v3/prospector/people/find-email"]}
  path="/admin/prospector/people/search"
  tool="search_people"
  args={`{
  "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9",
  "query": {
    "titles": ["CEO", "Founder"],
    "industries": ["Computer Software"],
    "locations": ["United States"],
    "employeesMin": 10,
    "employeesMax": 200,
    "count": 25
  }
}`}
/>

### Use case: find people [#use-case-find-people]

`POST /admin/prospector/people/search` with `websiteId` (from `GET /admin/websites`) and a `query`; every filter is optional ([all filters](/docs/mcp/tools/search-people)). Searching never returns emails.

```json title="Response"
{
  "httpStatus": 200,
  "people": [
    {
      "profileId": "3cbd7f0d47879822dd5f722ab6dfac85",
      "companyProfileId": "4a837e150440103296e07fd46e3f1ff1",
      "name": "Ava Thompson",
      "firstName": "Ava",
      "lastName": "Thompson",
      "position": "Founder",
      "jobTitle": "Founder",
      "jobTitles": ["Founder"],
      "seniority": "Owner",
      "department": "Executive",
      "company": "Northwind Analytics",
      "companyName": "Northwind Analytics",
      "companyDomain": "northwind-analytics.example",
      "companyLocation": { "city": "Austin", "country": "United States", "countryCode": "US" },
      "companyInfo": {
        "logo": null,
        "industry": "Computer Software",
        "sector": "Technology",
        "employees": "42",
        "revenue": "$1M - $10M",
        "description": null,
        "foundedYear": 2018,
        "tags": []
      },
      "linkedin": "https://www.linkedin.com/in/sample-ava-thompson-00",
      "emailStatus": null,
      "hasEmail": false,
      "hasPhone": true
    }
  ],
  "total": 6,
  "note": "locations filters on the company headquarters. jobTitle is the position that matched your titles filter; jobTitles lists every position the person holds. companyLocation / companyDomain are null when we do not hold that employer yet."
}
```

Next page: pass `query.page`.

### Use case: get their email [#use-case-get-their-email]

`POST /admin/prospector/people/reveal` with `websiteId` and a `profileId` from the search. **1 credit** when we hold an email or phone, nothing when we don’t.

```bash
curl -X POST "https://rest-admin.happierleads.com/admin/prospector/people/reveal?privateKey=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9", "profileId": "71e392938b6bfb2a8f112058d0afc3f1" }'
```

```json title="Response"
{
  "httpStatus": 200,
  "profileId": "71e392938b6bfb2a8f112058d0afc3f1",
  "businessEmail": "noah.ramirez@northwind-analytics.example",
  "emailStatus": "valid",
  "phone": null,
  "creditsCharged": 1,
  "status": "revealed",
  "remainingCredits": 498
}
```

### When it fails [#when-it-fails]

The HTTP status says why: `401` missing or wrong key, `402` no credits, `403` plan without Prospector, `429` more than one search per second or the plan’s search limit is used up.


---

## MCP — AI agents

Source: /docs/leads/prospector/search-prospects/manual-search/mcp

<Tools names={["search_people", "reveal_contact", "find_contact_email", "create_contact", "verify_contact"]} />

Connect the [MCP server](/docs/mcp#quickstart), then just ask. Searching is free; revealing an email costs 1 credit.

<McpDemo />

### Use case: find people [#use-case-find-people]

> Find 25 SaaS founders in the United States at companies with 10–200 employees.

<McpToolCall name="search_people">

```json
{
  "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9",
  "query": {
    "titles": ["CEO", "Founder"],
    "industries": ["Computer Software"],
    "locations": ["United States"],
    "employeesMin": 10,
    "employeesMax": 200,
    "count": 25
  }
}
```

</McpToolCall>

### Use case: narrow it down [#use-case-narrow-it-down]

> Only heads of marketing at software companies in Germany with more than 50 employees.

<McpToolCall name="search_people">

```json
{
  "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9",
  "query": {
    "titles": ["Head of Marketing"],
    "industries": ["Computer Software"],
    "locations": ["Germany"],
    "employeesMin": 50
  }
}
```

</McpToolCall>

### Use case: get emails and start outreach [#use-case-get-emails-and-start-outreach]

> Reveal the emails for the first five and add them to my campaign “Q4 SaaS founders”.

It calls `reveal_contact` once per person (1 credit each), then `list_campaigns` and `add_prospect_to_campaign`. Turn on tool approval in your assistant to confirm each paid call.