# People search

> Find professional profiles by role, company, name or description.

`people_search` finds people’s professional profiles by role, company, name or a description, for example title “Head of Security” at company domain `stripe.com`, or “AI safety researchers in London”. It returns name, title, company, location and LinkedIn URL where known. Give at least one of `query`, `company_domain`, `title` or `name`. To look up one profile from its LinkedIn URL, use [`people_enrich`](https://clonvo.com/docs/people-enrich.md).

Call it with `POST /v1/tools/people_search`, or as `people_search` over [MCP](https://clonvo.com/docs/mcp.md).

## Arguments

-   `query` string
    
    The people to find, described in words: role, seniority, industry, place.
    
-   `company_domain` string
    
    Their employer’s website domain, e.g. stripe.com. Use a bare domain such as example.com (no scheme, path or wildcard).
    
-   `title` string
    
    A job title, e.g. "Head of Tax".
    
-   `name` string
    
    A person’s full name, to find their profile.
    
-   `location` string
    
    Where they are, e.g. "London, United Kingdom".
    
-   `keywords` string\[\]
    
    Skills or topics their profile should mention.
    
-   `max_results` integer
    
    How many people to return (1–25, default 10).
    

## Example

```bash
curl https://api.clonvo.com/v1/tools/people_search \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "arguments": { "title": "Head of Developer Relations", "company_domain": "example.com", "max_results": 1 } }'
```

```json
{
  "id": "gen-01M6A4D3F5H7K9M1P3R5T7V9X1",
  "tool": "people_search",
  "provider": "clonvo",
  "result": {
    "people": [
      {
        "name": "Jane Doe",
        "title": "Head of Developer Relations",
        "company": "Example Inc.",
        "company_domain": "example.com",
        "location": "London, United Kingdom",
        "linkedin_url": "https://www.linkedin.com/in/jane-doe",
        "url": null,
        "summary": "Developer relations lead for an API platform; previously a backend engineer."
      }
    ]
  },
  "usage": { "cost": 0.009, "charged": 0.00918, "is_byok": false }
}
```

## Result

| Field | Description |
| --- | --- |
| `people[]` | The people found, each with the [person fields](#person-fields) below. |
| `notes` | Present when the provider handled an argument differently, for example a filter it couldn’t apply. |

The fields around `result` (`id`, `tool`, `provider`, `usage`) are the same for every tool; see [Calling tools](https://clonvo.com/docs/calling-tools.md#response).

## Person fields

`people_search` and `people_enrich` return people with these fields, whichever provider found them. A field the provider doesn’t know is `null`.

| Field | Description |
| --- | --- |
| `name` | The person’s name. Always set. |
| `title` | Their current job title. |
| `company` | Their current employer. |
| `company_domain` | The employer’s website domain. |
| `location` | Where they are. |
| `linkedin_url` | Their LinkedIn profile. |
| `url` | A profile or page about the person, when it isn’t the LinkedIn URL. |
| `summary` | A one-paragraph summary or headline, when the provider gives one. |

Clonvo never returns email addresses or phone numbers, even when a provider sends them.

## Notes

-   Results can differ slightly between providers: field coverage depends on the provider that served the call, and a filter it can’t apply is listed in `notes`.
-   Some providers price people searches per result returned, so `max_results` affects the cost. On Clonvo credits the cap for the call grows with `max_results`; see [Tool billing](https://clonvo.com/docs/tool-billing.md#on-clonvo-credits).
-   Company and people lookups are never stored as [web tool queries](https://clonvo.com/docs/privacy.md#web-tool-queries).