Oct 21, 2024 • Español · Français · Deutsch

People Search API: Find People and Their Work Emails Programmatically

Read time: 2 Minutes, 14 Seconds

2026-10-19 [Initally Posted on: 2024-10-21]

Query the people we hold, with their role, employer and work email where we have one, from your own code with a single authenticated request.

This guide covers the API only. To search, reveal and send from the web app, see Find People and People & Reveals. If you do not have an API key yet, the API Quickstart Guide walks through getting one.

The Endpoint

GET https://thestack.es/api/v1/search/people

Authenticate by sending your key in the X-API-KEY header:

1
2
3
4
curl -G "https://thestack.es/api/v1/search/people" \
     -H "X-API-KEY: {your_api_key}" \
     --data-urlencode "search_query=chief financial officer" \
     --data-urlencode "country=Spain"

Parameters

Parameter	Type	Description
`search_query`	text	Keywords matched against names, headlines and biographies, e.g. `head of sales` or a full name.
`country`	text, repeatable	Full country name, e.g. `country=Spain&country=Portugal`.
`company_name`	text, repeatable	Exact employer name, e.g. `company_name=Acme Analytics`.
`website`	text, repeatable	Exact employer website.
`is_investor`	`true`	Only people who are the primary contact of an investor.
`page`	integer	Page number, starting at 1.
`per_page`	`10` or `15`	Results per page. Default `15`.
`order`	`asc` or `desc`	By last update. Default `desc`, newest first.

Repeat a parameter to match any of its values. Different parameters combine: country=Spain&company_name=Acme Analytics means people at Acme Analytics in Spain.

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "data": [
    {
      "id": "ACoAAB1x...",
      "name": "Lucía Navarro",
      "email": "lucia@northwindlabs.io",
      "phone": null,
      "country": "Spain",
      "city": null,
      "company_name": "Northwind Labs",
      "company_website": "https://northwindlabs.io",
      "biography": "Building developer tooling...",
      "primary_position": "Head of Engineering at Northwind Labs",
      "school_name": null,
      "linkedin_url": "https://www.linkedin.com/in/lucia-navarro",
      "updated_at": "2026-10-19"
    }
  ],
  "has_more": true,
  "total": 128
}

email is filled in only when we already hold a work address for the person; otherwise it is null. Revealing new addresses happens in the web app, through the browser extension.
has_more says whether another page exists, so you can loop until it is false.
total is the number of people matching your filters across all pages.

Status Codes

Code	Meaning
`200`	Results returned.
`400`	A parameter has an invalid value (for example `page=0` or `order=up`).
`401`	The `X-API-KEY` header is missing or the key is not valid.
`403`	You have used all the API requests in your plan for this cycle.
`404`	Nobody matches those filters.

Each successful request counts against your plan’s monthly requests; a 404 does not.

Paging Through Everything

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import requests

url = "https://thestack.es/api/v1/search/people"
headers = {"X-API-KEY": "your_api_key"}
params = {"country": ["Spain", "Portugal"], "search_query": "recruiter", "per_page": 15}

page = 1
while True:
    response = requests.get(url, headers=headers, params={**params, "page": page})
    if response.status_code == 404:
        break
    response.raise_for_status()
    body = response.json()
    for person in body["data"]:
        print(person["name"], person["email"])
    if not body["has_more"]:
        break
    page += 1

Try It in the Browser

Every endpoint, with its parameters, is in the interactive documentation at thestack.es/api/docs: expand Search People, press Try it out, paste your key and send a request.