# Search People

Searches LinkedIn live and returns one page of people, up to about 25 per page. Combine as many filters as you like: every filter narrows the result, and values inside one list are alternatives (`["CFO", "CEO"]` means CFO *or* CEO).

Searches LinkedIn live and returns one page of people, up to about 25 per page. Combine as many filters as you like: every filter narrows the result, and values inside one list are alternatives (`["CFO", "CEO"]` means CFO *or* CEO).

At least one filter is required. Page through the result with `next_cursor`, which keeps the result stable from page to page. The source stops at page 100.

Every list filter takes 1 to 20 values of at most 200 characters. A value cannot contain a comma.

## Authentication

Send your API key as a Bearer token: `Authorization: Bearer gtk_…`. Create the key under **API Access → API Keys**. A missing, invalid or revoked key is **401**, including while an API is closed. A valid key while the Signals API or the Company API is closed for your organization answers **404**, the same body as an unknown path. Every response includes `FounderMCP-Api-Version` and `FounderMCP-Request-Id`.

### Body parameters

- **`keywords`** `string` — Free text, matched like the LinkedIn search box: name, headline, company.
- **`current_job_titles`** `string[]` — Job titles the person holds now, e.g. `["CFO", "Head of Finance"]`. Title matching is fuzzy: results are ranked by how well the title matches, so people with a different title can still appear. Add `seniority_levels` or `functions` for a strict filter.
- **`past_job_titles`** `string[]` — Job titles the person held before.
- **`current_companies`** `string[]` — Where the person works now: company names or LinkedIn company URLs (`https://www.linkedin.com/company/acme`). URLs are the most precise.
- **`past_companies`** `string[]` — Where the person worked before; same format as `current_companies`.
- **`exclude_current_companies`** `string[]` — Leave out people who work at these companies now.
- **`locations`** `string[]` — Where the person is based: country, region or city names in English, e.g. `["Belgium", "Amsterdam"]`.
- **`exclude_locations`** `string[]` — Leave out people based here.
- **`schools`** `string[]` — Schools or universities the person attended.
- **`first_names`** `string[]` — Exact first names.
- **`last_names`** `string[]` — Exact last names.
- **`seniority_levels`** `string[]` — Seniority of the current position. One of: `in_training`, `entry_level`, `senior`, `strategic`, `entry_level_manager`, `experienced_manager`, `director`, `vice_president`, `cxo`, `owner_partner`.
- **`exclude_seniority_levels`** `string[]` — Leave out these seniority levels. One of: `in_training`, `entry_level`, `senior`, `strategic`, `entry_level_manager`, `experienced_manager`, `director`, `vice_president`, `cxo`, `owner_partner`.
- **`functions`** `string[]` — Department of the current position. One of: `accounting`, `administrative`, `arts_and_design`, `business_development`, `community_and_social_services`, `consulting`, `education`, `engineering`, `entrepreneurship`, `finance`, `healthcare_services`, `human_resources`, `information_technology`, `legal`, `marketing`, `media_and_communication`, `military_and_protective_services`, `operations`, `product_management`, `program_and_project_management`, `purchasing`, `quality_assurance`, `real_estate`, `research`, `sales`, `customer_success_and_support`.
- **`exclude_functions`** `string[]` — Leave out these departments. One of: `accounting`, `administrative`, `arts_and_design`, `business_development`, `community_and_social_services`, `consulting`, `education`, `engineering`, `entrepreneurship`, `finance`, `healthcare_services`, `human_resources`, `information_technology`, `legal`, `marketing`, `media_and_communication`, `military_and_protective_services`, `operations`, `product_management`, `program_and_project_management`, `purchasing`, `quality_assurance`, `real_estate`, `research`, `sales`, `customer_success_and_support`.
- **`company_headcounts`** `string[]` — Size of the current employer, as a headcount range. One of: `self-employed`, `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`.
- **`years_of_experience`** `string[]` — Total years of work experience. One of: `less_than_1`, `1_to_2`, `3_to_5`, `6_to_10`, `more_than_10`.
- **`years_at_current_company`** `string[]` — Years at the current employer. One of: `less_than_1`, `1_to_2`, `3_to_5`, `6_to_10`, `more_than_10`.
- **`profile_languages`** `string[]` — Language of the LinkedIn profile. One of: `ar`, `cs`, `da`, `de`, `en`, `es`, `fr`, `in`, `it`, `ja`, `ko`, `ms`, `nl`, `no`, `pl`, `pt`, `ro`, `ru`, `sv`, `tl`, `tr`, `zh`.
- **`recently_changed_jobs`** `boolean` — Only people who started a new position in the last 90 days.
- **`posted_on_linkedin`** `boolean` — Only people who posted on LinkedIn in the last 30 days.
- **`page`** `integer` — Page to fetch, 1 to 100. Defaults to 1.
- **`cursor`** `string` — The `next_cursor` of the previous response. Takes precedence over `page`.
- **`max_credits`** `integer` — Stop before this call costs more than this. A page with results is 25 credits, however many people it holds, so below that the call is `402` `max_credits_exceeded` and nothing is searched. Accepted when the Signals API is open for your organization; otherwise the field is unknown.

## Response

- **`results`** `object[]` — The people on this page. See the fields below.
- **`results[].linkedin_url`** `string` — Profile URL. Search returns the member-id form (`/in/ACwAA…`); it works as input for Enrich People, which returns the public URL.
- **`results[].linkedin_id`** `string | null` — LinkedIn member id.
- **`results[].first_name`** `string | null` — First name.
- **`results[].last_name`** `string | null` — Last name.
- **`results[].full_name`** `string | null` — First and last name together.
- **`results[].picture_url`** `string | null` — Profile photo. LinkedIn photo URLs expire after a few weeks.
- **`results[].location`** `object` — `text`: where the person is based, as LinkedIn shows it.
- **`results[].current_positions`** `object[]` — Positions held now: `title`, `company_name`, `company_linkedin_url`, `started_on` (`year`, `month`), `tenure_at_position` and `tenure_at_company` (`years`, `months`).
- **`pagination`** `object` — `page`, `total_pages`, `total_results` (as reported by the source) and `next_cursor` (null on the last page).
- **`credits_used`** `integer` — Credits this call used: 25 for a page with results, however many people it holds, and 0 for an empty page. When rows carry `credits_charged`, the first row carries the page and the other rows 0.

## Credits

1 credit per person, charged per page of 25: a page with results is 25 credits, an empty page is free Errors and empty lookups are free. A call that spent credits puts that number in `credits_used`, in `X-Credits-Used` and in `X-Credits-Charged`. When the wallet can be read, the response also sends `X-Credits-Remaining`.

## Errors

- **400** `invalid_request` — The body is not valid JSON, a field is unknown or has the wrong type, or a value is not allowed.
- **401** `authentication_error` — The Authorization header is missing, or the key is unknown or revoked.
- **403** `permission_error` — API access is not part of your plan, or your account is suspended.
- **429** `rate_limit_error` — More than 60 requests per minute, or more than 3 at the same time, on one key. Wait for the Retry-After header.
- **429** `daily_limit_reached` — The request could take your organization over its daily credit limit. The limit resets at midnight (Europe/Brussels).
- **502** `upstream_error` — The data source did not answer. Retry later.
- **503** `service_unavailable` — The API is temporarily unavailable. Retry later.
- **500** `internal_error` — Something went wrong on our side.
- **402** `max_credits_exceeded` — max_credits is below one row. Accepted only when the Signals API is open; otherwise the field is unknown and the call is 400.

## Example

### cURL

```bash
curl -X POST "https://foundermcp.dev/api/v1/person/search" \
  -H "Authorization: Bearer $FOUNDERMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "current_job_titles": [
      "CFO",
      "Head of Finance"
    ],
    "locations": [
      "Belgium"
    ],
    "company_headcounts": [
      "51-200",
      "201-500"
    ],
    "recently_changed_jobs": true
  }'
```

### JavaScript

```javascript
const response = await fetch('https://foundermcp.dev/api/v1/person/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUNDERMCP_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "current_job_titles": [
      "CFO",
      "Head of Finance"
    ],
    "locations": [
      "Belgium"
    ],
    "company_headcounts": [
      "51-200",
      "201-500"
    ],
    "recently_changed_jobs": true
  })
});
const body = await response.json();
```

### Python

```python
import json
import os
import urllib.request

payload = {
  "current_job_titles": [
    "CFO",
    "Head of Finance"
  ],
  "locations": [
    "Belgium"
  ],
  "company_headcounts": [
    "51-200",
    "201-500"
  ],
  "recently_changed_jobs": true
}

request = urllib.request.Request(
    "https://foundermcp.dev/api/v1/person/search",
    headers={
    "Authorization": f"Bearer {os.environ['FOUNDERMCP_API_KEY']}",
    "Content-Type": "application/json"
    },
    data=json.dumps(payload).encode(),
    method="POST",
)
with urllib.request.urlopen(request) as response:
    body = json.load(response)
```

### Example response

```json
{
  "results": [
    {
      "linkedin_url": "https://www.linkedin.com/in/ACwAAExample123",
      "linkedin_id": "ACwAAExample123",
      "first_name": "Jane",
      "last_name": "Example",
      "full_name": "Jane Example",
      "picture_url": null,
      "location": {
        "text": "Ghent, Flemish Region, Belgium"
      },
      "current_positions": [
        {
          "title": "Chief Financial Officer",
          "company_name": "Acme Analytics",
          "company_linkedin_url": "https://www.linkedin.com/company/acme-analytics",
          "started_on": {
            "year": 2026,
            "month": 7
          },
          "tenure_at_position": {
            "years": 0,
            "months": 2
          },
          "tenure_at_company": {
            "years": 0,
            "months": 2
          }
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "total_pages": 6,
    "total_results": 131,
    "next_cursor": "eyJwIjoyfQ"
  },
  "credits_used": 25
}
```