People Search

POST

api

people

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 address

Options: include | exclude

Additional Cost: +2 credits per result when set to include

include_phone

string

default:"exclude"

Include phone number

Options: include | exclude

Additional Cost: +3 credits per result when set to include

👤 Person Filters

person_titles

string[]

Current job titles to include

Examples: ["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 level

Examples: ["C-Team", "Manager", "Director"]

person_location

string[]

Current person location

Examples: ["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/title

Format: {"min": 30, "max": 300}

🏢 Organization Filters

q_organization_domains

string[]

Match organization domains

Examples: ["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 industries

Examples: ["Technology", "Healthcare", "Finance"]

organization_not_industry

string[]

Exclude companies from these industries

organization_sic_industry

string[]

Filter by SIC codes

Examples: ["0919"]

organization_not_sic_industry

string[]

Exclude SIC codes

organization_naics_industry

string[]

Filter by NAICS codes

Examples: ["236117"]

organization_not_naics_industry

string[]

Exclude NAICS codes

organization_revenue_ranges

string[]

Revenue ranges

Examples: ["<$1M", "$1M-$10M", "$10M-$50M"]

organization_technology

string[]

Include if they use any of these tools

Examples: ["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 categories

Examples: ["News", "Finance"]

organization_playstore_app_category

string[]

PlayStore categories

Examples: ["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 reviews

Format: {"min": 100, "max": 10000}

organization_playstore_review_count

object

Number of Android reviews

Format: {"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 visits

Format: {"min": 1000, "max": 100000}

organization_website_traffic_monthly_organic

object

Monthly organic traffic

Format: {"min": 1000, "max": 100000}

organization_website_traffic_monthly_paid

object

Monthly paid traffic

Format: {"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 amount

Format: {"min": 1000000, "max": 100000000}

organization_funding_total_amount

object

Total raised funding

Format: {"min": 1000000, "max": 100000000}

organization_funding_date

object

Months since last funding round

Format: {"min": 1, "max": 24}

organization_funding_type

string[]

Funding stage

Examples: ["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 round

Format: {"min": 1, "max": 10}

👨‍💼 Team & Roles

organization_roles_count

object[]

Role distribution by department & range

Format: [{"department": "android_dev", "range": {"min": 1, "max": 100}}]

organization_open_roles_count

object[]

Open roles per department with range

Format: [{"department": "sales", "range": {"min": 1, "max": 10}}]

Response

data

array

Show Array of Person Objects

string

Unique identifier for the person

name

string

Full name of the person

first_name

string

First name

last_name

string

Last name

title

string

Current job title

seniority

string

Seniority level

linkedin_url

string

LinkedIn profile URL

job_start_date

string

Start date of current position

city

string

Current city

state

string

Current state/region

country

string

Current country

country_code

string

ISO country code

country_region

string

Geographic region (NORAM, EMEA, APAC, LATAM)

string

Email address (when included)

mobile_number

string

Phone number (when included)

organization_id

string

Organization identifier

organizations

object

Current organization details including name, domain, website, founded year, etc.

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

Effective Search Strategies

Pagination Best Practices

Cost Optimization

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

Sales Prospecting

# 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

Recruitment Searches

# 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

Market Research

Error Responses

400 Bad Request - Invalid Parameters

400 Bad Request - Missing Search Criteria

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

People Profile API - Get detailed profile by LinkedIn URL
People Lookup API - Find specific person by name and company
Company Search API - Search for companies with filters
Company Employee Search - Find employees within specific companies

Reverse Phone Lookup Get Company Profile

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

Authentication

People APIs

Company APIs

Overview

Authentication

Request Parameters

👤 Person Filters

🏢 Organization Filters

📱 Technology & Product Filters

📈 Web Traffic & Ads

💰 Funding Filters

👨‍💼 Team & Roles

Response

Example Requests

Example Response

Search Tips & Best Practices

Credit Usage

Common Search Patterns

Error Responses

Use Cases

Sales Prospecting

Talent Acquisition

Market Research

Lead Generation

Authentication

People APIs

Company APIs

​Overview

​Authentication

​Request Parameters

​📄 Pagination

​👤 Person Filters

​🏢 Organization Filters

​📱 Technology & Product Filters

​📈 Web Traffic & Ads

​💰 Funding Filters

​👨‍💼 Team & Roles

​Response

​Example Requests

​Example Response

​Search Tips & Best Practices

​Pagination Example

​Credit Usage

​Common Search Patterns

​Error Responses

​Use Cases

Sales Prospecting

Talent Acquisition

Market Research

Lead Generation

​Related Endpoints

Overview

Authentication

Request Parameters

📄 Pagination

👤 Person Filters

🏢 Organization Filters

📱 Technology & Product Filters

📈 Web Traffic & Ads

💰 Funding Filters

👨‍💼 Team & Roles

Response

Example Requests

Example Response

Search Tips & Best Practices

Pagination Example

Credit Usage

Common Search Patterns

Error Responses

Use Cases

Related Endpoints