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

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

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

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

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

{
  "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
}