> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuesday.so/llms.txt
> Use this file to discover all available pages before exploring further.

# People Search

> Search across professional records using a rich set of filters

## Overview

Search for people using advanced filters and criteria. This endpoint allows you to find professionals based on combinations of title, company, location, seniority, and other attributes. Perfect for building targeted prospect lists and conducting market research.

## Authentication

<ParamField header="X-API-KEY" type="string" required>
  Your Tuesday API key
</ParamField>

## Request Parameters

All parameters are optional. Combine them to filter results precisely.

### 📄 Pagination

<ParamField body="page" type="int" default="1">
  Page number
</ParamField>

<ParamField body="per_page" type="int" default="25">
  Results per page (max: 100)
</ParamField>

<ParamField body="include_email" type="string" default="exclude">
  Include email address

  **Options:** `include` | `exclude`

  **Additional Cost:** +2 credits per result when set to `include`
</ParamField>

<ParamField body="include_phone" type="string" default="exclude">
  Include phone number

  **Options:** `include` | `exclude`

  **Additional Cost:** +3 credits per result when set to `include`
</ParamField>

### 👤 Person Filters

<ParamField body="person_titles" type="string[]">
  Current job titles to include

  **Examples:** `["Software Engineer", "Senior Developer"]`
</ParamField>

<ParamField body="person_not_titles" type="string[]">
  Exclude these current job titles
</ParamField>

<ParamField body="person_past_titles" type="string[]">
  Match against past job titles
</ParamField>

<ParamField body="person_seniorities" type="string[]">
  Filter by seniority level

  **Examples:** `["C-Team", "Manager", "Director"]`
</ParamField>

<ParamField body="person_location" type="string[]">
  Current person location

  **Examples:** `["San Francisco", "California", "United States"]`
</ParamField>

<ParamField body="not_person_location" type="string[]">
  Exclude people in these locations
</ParamField>

<ParamField body="person_days_in_current_title_range" type="object">
  Days in current role/title

  **Format:** `{"min": 30, "max": 300}`
</ParamField>

### 🏢 Organization Filters

<ParamField body="q_organization_domains" type="string[]">
  Match organization domains

  **Examples:** `["google.com", "microsoft.com"]`
</ParamField>

<ParamField body="not_q_organization_domains" type="string[]">
  Exclude organizations with these domains
</ParamField>

<ParamField body="organization_location" type="string[]">
  Company HQ/location
</ParamField>

<ParamField body="not_organization_location" type="string[]">
  Exclude companies in these locations
</ParamField>

<ParamField body="organization_industry" type="string[]">
  Include companies in these industries

  **Examples:** `["Technology", "Healthcare", "Finance"]`
</ParamField>

<ParamField body="organization_not_industry" type="string[]">
  Exclude companies from these industries
</ParamField>

<ParamField body="organization_sic_industry" type="string[]">
  Filter by SIC codes

  **Examples:** `["0919"]`
</ParamField>

<ParamField body="organization_not_sic_industry" type="string[]">
  Exclude SIC codes
</ParamField>

<ParamField body="organization_naics_industry" type="string[]">
  Filter by NAICS codes

  **Examples:** `["236117"]`
</ParamField>

<ParamField body="organization_not_naics_industry" type="string[]">
  Exclude NAICS codes
</ParamField>

<ParamField body="organization_revenue_ranges" type="string[]">
  Revenue ranges

  **Examples:** `["<$1M", "$1M-$10M", "$10M-$50M"]`
</ParamField>

### 📱 Technology & Product Filters

<ParamField body="organization_technology" type="string[]">
  Include if they use any of these tools

  **Examples:** `["Salesforce", "AWS", "React"]`
</ParamField>

<ParamField body="organization_all_technology" type="string[]">
  Must use all listed technologies
</ParamField>

<ParamField body="not_organization_technology" type="string[]">
  Exclude if using any of these technologies
</ParamField>

<ParamField body="organization_has_web_app" type="boolean">
  Has a web application?
</ParamField>

<ParamField body="organization_has_mobile_app" type="boolean">
  Has a mobile application?
</ParamField>

<ParamField body="organization_appstore_app_category" type="string[]">
  AppStore categories

  **Examples:** `["News", "Finance"]`
</ParamField>

<ParamField body="organization_playstore_app_category" type="string[]">
  PlayStore categories

  **Examples:** `["Car race", "Games"]`
</ParamField>

<ParamField body="organization_appstore_rating" type="object">
  iOS app rating (1–5)

  **Format:** `{"min": 4, "max": 5}`
</ParamField>

<ParamField body="organization_playstore_rating" type="object">
  Android app rating (1–5)

  **Format:** `{"min": 4, "max": 5}`
</ParamField>

<ParamField body="organization_appstore_review_count" type="object">
  Number of iOS reviews

  **Format:** `{"min": 100, "max": 10000}`
</ParamField>

<ParamField body="organization_playstore_review_count" type="object">
  Number of Android reviews

  **Format:** `{"min": 100, "max": 10000}`
</ParamField>

<ParamField body="organization_is_website_for_sale" type="boolean">
  Website listed for sale?
</ParamField>

### 📈 Web Traffic & Ads

<ParamField body="organization_website_traffic_total_monthly" type="object">
  Total monthly visits

  **Format:** `{"min": 1000, "max": 100000}`
</ParamField>

<ParamField body="organization_website_traffic_monthly_organic" type="object">
  Monthly organic traffic

  **Format:** `{"min": 1000, "max": 100000}`
</ParamField>

<ParamField body="organization_website_traffic_monthly_paid" type="object">
  Monthly paid traffic

  **Format:** `{"min": 1000, "max": 100000}`
</ParamField>

<ParamField body="organization_monthly_google_adspend" type="object">
  Estimated monthly Google Ads spend (\$)

  **Format:** `{"min": 1000, "max": 50000}`
</ParamField>

### 💰 Funding Filters

<ParamField body="organization_funding_amount" type="object">
  Last round amount

  **Format:** `{"min": 1000000, "max": 100000000}`
</ParamField>

<ParamField body="organization_funding_total_amount" type="object">
  Total raised funding

  **Format:** `{"min": 1000000, "max": 100000000}`
</ParamField>

<ParamField body="organization_funding_date" type="object">
  Months since last funding round

  **Format:** `{"min": 1, "max": 24}`
</ParamField>

<ParamField body="organization_funding_type" type="string[]">
  Funding stage

  **Examples:** `["Seed", "Series A", "Series B"]`
</ParamField>

<ParamField body="organization_funding_lead_investors" type="string[]">
  Names of lead investors
</ParamField>

<ParamField body="organization_funding_number_of_investors" type="object">
  Number of investors in the last round

  **Format:** `{"min": 1, "max": 10}`
</ParamField>

### 👨‍💼 Team & Roles

<ParamField body="organization_roles_count" type="object[]">
  Role distribution by department & range

  **Format:** `[{"department": "android_dev", "range": {"min": 1, "max": 100}}]`
</ParamField>

<ParamField body="organization_open_roles_count" type="object[]">
  Open roles per department with range

  **Format:** `[{"department": "sales", "range": {"min": 1, "max": 10}}]`
</ParamField>

## Response

<ResponseField name="data" type="array">
  <Expandable title="Array of Person Objects">
    <ResponseField name="id" type="string">
      Unique identifier for the person
    </ResponseField>

    <ResponseField name="name" type="string">
      Full name of the person
    </ResponseField>

    <ResponseField name="first_name" type="string">
      First name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Last name
    </ResponseField>

    <ResponseField name="title" type="string">
      Current job title
    </ResponseField>

    <ResponseField name="seniority" type="string">
      Seniority level
    </ResponseField>

    <ResponseField name="linkedin_url" type="string">
      LinkedIn profile URL
    </ResponseField>

    <ResponseField name="job_start_date" type="string">
      Start date of current position
    </ResponseField>

    <ResponseField name="city" type="string">
      Current city
    </ResponseField>

    <ResponseField name="state" type="string">
      Current state/region
    </ResponseField>

    <ResponseField name="country" type="string">
      Current country
    </ResponseField>

    <ResponseField name="country_code" type="string">
      ISO country code
    </ResponseField>

    <ResponseField name="country_region" type="string">
      Geographic region (NORAM, EMEA, APAC, LATAM)
    </ResponseField>

    <ResponseField name="email" type="string">
      Email address (when included)
    </ResponseField>

    <ResponseField name="mobile_number" type="string">
      Phone number (when included)
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization identifier
    </ResponseField>

    <ResponseField name="organizations" type="object">
      Current organization details including name, domain, website, founded year, etc.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="statusCode" type="number">
  HTTP status code (201 for success)
</ResponseField>

<ResponseField name="message" type="string">
  Response message
</ResponseField>

## Example Requests

<CodeGroup>
  ```bash Basic Search theme={null}
  curl --location 'https://api.tuesday.so/api/v1/people/search' \
  --header 'X-API-KEY: your-api-key-here' \
  --header 'Content-Type: application/json' \
  --data '{
    "page": 1,
    "per_page": 25,
    "person_titles": ["Software Engineer"],
    "include_email": "include",
    "include_phone": "include"
  }'
  ```

  ```bash Advanced Search with Company theme={null}
  curl --location 'https://api.tuesday.so/api/v1/people/search' \
  --header 'X-API-KEY: your-api-key-here' \
  --header 'Content-Type: application/json' \
  --data '{
    "page": 1,
    "per_page": 25,
    "q_organization_domains": ["salesforce.com"],
    "person_seniorities": ["Director"],
    "include_email": "include"
  }'
  ```

  ```bash Industry and Size Filter theme={null}
  curl --location 'https://api.tuesday.so/api/v1/people/search' \
  --header 'X-API-KEY: your-api-key-here' \
  --header 'Content-Type: application/json' \
  --data '{
    "page": 1,
    "per_page": 25,
    "organization_industry": ["Technology"],
    "person_titles": ["Engineering"],
    "person_location": ["United States"]
  }'
  ```

  ```javascript JavaScript theme={null}
  const searchPayload = {
    page: 1,
    per_page: 25,
    person_titles: ['Marketing Director'],
    person_seniorities: ['Director'],
    person_location: ['San Francisco'],
    organization_industry: ['Technology'],
    include_email: 'include'
  };

  const response = await fetch(
    'https://api.tuesday.so/api/v1/people/search',
    {
      method: 'POST',
      headers: {
        'X-API-KEY': 'your-api-key-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(searchPayload)
    }
  );

  const results = await response.json();
  console.log(results);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.tuesday.so/api/v1/people/search"
  payload = {
      "page": 1,
      "per_page": 25,
      "person_titles": ["VP Sales"],
      "person_seniorities": ["VP"],
      "person_location": ["United States"],
      "organization_industry": ["Software"],
      "include_email": "include",
      "include_phone": "include"
  }
  headers = {
      "X-API-KEY": "your-api-key-here",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  results = response.json()

  for person in results['data']:
      print(f"{person['name']} - {person['title']} at {person['organizations.name']}")
  ```

  ```php PHP theme={null}
  <?php
  $payload = [
      'page' => 1,
      'per_page' => 25,
      'person_titles' => ['Software Engineer'],
      'person_seniorities' => ['Senior'],
      'person_location' => ['Austin'],
      'organization_industry' => ['Technology'],
      'include_email' => 'include'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.tuesday.so/api/v1/people/search");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-KEY: your-api-key-here',
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  foreach ($data['data'] as $person) {
      echo $person['name'] . " - " . $person['title'] . "\n";
  }
  ?>
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json Response theme={null}
  {
      "data": [
          {
              "city": "Washington",
              "country": "United States",
              "country_code": "US",
              "country_region": "NORAM",
              "email": "austin.gerner@actif.ai",
              "first_name": "Austin",
              "id": "tu_pac5zsepm",
              "job_start_date": "2022-03-01",
              "last_name": "Gerner",
              "linkedin_url": "https://www.linkedin.com/in/austin-gerner-080413b4",
              "mobile_number": "+1 570-872-7952",
              "name": "Austin Gerner",
              "organization_id": "tu_oabfyglnu",
              "organizations.founded_year": 2019,
              "organizations.linkedin_url": "https://www.linkedin.com/company/actifai",
              "organizations.name": "Actifai",
              "organizations.primary_domain": "actif.ai",
              "organizations.website_url": "https://www.actif.ai",
              "seniority": "Staff",
              "state": "District of Columbia",
              "title": "Senior Software Engineer"
          },
          {
              "city": "Greenfield",
              "country": "United States",
              "country_code": "US",
              "country_region": "NORAM",
              "email": "phil.wingham@rtx.com",
              "first_name": "Phil",
              "id": "tu_pab5rkwdc",
              "job_start_date": "2012-01-01",
              "last_name": "Wingham",
              "linkedin_url": "https://www.linkedin.com/in/phil-wingham-697200b",
              "mobile_number": "+1 765-994-1888",
              "name": "Phil Wingham",
              "organization_id": "tu_oabstv4wl",
              "organizations.linkedin_url": "https://www.linkedin.com/company/rtx",
              "organizations.name": "Rtx",
              "organizations.primary_domain": "rtx.com",
              "organizations.website_url": "https://www.rtx.com",
              "seniority": "Staff",
              "state": "Indiana",
              "title": "Senior Software Engineer Ii"
          }
      ],
      "statusCode": 201,
      "message": "Success"
  }
  ```
</ResponseExample>

## Search Tips & Best Practices

<AccordionGroup>
  <Accordion title="Effective Search Strategies">
    **Combine Multiple Filters:**

    * Use 2-3 filters for optimal results (e.g., title + location + seniority)
    * Start broad, then narrow down with additional criteria

    **Title Matching:**

    * Use partial titles for broader results: `"Marketing"` vs `"Marketing Director"`
    * Include common variations: `"VP Sales"`, `"Vice President Sales"`

    **Location Targeting:**

    * City names: `"San Francisco"`, `"New York"`
    * State/region: `"California"`, `"Texas"`
    * Country: `"United States"`, `"Germany"`
  </Accordion>

  <Accordion title="Pagination Best Practices">
    * Use `limit` to control page size (recommended: 10-50)
    * Implement pagination using `offset` for large result sets
    * Check `has_more` field to determine if more results exist
    * Total results available in `pagination.total`
  </Accordion>

  <Accordion title="Cost Optimization">
    * Start searches without email/phone enrichment to preview results
    * Only add enrichment for final, targeted result sets
    * Use smaller limit values when exploring search criteria
    * Consider the total cost: base credits + enrichment costs per result
  </Accordion>
</AccordionGroup>

## Pagination Example

<CodeGroup>
  ```javascript Pagination Implementation theme={null}
  async function getAllResults(searchParams, maxResults = 1000) {
    const allResults = [];
    let offset = 0;
    const limit = 50; // Batch size
    
    while (allResults.length < maxResults) {
      const params = new URLSearchParams({
        ...searchParams,
        limit: limit,
        offset: offset
      });
      
      const response = await fetch(
        `https://api.tuesday.so/api/v1/people/search?${params}`,
        { headers: { 'X-API-KEY': 'your-api-key-here' } }
      );
      
      const data = await response.json();
      
      if (!data.data || data.data.length === 0) break;
      
      allResults.push(...data.data);
      
      if (!data.pagination.has_more) break;
      
      offset += limit;
      
      // Rate limiting pause
      await new Promise(resolve => setTimeout(resolve, 3000));
    }
    
    return allResults.slice(0, maxResults);
  }

  // Usage
  const results = await getAllResults({
    title: 'Software Engineer',
    location: 'California',
    seniority: 'Senior'
  }, 500);
  ```

  ```python Python Pagination theme={null}
  def search_all_people(search_params, max_results=1000):
      all_results = []
      offset = 0
      limit = 50
      
      while len(all_results) < max_results:
          params = {
              **search_params,
              'limit': limit,
              'offset': offset
          }
          
          response = requests.get(
              "https://api.tuesday.so/api/v1/people/search",
              params=params,
              headers={'X-API-KEY': 'your-api-key-here'}
          )
          
          data = response.json()
          
          if not data.get('data'):
              break
              
          all_results.extend(data['data'])
          
          if not data['pagination']['has_more']:
              break
              
          offset += limit
          
          # Rate limiting
          time.sleep(3)
      
      return all_results[:max_results]

  # Usage
  results = search_all_people({
      'title': 'Data Scientist',
      'industry': 'Technology',
      'seniority': 'Senior'
  }, 300)
  ```
</CodeGroup>

## Credit Usage

<div className="grid grid-cols-1 md:grid-cols-3 gap-4 my-6">
  <div className="border rounded-lg p-4 text-center">
    <div className="text-2xl font-bold text-blue-600">
      {1}
    </div>

    <div className="text-sm text-gray-600">Base per result</div>
  </div>

  <div className="border rounded-lg p-4 text-center">
    <div className="text-2xl font-bold text-orange-600">
      {"+2"}
    </div>

    <div className="text-sm text-gray-600">Email per result</div>
  </div>

  <div className="border rounded-lg p-4 text-center">
    <div className="text-2xl font-bold text-red-600">
      {"+3"}
    </div>

    <div className="text-sm text-gray-600">Phone per result</div>
  </div>
</div>

<Warning>
  **Cost Calculation Example:**

  * Search returning 20 results with email and phone enrichment
  * Base cost: 20 × 1 = 20 credits
  * Email enrichment: 20 × 2 = 40 credits
  * Phone enrichment: 20 × 3 = 60 credits
  * **Total: 120 credits**
</Warning>

## Common Search Patterns

<AccordionGroup>
  <Accordion title="Sales Prospecting">
    ```bash theme={null}
    # Find decision makers at target companies
    ?title=Director&seniority=Director&industry=Technology&company_size=501-1000

    # Sales leaders in specific geography
    ?title=Sales&seniority=VP&location=California&include_email=include
    ```
  </Accordion>

  <Accordion title="Recruitment Searches">
    ```bash theme={null}
    # Senior engineers in tech hubs
    ?title=Software Engineer&seniority=Senior&location=San Francisco&industry=Technology

    # Marketing professionals with experience
    ?title=Marketing&keywords=digital marketing&seniority=Manager&country=US
    ```
  </Accordion>

  <Accordion title="Market Research">
    ```bash theme={null}
    # Industry analysis by role distribution
    ?industry=Healthcare&company_size=1001-5000&limit=100

    # Geographic concentration of talent
    ?title=Data Scientist&country=US&limit=50
    ```
  </Accordion>
</AccordionGroup>

## Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request - Invalid Parameters">
    ```json theme={null}
    {
        "statusCode": 400,
        "message": "Bad Request",
        "error": "Invalid limit value. Must be between 1 and 100"
    }
    ```
  </Accordion>

  <Accordion title="400 Bad Request - Missing Search Criteria">
    ```json theme={null}
    {
        "statusCode": 400,
        "message": "Bad Request",
        "error": "At least one search criterion is required"
    }
    ```
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Sales Prospecting" icon="bullseye">
    Build targeted prospect lists based on title, industry, and company size
  </Card>

  <Card title="Talent Acquisition" icon="users">
    Find qualified candidates matching specific role and experience criteria
  </Card>

  <Card title="Market Research" icon="chart-bar">
    Analyze industry trends and talent distribution across regions
  </Card>

  <Card title="Lead Generation" icon="rocket">
    Identify decision makers and influencers in target companies
  </Card>
</CardGroup>

## Related Endpoints

* [People Profile API](/api-reference/people/profile) - Get detailed profile by LinkedIn URL
* [People Lookup API](/api-reference/people/lookup) - Find specific person by name and company
* [Company Search API](/api-reference/company/search) - Search for companies with filters
* [Company Employee Search](/api-reference/company/employee-search) - Find employees within specific companies