Skip to main content
POST
/
api
/
v1
/
people
/
search
People Search
curl --request POST \
  --url https://api.tuesday.so/api/v1/people/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '{
  "page": 123,
  "per_page": 123,
  "include_email": "<string>",
  "include_phone": "<string>",
  "person_titles": [
    "<string>"
  ],
  "person_not_titles": [
    "<string>"
  ],
  "person_past_titles": [
    "<string>"
  ],
  "person_seniorities": [
    "<string>"
  ],
  "person_location": [
    "<string>"
  ],
  "not_person_location": [
    "<string>"
  ],
  "person_days_in_current_title_range": {},
  "q_organization_domains": [
    "<string>"
  ],
  "not_q_organization_domains": [
    "<string>"
  ],
  "organization_location": [
    "<string>"
  ],
  "not_organization_location": [
    "<string>"
  ],
  "organization_industry": [
    "<string>"
  ],
  "organization_not_industry": [
    "<string>"
  ],
  "organization_sic_industry": [
    "<string>"
  ],
  "organization_not_sic_industry": [
    "<string>"
  ],
  "organization_naics_industry": [
    "<string>"
  ],
  "organization_not_naics_industry": [
    "<string>"
  ],
  "organization_revenue_ranges": [
    "<string>"
  ],
  "organization_technology": [
    "<string>"
  ],
  "organization_all_technology": [
    "<string>"
  ],
  "not_organization_technology": [
    "<string>"
  ],
  "organization_has_web_app": true,
  "organization_has_mobile_app": true,
  "organization_appstore_app_category": [
    "<string>"
  ],
  "organization_playstore_app_category": [
    "<string>"
  ],
  "organization_appstore_rating": {},
  "organization_playstore_rating": {},
  "organization_appstore_review_count": {},
  "organization_playstore_review_count": {},
  "organization_is_website_for_sale": true,
  "organization_website_traffic_total_monthly": {},
  "organization_website_traffic_monthly_organic": {},
  "organization_website_traffic_monthly_paid": {},
  "organization_monthly_google_adspend": {},
  "organization_funding_amount": {},
  "organization_funding_total_amount": {},
  "organization_funding_date": {},
  "organization_funding_type": [
    "<string>"
  ],
  "organization_funding_lead_investors": [
    "<string>"
  ],
  "organization_funding_number_of_investors": {},
  "organization_roles_count": [
    {}
  ],
  "organization_open_roles_count": [
    {}
  ]
}'
{
    "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"
}

​
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

​
X-API-KEY
string
required
Your Tuesday API key

​
Request Parameters

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

​
📄 Pagination

​
page
int
default:"1"
Page number
​
per_page
int
default:"25"
Results per page (max: 100)
​
include_email
string
default:"exclude"
Include email addressOptions: include | excludeAdditional Cost: +2 credits per result when set to include
​
include_phone
string
default:"exclude"
Include phone numberOptions: include | excludeAdditional Cost: +3 credits per result when set to include

​
👤 Person Filters

​
person_titles
string[]
Current job titles to includeExamples: ["Software Engineer", "Senior Developer"]
​
person_not_titles
string[]
Exclude these current job titles
​
person_past_titles
string[]
Match against past job titles
​
person_seniorities
string[]
Filter by seniority levelExamples: ["C-Team", "Manager", "Director"]
​
person_location
string[]
Current person locationExamples: ["San Francisco", "California", "United States"]
​
not_person_location
string[]
Exclude people in these locations
​
person_days_in_current_title_range
object
Days in current role/titleFormat: {"min": 30, "max": 300}

​
🏢 Organization Filters

​
q_organization_domains
string[]
Match organization domainsExamples: ["google.com", "microsoft.com"]
​
not_q_organization_domains
string[]
Exclude organizations with these domains
​
organization_location
string[]
Company HQ/location
​
not_organization_location
string[]
Exclude companies in these locations
​
organization_industry
string[]
Include companies in these industriesExamples: ["Technology", "Healthcare", "Finance"]
​
organization_not_industry
string[]
Exclude companies from these industries
​
organization_sic_industry
string[]
Filter by SIC codesExamples: ["0919"]
​
organization_not_sic_industry
string[]
Exclude SIC codes
​
organization_naics_industry
string[]
Filter by NAICS codesExamples: ["236117"]
​
organization_not_naics_industry
string[]
Exclude NAICS codes
​
organization_revenue_ranges
string[]
Revenue rangesExamples: ["<$1M", "$1M-$10M", "$10M-$50M"]

​
📱 Technology & Product Filters

​
organization_technology
string[]
Include if they use any of these toolsExamples: ["Salesforce", "AWS", "React"]
​
organization_all_technology
string[]
Must use all listed technologies
​
not_organization_technology
string[]
Exclude if using any of these technologies
​
organization_has_web_app
boolean
Has a web application?
​
organization_has_mobile_app
boolean
Has a mobile application?
​
organization_appstore_app_category
string[]
AppStore categoriesExamples: ["News", "Finance"]
​
organization_playstore_app_category
string[]
PlayStore categoriesExamples: ["Car race", "Games"]
​
organization_appstore_rating
object
iOS app rating (1–5)Format: {"min": 4, "max": 5}
​
organization_playstore_rating
object
Android app rating (1–5)Format: {"min": 4, "max": 5}
​
organization_appstore_review_count
object
Number of iOS reviewsFormat: {"min": 100, "max": 10000}
​
organization_playstore_review_count
object
Number of Android reviewsFormat: {"min": 100, "max": 10000}
​
organization_is_website_for_sale
boolean
Website listed for sale?

​
📈 Web Traffic & Ads

​
organization_website_traffic_total_monthly
object
Total monthly visitsFormat: {"min": 1000, "max": 100000}
​
organization_website_traffic_monthly_organic
object
Monthly organic trafficFormat: {"min": 1000, "max": 100000}
​
organization_website_traffic_monthly_paid
object
Monthly paid trafficFormat: {"min": 1000, "max": 100000}
​
organization_monthly_google_adspend
object
Estimated monthly Google Ads spend ($)Format: {"min": 1000, "max": 50000}

​
💰 Funding Filters

​
organization_funding_amount
object
Last round amountFormat: {"min": 1000000, "max": 100000000}
​
organization_funding_total_amount
object
Total raised fundingFormat: {"min": 1000000, "max": 100000000}
​
organization_funding_date
object
Months since last funding roundFormat: {"min": 1, "max": 24}
​
organization_funding_type
string[]
Funding stageExamples: ["Seed", "Series A", "Series B"]
​
organization_funding_lead_investors
string[]
Names of lead investors
​
organization_funding_number_of_investors
object
Number of investors in the last roundFormat: {"min": 1, "max": 10}

​
👨‍💼 Team & Roles

​
organization_roles_count
object[]
Role distribution by department & rangeFormat: [{"department": "android_dev", "range": {"min": 1, "max": 100}}]
​
organization_open_roles_count
object[]
Open roles per department with rangeFormat: [{"department": "sales", "range": {"min": 1, "max": 10}}]

​
Response

​
data
array
​
statusCode
number
HTTP status code (201 for success)
​
message
string
Response message

​
Example Requests

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

​
Example Response

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

​
Search Tips & Best Practices

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"
  • 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
  • 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

​
Pagination Example

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

​
Credit Usage

Base per result
Email per result
Phone per result
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

​
Common Search Patterns

# 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

# 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

# Industry analysis by role distribution
?industry=Healthcare&company_size=1001-5000&limit=100

# Geographic concentration of talent
?title=Data Scientist&country=US&limit=50

​
Error Responses

{
    "statusCode": 400,
    "message": "Bad Request",
    "error": "Invalid limit value. Must be between 1 and 100"
}

{
    "statusCode": 400,
    "message": "Bad Request",
    "error": "At least one search criterion is required"
}

​
Use Cases

Sales Prospecting

Build targeted prospect lists based on title, industry, and company size

Talent Acquisition

Find qualified candidates matching specific role and experience criteria

Market Research

Analyze industry trends and talent distribution across regions

Lead Generation

Identify decision makers and influencers in target companies
⌘I