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

> Find a person's professional profile using available attributes like name, company, and title

## Overview

Find a person's professional profile when you don't have their LinkedIn URL but have other identifying information like their name, company domain, title, or location. This endpoint is perfect for lead generation and contact discovery workflows.

## Authentication

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

## Query Parameters

<ParamField query="company_domain" type="string" required>
  Domain of the company (e.g., `technova.com`, `sempersolaris.com`)
</ParamField>

<ParamField query="first_name" type="string" required>
  First name of the person
</ParamField>

<ParamField query="last_name" type="string">
  Last name of the person (optional but recommended for better accuracy)
</ParamField>

<ParamField query="title" type="string">
  Job title or role (e.g., "Energy Consultant", "Software Engineer")
</ParamField>

<ParamField query="location" type="string">
  Location (city, state, or country) (e.g., "Florida", "New York", "United States")
</ParamField>

<ParamField query="include_email" type="string" default="exclude">
  Include email address in the response

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

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

<ParamField query="include_phone" type="string" default="exclude">
  Include phone number in the response

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

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

## Response

<ResponseField name="data" type="object">
  <Expandable title="Person Profile Data">
    <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 (e.g., "Staff", "Manager", "Director")
    </ResponseField>

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

    <ResponseField name="job_start_date" type="string">
      Start date of current position (YYYY-MM-DD format)
    </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">
      Two-letter country code
    </ResponseField>

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

    <ResponseField name="email" type="string">
      Email address (only when `include_email=include`)
    </ResponseField>

    <ResponseField name="mobile_number" type="string">
      Phone number (only when `include_phone=include`)
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Unique identifier for the person's current organization
    </ResponseField>

    <ResponseField name="organizations.name" type="string">
      Current organization name
    </ResponseField>

    <ResponseField name="organizations.linkedin_url" type="string">
      Organization's LinkedIn URL
    </ResponseField>

    <ResponseField name="organizations.primary_domain" type="string">
      Organization's primary domain
    </ResponseField>

    <ResponseField name="organizations.website_url" type="string">
      Organization's website URL
    </ResponseField>

    <ResponseField name="organizations.founded_year" type="number">
      Year the organization was founded
    </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 Basic Lookup theme={null}
  curl --location 'https://api.tuesday.so/api/v1/people/lookup?company_domain=sempersolaris.com&first_name=David&last_name=Addiss' \
  --header 'X-API-KEY: your-api-key-here'
  ```

  ```bash With Title and Location theme={null}
  curl --location 'https://api.tuesday.so/api/v1/people/lookup?company_domain=sempersolaris.com&first_name=David&last_name=Addiss&title=Energy%20Consultant&location=Florida' \
  --header 'X-API-KEY: your-api-key-here'
  ```

  ```bash With Email and Phone theme={null}
  curl --location 'https://api.tuesday.so/api/v1/people/lookup?company_domain=sempersolaris.com&first_name=David&last_name=Addiss&title=Energy%20Consultant&location=Florida&include_email=include&include_phone=include' \
  --header 'X-API-KEY: your-api-key-here'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    company_domain: 'sempersolaris.com',
    first_name: 'David',
    last_name: 'Addiss',
    title: 'Energy Consultant',
    location: 'Florida',
    include_email: 'include',
    include_phone: 'include'
  });

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

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

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

  url = "https://api.tuesday.so/api/v1/people/lookup"
  params = {
      "company_domain": "sempersolaris.com",
      "first_name": "David",
      "last_name": "Addiss",
      "title": "Energy Consultant", 
      "location": "Florida",
      "include_email": "include",
      "include_phone": "include"
  }
  headers = {
      "X-API-KEY": "your-api-key-here"
  }

  response = requests.get(url, params=params, headers=headers)
  profile = response.json()
  print(profile)
  ```

  ```php PHP theme={null}
  <?php
  $params = http_build_query([
      'company_domain' => 'sempersolaris.com',
      'first_name' => 'David',
      'last_name' => 'Addiss',
      'title' => 'Energy Consultant',
      'location' => 'Florida',
      'include_email' => 'include',
      'include_phone' => 'include'
  ]);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.tuesday.so/api/v1/people/lookup?$params");
  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);

  $data = json_decode($response, true);
  print_r($data);
  ?>
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json Response theme={null}
  {
      "data": {
          "city": "St Petersburg",
          "country": "United States",
          "country_code": "US",
          "country_region": "NORAM",
          "email": "david.addiss@sempersolaris.com",
          "first_name": "David",
          "id": "tu_pacyf3uhs",
          "job_start_date": "2022-04-01",
          "last_name": "Addiss",
          "linkedin_url": "https://www.linkedin.com/in/david-addiss-4725189",
          "mobile_number": "+1 813-407-3977",
          "name": "David Addiss",
          "organization_id": "tu_oac4h5wgp",
          "organizations.founded_year": 2012,
          "organizations.linkedin_url": "https://www.linkedin.com/company/semper-solaris",
          "organizations.name": "Semper Solaris",
          "organizations.primary_domain": "sempersolaris.com",
          "organizations.website_url": "https://www.sempersolaris.com?utm_source=linkedin",
          "seniority": "Staff",
          "state": "Florida",
          "title": "Energy Consultant"
      },
      "statusCode": 200,
      "message": "Success"
  }
  ```
</ResponseExample>

## Best Practices

<AccordionGroup>
  <Accordion title="Improve Match Accuracy">
    To get the most accurate results:

    * Always provide both `first_name` and `last_name` when possible
    * Include `title` to help disambiguate between people with the same name
    * Add `location` to further refine results
    * Ensure the company domain is accurate and current
  </Accordion>

  <Accordion title="Handle Multiple Matches">
    If multiple people match your criteria:

    * The API returns the best match based on all provided parameters
    * Add more specific criteria (title, location) to narrow results
    * Review the returned LinkedIn URL to verify it's the correct person
  </Accordion>

  <Accordion title="Company Domain Tips">
    For best results with company domains:

    * Use the primary domain (e.g., `google.com` not `gmail.com`)
    * Check the company's official website for the correct domain
    * Some companies may have multiple domains - try the main one first
  </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 Lookup</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 Enrichment</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 Enrichment</div>
  </div>
</div>

## Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request - Missing Required Parameters">
    ```json theme={null}
    {
        "statusCode": 400,
        "message": "Bad Request",
        "error": "Missing required parameters: company_domain and first_name are required"
    }
    ```
  </Accordion>

  <Accordion title="404 Not Found - No Match Found">
    ```json theme={null}
    {
        "statusCode": 404,
        "message": "Not Found",
        "error": "No profile found matching the provided criteria"
    }
    ```
  </Accordion>

  <Accordion title="400 Bad Request - Invalid Domain">
    ```json theme={null}
    {
        "statusCode": 400,
        "message": "Bad Request",
        "error": "Invalid company domain format"
    }
    ```
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Lead Generation" icon="bullseye">
    Find contact information for prospects when you only know their name and company
  </Card>

  <Card title="CRM Data Cleanup" icon="broom">
    Enrich incomplete contact records with missing information
  </Card>

  <Card title="Sales Prospecting" icon="chart-line">
    Research specific individuals at target companies
  </Card>

  <Card title="Contact Discovery" icon="magnifying-glass">
    Find the right person to contact at a company for specific roles
  </Card>
</CardGroup>

## Related Endpoints

* [People Profile API](/api-reference/people/profile) - Get profile by LinkedIn URL
* [People Search API](/api-reference/people/search) - Advanced search with multiple filters
* [Reverse Email Lookup](/api-reference/people/lookup-email) - Find profile by email address
* [Reverse Phone Lookup](/api-reference/people/lookup-phone) - Find profile by phone number