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

# Reverse Phone Lookup

> Find a person's professional profile using their phone number

## Overview

Find a person's professional profile using their phone number. This endpoint is useful for identifying unknown callers, enriching contact databases, and discovering professional information about phone contacts.

## Authentication

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

## Query Parameters

<ParamField query="phone" type="string" required>
  Phone number to lookup (e.g., `+14155552671`, `+1 713-408-6387`)

  **Format:** International format with country code is recommended
</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="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 cURL theme={null}
  curl --location 'https://api.tuesday.so/api/v1/people/lookup/phone?phone=%2B1%20713-408-6387' \
  --header 'X-API-KEY: your-api-key-here'
  ```

  ```javascript JavaScript theme={null}
  const phone = '+1 713-408-6387';
  const params = new URLSearchParams({ phone });

  const response = await fetch(
    `https://api.tuesday.so/api/v1/people/lookup/phone?${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/phone"
  params = {
      "phone": "+1 713-408-6387"
  }
  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
  $phone = "+1 713-408-6387";
  $params = http_build_query(['phone' => $phone]);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.tuesday.so/api/v1/people/lookup/phone?$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": "Houston",
          "country": "United States",
          "country_code": "US",
          "country_region": "NORAM",
          "first_name": "Matthew",
          "id": "tu_pacdp5w2z",
          "job_start_date": "2017-03-01",
          "last_name": "Lindstrom",
          "linkedin_url": "https://www.linkedin.com/in/mrlindstrom1",
          "name": "Matthew Lindstrom",
          "organization_id": "tu_oacidb4kh",
          "organizations.founded_year": 1997,
          "organizations.linkedin_url": "https://www.linkedin.com/company/waypoint-solutions-llc",
          "organizations.name": "Waypoint Business Solutions",
          "organizations.primary_domain": "waypointsolutions.com",
          "organizations.website_url": "https://www.waypointsolutions.com",
          "seniority": "Staff",
          "state": "Texas",
          "title": "Senior Engineer"
      },
      "statusCode": 200,
      "message": "Success"
  }
  ```
</ResponseExample>

## Phone Number Formats

<AccordionGroup>
  <Accordion title="Supported Formats">
    The API accepts various phone number formats:

    **Recommended (International):**

    * `+1 713-408-6387`
    * `+14155552671`
    * `+44 20 7946 0958`

    **Also Accepted:**

    * `(713) 408-6387`
    * `713-408-6387`
    * `7134086387`
  </Accordion>

  <Accordion title="Best Practices">
    For optimal results:

    * Include country code when possible (e.g., `+1` for US)
    * Use international format for non-US numbers
    * URL encode special characters in API requests
    * Ensure numbers are complete and valid
  </Accordion>
</AccordionGroup>

## Credit Usage

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

  <div className="text-sm text-gray-600">Credit per lookup</div>
</div>

<Note>
  Phone reverse lookup uses 1 credit per request. Unlike other people endpoints, this doesn't have additional enrichment options since contact information is already provided.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request - Missing Phone Number">
    ```json theme={null}
    {
        "statusCode": 400,
        "message": "Bad Request",
        "error": "Missing required parameter: phone"
    }
    ```
  </Accordion>

  <Accordion title="400 Bad Request - Invalid Phone Format">
    ```json theme={null}
    {
        "statusCode": 400,
        "message": "Bad Request",
        "error": "Invalid phone number format"
    }
    ```
  </Accordion>

  <Accordion title="404 Not Found - Phone Not Found">
    ```json theme={null}
    {
        "statusCode": 404,
        "message": "Not Found",
        "error": "No profile found for the provided phone number"
    }
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Phone Number Quality">
    * Business/mobile numbers typically have higher match rates
    * Landline numbers may have lower success rates
    * Recent numbers are more likely to return current information
    * Professional contact numbers yield better results than personal lines
  </Accordion>

  <Accordion title="Privacy Considerations">
    * Only lookup phone numbers you have legitimate business reasons to research
    * Respect privacy laws and regulations in your jurisdiction
    * Consider opt-in/opt-out mechanisms for contact enrichment
    * Use results responsibly for business purposes
  </Accordion>

  <Accordion title="Data Validation">
    * Verify phone numbers are properly formatted before lookup
    * Handle cases where numbers may have changed or been reassigned
    * Cross-reference results with other data points when possible
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Caller Identification" icon="phone">
    Identify unknown business callers and prepare for conversations
  </Card>

  <Card title="Contact Enrichment" icon="address-book">
    Add professional context to phone contacts in your database
  </Card>

  <Card title="Lead Verification" icon="shield-check">
    Verify legitimacy of phone-based leads and prospects
  </Card>

  <Card title="CRM Data Quality" icon="database">
    Enhance phone contact records with professional information
  </Card>
</CardGroup>

## Regional Considerations

<AccordionGroup>
  <Accordion title="United States & Canada">
    * 10-digit numbers: `(555) 123-4567` or `+1-555-123-4567`
    * Business numbers typically have higher match rates
    * Mobile numbers increasingly used for professional contact
  </Accordion>

  <Accordion title="International Numbers">
    * Always include country code: `+44 20 7946 0958`
    * Format varies by country - use standard international format
    * Business directories may be less comprehensive in some regions
  </Accordion>

  <Accordion title="Mobile vs. Landline">
    * Mobile numbers often have better match rates for professionals
    * Business landlines may connect to multiple employees
    * Consider the number type when interpreting results
  </Accordion>
</AccordionGroup>

## Related Endpoints

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