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

# Free people search

> Search for people with search_contact. Learn the inputs, included usage, pagination, results and Play syntax.

Deepline-native people search returns names, job titles, LinkedIn profiles and company information. Use the tool `search_contact` to find people at a company, look up a LinkedIn profile, or search across a filtered set of companies. Email and phone enrichment are separate operations.

## Use it in Claude Code

After [installing Deepline](https://deepline.com/docs/quickstart.md) and signing in, paste this prompt into Claude Code. Replace the company domain and role for your search.

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
/deepline-gtm Find up to 5 engineering managers at stripe.com using Deepline-native people search. Use free_only: true. Return each person's name, current title and LinkedIn URL. Do not use paid providers or enrich emails or phone numbers.
```

> [!NOTE]
>
> Title matching can include related roles. Review the returned titles before
> using the list. The prompt limits native search to the included allowance;
> Claude usage has its own pricing.

## Use the CLI

Inspect the tool in your workspace with `deepline tools describe search_contact`, then run a small search:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute search_contact --input '{
  "domain": "stripe.com",
  "title_filters": [{"name": "eng managers", "filter": "\"Engineering Manager\""}],
  "page_size": 5,
  "free_only": true
}' --json
```

The alias `deepline_native_search_contact` resolves to the same native search and allowance.

> [accordion] What did the tested prompt return?
>
> On November 12, 2026, Claude CLI with Deepline CLI 0.3.394 returned five
> profiles for zero Deepline credits. Three matched the requested role; two were
> engineering program managers. This is one bounded example, not a coverage
> benchmark. Your results may differ.

## Call the endpoint over HTTP

Send a workspace API key to `POST https://code.deepline.com/api/v2/tools/search_contact/execute`. Put the search inputs inside `payload`. Deepline manages provider access; you do not need a separate provider key.

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
curl https://code.deepline.com/api/v2/tools/search_contact/execute \
  -H "Authorization: Bearer $DEEPLINE_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"payload":{"domain":"stripe.com","title_filters":[{"name":"engineering","filter":"Engineering Manager"}],"page_size":5,"free_only":true}}'
```

See [Execute a tool](https://deepline.com/docs/api-reference/execute-tool.md) for the shared response envelope and request options. The upstream provider path `/v1/search/contact` is not the Deepline customer endpoint. `free_only` belongs to Deepline's allowance checks and is not forwarded upstream.

## Included usage and pricing

The free allowance counts returned profiles. A request for five profiles that returns three uses three profiles. Repeated searches can consume allowance again; this is not a count of unique people saved to your workspace.

| Plan | Included profiles per month | Requests per minute |
| - | -: | -: |
| Solo | 5,000 | 10 |
| Team | 200,000 | 30 |
| Scale | 500,000 | 60 |

These are the November plan terms. Earlier plan labels were Pay as you go, Growth and Team, respectively. Availability and workspace-specific entitlements can differ. Run `deepline billing entitlements` for your remaining allowance, reset time, rate limit and overage price. The workspace's returned terms take precedence.

Solo resets each UTC calendar month. Paid plans reset on their monthly billing cycle. On these plans, native search above the allowance costs 0.05 Deepline credits per returned profile, or $0.005. An additional 1,000 profiles costs $5. Workspaces outside these plan entitlements can have different rates.

Set `free_only: true` on every request that must stay within the included allowance. Deepline reserves the allowance before making the search. If fewer profiles remain than the requested page size, it reduces the page size. If none remain, it returns `FREE_ALLOWANCE_EXHAUSTED` without a paid search. If native search is not included for the workspace, it returns `FREE_PROVIDER_UNAVAILABLE`.

Omitting `free_only` or setting it to `false` permits paid overage. The flag covers this search only. Other providers, enrichment, agent usage and Play compute have their own charges. An uncertain provider timeout can retain a reservation while Deepline reconciles it; inspect your allowance before retrying a large request.

## Choose a search mode

### Search at one company or look up one profile

Provide at least one of `domain`, `company_linkedin`, `company_name` or `contact_linkedin`. Prefer a domain or LinkedIn company URL when the company name is ambiguous. A company name needs at least three characters; use a domain for shorter names.

For a known company, the free `company_titles` tool returns its current title roster. Pass selected titles as `title_lists`. Check the returned titles because matching is not exact.

### Search across companies

A company-set search requires all of the following:

* At least one nonempty company filter: `company_location_countries`, `company_industries` or `company_employee_ranges`.
* A date in `experience_start_date` or `experience_start_date_new_hire`.
* A nonempty `title_filters` or `title_lists` array.

For example, this input searches for sales leaders at US companies with 51 to 200 employees whose current role started on or after January 1, 2026:

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "company_location_countries": ["United States"],
  "company_employee_ranges": ["51-200"],
  "experience_start_date": "2026-01-01",
  "title_filters": [
    {
      "name": "sales leadership",
      "filter": "VP Sales OR Head of Sales OR Director of Sales"
    }
  ],
  "page_size": 25,
  "free_only": true
}
```

The date constrains the results. This mode does not produce an unrestricted list of everyone in a market. To search company by company without a role-start date, first use [free company search](https://deepline.com/docs/free-company-search-database.md) to find domains, then call `search_contact` for each domain. The company database and people search use different industry lists.

## Input reference

Unknown input fields are rejected. All fields are optional individually, but a request must satisfy one of the search modes above.

| Field | Type | Meaning and limits |
| - | - | - |
| `free_only` | boolean | Use only the remaining included allowance. Omitted or false allows paid overage. |
| `contact_linkedin` | string | Person's LinkedIn URL or slug, 3 to 500 characters. |
| `domain` | string | Company domain, 4 to 500 characters. Do not pass an email address. |
| `company_linkedin` | string | LinkedIn company URL or slug, 3 to 500 characters. |
| `company_name` | string | Company name, 3 to 500 characters. |
| `title_filters` | object array | Up to five ordered objects with `name` and a Boolean `filter` expression. Use role names with `OR`, `AND` or `NOT`. |
| `title_lists` | object array | Up to five objects with `name` and `titles`, an array of strings. Maximum 120 titles across all lists. Used when `title_filters` is absent. Matching can include related titles. |
| `departments` | string array | Department names from the list below. |
| `seniorities` | string array | `Director`, `Manager`, `Senior`, `Entry` or `Partner`. Head maps to Director; Intern and Junior map to Entry. Use title filters for VP, C-level, founder and owner roles. |
| `location_countries` | string array | Person's country of residence. Up to 50 names, each 1 to 200 characters. |
| `company_location_countries` | string array | Company headquarters country, with the same limits as `location_countries`. |
| `company_industries` | string array | Up to 50 categories from the supported industry list. |
| `company_employee_ranges` | string array | Up to eight ranges from the list below. |
| `experience_start_date` | string | Current role started on or after this date, in `YYYY-MM-DD` format. |
| `experience_start_date_new_hire` | string | New hires whose current role started on or after this date, in `YYYY-MM-DD` format. |
| `included_names` | string array | Up to 100 names. Matches prefixes, so pass full names and check the returned names. |
| `excluded_names` | string array | Up to 100 names to exclude. |
| `headline` | string | Filter against a person's headline or bio, 3 to 500 characters. |
| `page_number` | integer | Starts at 1. Maximum 100. Defaults to 1. |
| `page_size` | integer | 1 to 250. Defaults to 10. `free_only` can reduce it to the remaining allowance. |
| `custom_fields` | object | Up to 16 metadata keys with string, number or Boolean values, echoed in finder responses. |

Accepted departments are `Leadership`, `Engineering`, `Product Management`, `Sales`, `Marketing`, `Customer Success`, `Finance`, `Accounting`, `Legal`, `Human Resources`, `Information Technology`, `Operations`, `Education` and `Other`.

Accepted employee ranges are `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000` and `10001+`.

Use full names from the [supported countries](https://deepline.com/people-search-countries.txt) and categories from the [supported industries](https://deepline.com/people-search-industries.txt). `US` is accepted, but other country codes are rejected. Deepline normalizes names such as Czechia and Türkiye to the accepted spelling. There is no country autocomplete endpoint for this tool.

## Results and pagination

The tool completes synchronously. It does not require polling. The provider payload contains `output.persons`; the Deepline Play getter is `result.extractedLists.people.get()`. It returns `null` on a miss, so handle that before iterating.

Profiles can include `first_name`, `last_name`, `title`, `linkedin_url`, `linkedin_id`, `seniority`, `department`, `location`, `country`, `company_name`, `company_domain`, `company_linkedin_id`, `about` and `experiences`. Fields may be missing or null. Inspect current experience records before assuming a person still works at the target company.

Use `linkedin_url` to deduplicate people. The result's `id` changes between requests and is not a stable person identifier. Email and phone fields are intentionally redacted. Redaction does not mean that contact data is available for purchase.

For a small lookup, start with a few results and inspect their quality. For a larger collection, use `page_size` of at least 25, increment `page_number` and continue through short pages until an empty page. The provider removes duplicates and invalid records after paging, so a short page is not proof that results have ended. Small pages can even be empty mid-results. Keep the same filters and deduplicate by LinkedIn URL across pages. Stop at the 100-page limit or when the free allowance is exhausted.

## Put the search in a Play

Save this as `people-search.play.ts`. The company domain becomes the Play input. This example performs one search and returns the profiles for the next step. It uses the current SDK's default async function syntax. Older CLI releases that require `definePlay` must be updated before checking or running this file.

```typescript theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import deepline from 'deepline';

export default async function (input: { domain: string }) {
  const search = await deepline.tools.execute({
    id: 'people_search',
    tool: 'search_contact',
    input: {
      domain: input.domain,
      title_filters: [{ name: 'engineering', filter: 'Engineering Manager' }],
      page_size: 5,
      free_only: true,
    },
    description: 'Find engineering managers at this company.',
    staleAfterSeconds: 0,
  });
  return { people: search.extractedLists.people.get() };
}
```

Validate the file without running it:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline plays check people-search.play.ts
```

When you are ready to run the Play:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline plays run people-search.play.ts --input '{"domain":"stripe.com"}'
```

`staleAfterSeconds: 0` requests fresh execution. `free_only` prevents search overage, but does not make Play compute or later enrichment steps free.

## Errors

| Error | What to do |
| - | - |
| `FREE_ALLOWANCE_EXHAUSTED`, HTTP 422 | Wait for the reset or explicitly permit paid overage by removing `free_only`. |
| `FREE_PROVIDER_UNAVAILABLE`, HTTP 422 | Check workspace entitlements. Do not silently switch to a paid provider. |
| Input validation, HTTP 422 | Check the search-mode requirements, field names, array shapes, enum values and limits. Validation happens before provider execution. |
| Rate limit, HTTP 429 | Respect the returned `retry-after` header. The limit applies across calls in the workspace. |
| Provider error or timeout | Inspect the error and remaining allowance before retrying. A timeout is not proof that the provider did not execute the search. |

Zero returned profiles do not incur a per-profile search charge. Do not treat an empty result as an input validation error.

## Enrich selected people or try another provider

To look for an email, pass a selected profile's `linkedin_url` as `linkedin` to `enrich_contact`. Set `include_phones: true` if you also want phone data, or use `enrich_phone` for phone-only enrichment. Describe the tool before running it to see current pricing. There is no search unlock flag or reveal-by-person-ID endpoint.

If native search misses the people you need, use the [people-search provider directory](https://deepline.com/features/people-search#providers) to choose a fallback. These tools have separate coverage and prices; the native profile allowance does not cover their charges. Review a small sample and approve the price before expanding a paid search.


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