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

# Company Employee Search

> Find employees within a specific company using various filters

## Overview

Search for employees within a specific company using filters like department, title, seniority, and location. Perfect for sales prospecting, recruitment, and competitive intelligence when you need to find specific people at target companies.

## Authentication

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

## Query Parameters

<ParamField query="company_domain" type="string">
  Company domain to search within

  **Example:** `salesforce.com`

  **Note:** Either `company_domain` or `company_linkedin_url` is required
</ParamField>

<ParamField query="company_linkedin_url" type="string">
  LinkedIn company page URL

  **Example:** `https://www.linkedin.com/company/salesforce`

  **Note:** Either `company_domain` or `company_linkedin_url` is required
</ParamField>

<ParamField query="title" type="string">
  Job title or role filter (supports partial matches)

  **Examples:** `"Sales Director"`, `"Software Engineer"`, `"Marketing"`
</ParamField>

<ParamField query="department" type="string">
  Department filter

  **Options:** `"Engineering"`, `"Sales"`, `"Marketing"`, `"Operations"`, `"Human Resources"`, `"Finance"`, `"Customer Success"`, `"Product"`
</ParamField>

<ParamField query="seniority" type="string">
  Seniority level filter

  **Options:** `"C-Suite"`, `"VP"`, `"Director"`, `"Manager"`, `"Senior"`, `"Staff"`, `"Intern"`
</ParamField>

<ParamField query="location" type="string">
  Office location or geographic filter

  **Examples:** `"San Francisco"`, `"New York"`, `"Remote"`, `"California"`
</ParamField>

<ParamField query="keywords" type="string">
  Keywords to search in employee profiles

  **Examples:** `"machine learning"`, `"enterprise sales"`, `"product marketing"`
</ParamField>

<ParamField query="limit" type="number" default="10">
  Maximum number of results to return (1-100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of results to skip for pagination
</ParamField>

<ParamField query="include_email" type="string" default="exclude">
  Include email addresses in results

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

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

<ParamField query="include_phone" type="string" default="exclude">
  Include phone numbers in results

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

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

## Response

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

    <ResponseField name="name" type="string">
      Full name of the employee
    </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="department" type="string">
      Department classification
    </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 at current company (YYYY-MM-DD format)
    </ResponseField>

    <ResponseField name="tenure_months" type="number">
      Number of months at the company
    </ResponseField>

    <ResponseField name="location" type="string">
      Work location (city, state or "Remote")
    </ResponseField>

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

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

    <ResponseField name="previous_companies" type="array">
      Previous work experience (limited)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="company_info" type="object">
  <Expandable title="Company Context">
    <ResponseField name="name" type="string">
      Company name
    </ResponseField>

    <ResponseField name="domain" type="string">
      Primary domain
    </ResponseField>

    <ResponseField name="total_employees_found" type="number">
      Total matching employees (respecting pagination)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination Details">
    <ResponseField name="total" type="number">
      Total number of matching employees
    </ResponseField>

    <ResponseField name="limit" type="number">
      Number of results per page
    </ResponseField>

    <ResponseField name="offset" type="number">
      Current offset
    </ResponseField>

    <ResponseField name="has_more" type="boolean">
      Whether more results are available
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

## Example Requests

<CodeGroup>
  ```bash Find Sales Directors theme={null}
  curl --location 'https://api.tuesday.so/api/v1/company/employee-search?company_domain=salesforce.com&title=Sales%20Director&department=Sales' \
  --header 'X-API-KEY: your-api-key-here'
  ```

  ```bash Engineering Leadership theme={null}
  curl --location 'https://api.tuesday.so/api/v1/company/employee-search?company_domain=google.com&department=Engineering&seniority=Director&limit=20' \
  --header 'X-API-KEY: your-api-key-here'
  ```

  ```bash Remote Marketing Team theme={null}
  curl --location 'https://api.tuesday.so/api/v1/company/employee-search?company_domain=stripe.com&department=Marketing&location=Remote&include_email=include' \
  --header 'X-API-KEY: your-api-key-here'
  ```

  ```javascript JavaScript theme={null}
  const searchEmployees = async (companyDomain, filters = {}) => {
    const params = new URLSearchParams({
      company_domain: companyDomain,
      ...filters
    });

    const response = await fetch(
      `https://api.tuesday.so/api/v1/company/employee-search?${params}`,
      {
        headers: {
          'X-API-KEY': 'your-api-key-here'
        }
      }
    );

    const results = await response.json();
    return results;
  };

  // Usage Examples
  const salesTeam = await searchEmployees('salesforce.com', {
    department: 'Sales',
    seniority: 'Manager',
    location: 'San Francisco',
    limit: 25
  });

  const engineers = await searchEmployees('stripe.com', {
    department: 'Engineering',
    keywords: 'machine learning',
    seniority: 'Senior'
  });

  console.log(`Found ${salesTeam.data.length} sales managers`);
  ```

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

  def search_company_employees(company_domain=None, company_linkedin_url=None, **filters):
      url = "https://api.tuesday.so/api/v1/company/employee-search"
      
      params = {}
      if company_domain:
          params['company_domain'] = company_domain
      elif company_linkedin_url:
          params['company_linkedin_url'] = company_linkedin_url
      else:
          raise ValueError("Either company_domain or company_linkedin_url is required")
      
      # Add filters
      params.update(filters)
      
      headers = {'X-API-KEY': 'your-api-key-here'}
      
      response = requests.get(url, params=params, headers=headers)
      return response.json()

  # Usage Examples
  # Find engineering managers
  eng_managers = search_company_employees(
      company_domain='github.com',
      department='Engineering',
      seniority='Manager',
      limit=30
  )

  # Find sales directors with contact info
  sales_directors = search_company_employees(
      company_domain='hubspot.com',
      title='Sales Director',
      include_email='include',
      include_phone='include'
  )

  # Find remote product managers
  remote_pm = search_company_employees(
      company_domain='figma.com',
      department='Product',
      location='Remote',
      keywords='product management'
  )

  for employee in eng_managers['data']:
      print(f"{employee['name']} - {employee['title']} ({employee['tenure_months']} months)")
  ```

  ```php PHP theme={null}
  <?php
  function searchCompanyEmployees($companyDomain = null, $companyLinkedinUrl = null, $filters = []) {
      $params = [];
      
      if ($companyDomain) {
          $params['company_domain'] = $companyDomain;
      } elseif ($companyLinkedinUrl) {
          $params['company_linkedin_url'] = $companyLinkedinUrl;
      } else {
          throw new Exception("Either company_domain or company_linkedin_url is required");
      }
      
      // Add filters
      $params = array_merge($params, $filters);
      
      $queryString = http_build_query($params);
      
      $ch = curl_init();
      curl_setopt($ch, CURLOPT_URL, "https://api.tuesday.so/api/v1/company/employee-search?$queryString");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'X-API-KEY: your-api-key-here'
      ]);
      
      $response = curl_exec($ch);
      curl_close($ch);
      
      return json_decode($response, true);
  }

  // Usage Examples
  $salesTeam = searchCompanyEmployees('salesforce.com', null, [
      'department' => 'Sales',
      'seniority' => 'VP',
      'limit' => 10
  ]);

  $engineers = searchCompanyEmployees('netflix.com', null, [
      'department' => 'Engineering',
      'keywords' => 'distributed systems',
      'seniority' => 'Senior'
  ]);

  foreach ($salesTeam['data'] as $employee) {
      echo $employee['name'] . " - " . $employee['title'] . "\n";
  }
  ?>
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json Response theme={null}
  {
      "data": [
          {
              "id": "tu_emp_sf_001",
              "name": "Sarah Chen",
              "first_name": "Sarah",
              "last_name": "Chen",
              "title": "Senior Sales Director",
              "department": "Sales", 
              "seniority": "Director",
              "linkedin_url": "https://www.linkedin.com/in/sarah-chen-sales",
              "job_start_date": "2021-08-15",
              "tenure_months": 28,
              "location": "San Francisco, CA",
              "email": "sarah.chen@salesforce.com",
              "mobile_number": "+1 415-555-0198",
              "previous_companies": [
                  {
                      "name": "Oracle",
                      "title": "Sales Manager",
                      "duration_months": 36
                  }
              ]
          },
          {
              "id": "tu_emp_sf_002", 
              "name": "Michael Rodriguez",
              "first_name": "Michael",
              "last_name": "Rodriguez",
              "title": "VP of Sales, Enterprise",
              "department": "Sales",
              "seniority": "VP",
              "linkedin_url": "https://www.linkedin.com/in/michael-rodriguez-sales-vp",
              "job_start_date": "2019-03-01",
              "tenure_months": 58,
              "location": "New York, NY",
              "email": "mrodriguez@salesforce.com",
              "mobile_number": "+1 212-555-0156",
              "previous_companies": [
                  {
                      "name": "SAP",
                      "title": "Regional Sales Director",
                      "duration_months": 48
                  }
              ]
          }
      ],
      "company_info": {
          "name": "Salesforce",
          "domain": "salesforce.com",
          "total_employees_found": 1247
      },
      "pagination": {
          "total": 1247,
          "limit": 10,
          "offset": 0,
          "has_more": true
      },
      "statusCode": 200,
      "message": "Success"
  }
  ```
</ResponseExample>

## Search Strategies

<AccordionGroup>
  <Accordion title="Department-Based Searches">
    **Sales Prospecting:**

    * `department=Sales&seniority=Director` - Decision makers
    * `department=Sales&location=Remote` - Remote sales team
    * `title=VP Sales` - C-level sales contacts

    **Recruitment:**

    * `department=Engineering&keywords=React` - Frontend developers
    * `department=Product&seniority=Manager` - Product managers
    * `department=Marketing&keywords=growth` - Growth marketers
  </Accordion>

  <Accordion title="Seniority-Based Targeting">
    **Executive Outreach:**

    * `seniority=C-Suite` - C-level executives
    * `seniority=VP&department=Sales` - VP-level decision makers

    **Mid-Level Contacts:**

    * `seniority=Director&department=Engineering` - Technical directors
    * `seniority=Manager` - Team managers across departments

    **Individual Contributors:**

    * `seniority=Senior&department=Engineering` - Senior engineers
    * `seniority=Staff&keywords=data science` - Data scientists
  </Accordion>

  <Accordion title="Location-Based Searches">
    **Geographic Targeting:**

    * `location=San Francisco` - Bay Area employees
    * `location=Remote` - Distributed workforce
    * `location=New York` - East Coast presence

    **Multi-Location:**

    * Combine with other filters for regional analysis
    * Identify location-specific team structures
    * Find local office leadership
  </Accordion>
</AccordionGroup>

## 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>
  **Large Company Searches:** Companies with 10,000+ employees may return hundreds of results. Use specific filters to narrow results and manage costs effectively.
</Warning>

## Pagination Best Practices

<CodeGroup>
  ```javascript Bulk Employee Export theme={null}
  async function exportAllEmployees(companyDomain, filters = {}) {
    let allEmployees = [];
    let offset = 0;
    const limit = 50;
    
    while (true) {
      const params = new URLSearchParams({
        company_domain: companyDomain,
        limit: limit,
        offset: offset,
        ...filters
      });
      
      const response = await fetch(
        `https://api.tuesday.so/api/v1/company/employee-search?${params}`,
        { headers: { 'X-API-KEY': 'your-api-key-here' } }
      );
      
      const data = await response.json();
      
      if (!data.data || data.data.length === 0) break;
      
      allEmployees.push(...data.data);
      
      if (!data.pagination.has_more) break;
      
      offset += limit;
      
      // Rate limiting pause
      await new Promise(resolve => setTimeout(resolve, 3000));
    }
    
    return allEmployees;
  }

  // Export all engineering managers
  const engineeringManagers = await exportAllEmployees('stripe.com', {
    department: 'Engineering',
    seniority: 'Manager'
  });
  ```

  ```python Python Batch Processing theme={null}
  import time

  def batch_search_employees(company_domain, filters, batch_size=50, max_results=1000):
      """Search employees in batches with rate limiting"""
      all_employees = []
      offset = 0
      
      while len(all_employees) < max_results:
          params = {
              'company_domain': company_domain,
              'limit': min(batch_size, max_results - len(all_employees)),
              'offset': offset,
              **filters
          }
          
          response = requests.get(
              "https://api.tuesday.so/api/v1/company/employee-search",
              params=params,
              headers={'X-API-KEY': 'your-api-key-here'}
          )
          
          data = response.json()
          
          if not data.get('data'):
              break
              
          all_employees.extend(data['data'])
          
          if not data['pagination']['has_more']:
              break
              
          offset += batch_size
          time.sleep(3)  # Rate limiting
      
      return all_employees[:max_results]

  # Example: Get all sales people
  sales_team = batch_search_employees('hubspot.com', {
      'department': 'Sales',
      'include_email': 'include'
  }, max_results=500)
  ```
</CodeGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Sales Prospecting" icon="bullseye">
    Find decision makers and contacts at target companies for outreach
  </Card>

  <Card title="Competitive Hiring" icon="users">
    Identify talent at competitor companies for recruitment
  </Card>

  <Card title="Account Research" icon="magnifying-glass">
    Research company structure and key contacts before meetings
  </Card>

  <Card title="Market Intelligence" icon="chart-line">
    Analyze competitor team structures and hiring patterns
  </Card>

  <Card title="Partnership Mapping" icon="handshake">
    Find relevant contacts for business development and partnerships
  </Card>

  <Card title="Org Chart Building" icon="sitemap">
    Build organizational charts for target accounts
  </Card>
</CardGroup>

## Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request - Missing Company Parameter">
    ```json theme={null}
    {
        "statusCode": 400,
        "message": "Bad Request",
        "error": "Either company_domain or company_linkedin_url is required"
    }
    ```
  </Accordion>

  <Accordion title="404 Not Found - Company Not Found">
    ```json theme={null}
    {
        "statusCode": 404,
        "message": "Not Found",
        "error": "Company not found or has insufficient employee data"
    }
    ```
  </Accordion>

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

## Advanced Filtering

<AccordionGroup>
  <Accordion title="Multi-Filter Combinations">
    **Effective Combinations:**

    ```bash theme={null}
    # Senior engineering leadership
    ?department=Engineering&seniority=Director&keywords=architecture

    # Remote sales managers
    ?department=Sales&seniority=Manager&location=Remote

    # Product marketing specialists
    ?department=Marketing&keywords=product marketing&seniority=Staff
    ```
  </Accordion>

  <Accordion title="Keyword Strategies">
    **Technical Keywords:**

    * Programming languages: `"Python"`, `"React"`, `"Go"`
    * Technologies: `"AWS"`, `"Kubernetes"`, `"GraphQL"`
    * Methodologies: `"Agile"`, `"DevOps"`, `"Machine Learning"`

    **Business Keywords:**

    * Functions: `"enterprise sales"`, `"product marketing"`, `"customer success"`
    * Skills: `"analytics"`, `"strategy"`, `"operations"`
  </Accordion>
</AccordionGroup>

## Related Endpoints

* [Company Profile API](/api-reference/company/profile) - Get comprehensive company information
* [Company Employee Count](/api-reference/company/employee-count) - Get employee metrics and department breakdown
* [People Search API](/api-reference/people/search) - Search across all companies with filters
* [People Lookup API](/api-reference/people/lookup) - Find specific people by name and company