# Search Single Contact

Find and enrich a single contact using various search criteria. You can search by name, email, 
LinkedIn URL, or company information.
>##### Endpoint
  
GET https://api.lusha.com/v2/person
  


>##### Search Requirements
  
You must provide either:
- email OR
- linkedinUrl OR
- firstName AND lastName AND (companyName OR companyDomain)

>##### Notes: 
- Provide as much information as possible for better results
- Use refreshJobInfo=true to get the latest employment data
- Use filterBy parameter to specify what contact details you need
- Include the signals parameter to retriever contact signals (If no signals data is found for the specified period, the signals object will be empty but still present in the response.)
  - When requesting signals, you can optionally specify a start date using signalsStartDate.
  - Signals data is optional. If you don't include the signals parameter, no signals data will be returned.

---

⚠️ Important Notice - Unified Credits Plan Required

| Parameter | Requirement |
|-----------|-------------|
| revealEmails and revealPhones | Only available to customers on the Unified Credits pricing plan |
| Plan Restriction | Attempting to use these parameters on other plans will result in a 403 Unauthorized error |
| Default Behavior | When neither parameter is used, the API returns both email addresses and phone numbers, if available |

---

Endpoint: GET /v2/person
Security: ApiKeyAuth

## Query parameters:

  - `firstName` (string)
    The first name of the person
    Example: "Dustin"

  - `lastName` (string)
    The last name of the person
    Example: "Moskovitz"

  - `companyName` (string)
    The name of the company the person works at
    Example: "Lusha"

  - `companyDomain` (string)
    The domain name of the company
    Example: "lusha.com"

  - `email` (string)
    The email address of the person
    Example: "dustin@lusha.com"

  - `linkedinUrl` (string)
    The LinkedIn URL of the person
    Example: "https://www.linkedin.com/in/dustin/"

  - `refreshJobInfo` (boolean)
    Set to true to refresh and update the job details for the person. 
This ensures that outdated job information is replaced with the most recent data.
    Example: true

  - `filterBy` (string)
    Filters results based on specific contact details. Available options:
- phoneNumbers: Only return contacts with phone numbers
- emailAddresses: Only return contacts with email addresses

By default, results will include contacts with at least one contact detail.
    Enum: "phoneNumbers", "emailAddresses"

  - `revealEmails` (boolean)
    Set revealEmails=true to retrieve only the email address of the contact.
    Example: true

  - `revealPhones` (boolean)
    Set revealPhones=true to retrieve only the phone number of the contact.
    Example: true

  - `signals` (array)
    Array of signal types to retrieve for the contact.
- allSignals: All available signal types
- promotion: Promotion signals
- companyChange: Company change signals
    Enum: "allSignals", "promotion", "companyChange"

  - `signalsStartDate` (string)
    Start date for signal retrieval in YYYY-MM-DD format. Defaults to 6 months ago if not specified.
    Example: "2025-03-01"

  - `partialProfile` (boolean)
    Search for a single contact with the option to receive a partial profile.
    Example: true

## Response 200 fields (application/json):

  - `contact` (object, required)

  - `contact.error` (object,null, required)

  - `contact.error.code` (number, required)
    The code of the contact error
    Example: 3

  - `contact.error.name` (string, required)
    The name of the contact error
    Example: "EMPTY_DATA"

  - `contact.error.message` (string, required)
    The message of the contact error
    Example: "Could not find requested data"

  - `contact.isCreditCharged` (boolean, required)
    Indicates whether a credit charge was made for the contact
    Example: true

  - `contact.data` (object)

  - `contact.data.companyId` (number)
    A unique identifier for the company on Lusha
    Example: 123

  - `contact.data.firstName` (string)
    The first name of the person
    Example: "Dustin"

  - `contact.data.lastName` (string)
    The last name of the person
    Example: "Moskovitz"

  - `contact.data.fullName` (string)
    The full name of the person
    Example: "Dustin Moskovitz"

  - `contact.data.emails` (array)
    Simple array of email addresses (deprecated - use emailAddresses)
    Example: ["john.doe@example.com"]

  - `contact.data.emailAddresses` (array)
    Detailed email addresses with metadata

  - `contact.data.emailAddresses.email` (string)
    The email address (alternative to 'address')
    Example: "dustin@lusha.com"

  - `contact.data.emailAddresses.address` (string)
    The email address (alternative to 'email')
    Example: "dustin@lusha.com"

  - `contact.data.emailAddresses.emailType` (string)
    The type of email address (alternative to 'type')
    Enum: "work", "private"

  - `contact.data.emailAddresses.emailConfidence` (string)
    The confidence level of the email address
    Example: "A+"

  - `contact.data.emailAddresses.updateDate` (string)
    The update date of the email address
    Example: "2020-01-01"

  - `contact.data.phones` (array)
    Simple array of phone numbers (deprecated - use phoneNumbers)
    Example: [["+1 555-123-4567"]]

  - `contact.data.phoneNumbers` (array)
    Detailed phone numbers with metadata

  - `contact.data.phoneNumbers.number` (string)
    The phone number
    Example: "+1234567890"

  - `contact.data.phoneNumbers.phoneType` (string, required)
    The type of phone number
    Enum: "Mobile", "Direct", "Phone"

  - `contact.data.phoneNumbers.doNotCall` (boolean, required)
    Indicates whether the phone number is listed as "Do Not Call" (DNC).

  - `contact.data.phoneNumbers.updateDate` (string, required)
    The update date of the phone number
    Example: "2020-01-01"

  - `contact.data.personId` (number)
    The unique person identifier in Lusha
    Example: 123456

  - `contact.data.location` (object)

  - `contact.data.location.country` (string, required)
    The country where the person is located.
    Example: "Israel"

  - `contact.data.location.countryIso2` (string, required)
    The ISO 3166-1 alpha-2 country code of the person.
    Example: "IL"

  - `contact.data.location.country_iso2` (string)
    The ISO 3166-1 alpha-2 country code of the person.
    Example: "IL"

  - `contact.data.location.continent` (string, required)
    The continent where the person is located.
    Example: "Asia"

  - `contact.data.location.rawLocation` (string, required)
    The detailed address.
    Example: "800 Boylston St, Suite 1410, Boston, MA 02199, US"

  - `contact.data.location.region` (string)
    The region where the person is located.
    Example: "Tel Aviv"

  - `contact.data.location.city` (string)
    The city where the person is located.
    Example: "Tel Aviv"

  - `contact.data.location.cityId` (number)
    The ID of the city where the person is located.
    Example: 123

  - `contact.data.location.state` (string)
    The state where the person is located.
    Example: "Tel Aviv"

  - `contact.data.location.stateCode` (string)
    The state code of the person.
    Example: "IL"

  - `contact.data.location.state_code` (string)
    The state code of the person.
    Example: "IL"

  - `contact.data.location.street` (string)
    The street where the person is located.
    Example: "123 Main St"

  - `contact.data.location.locationCoordinates` (array)
    The coordinates of the person.
    Example: [32.0853,34.7818]

  - `contact.data.location.isEuContact` (boolean)
    Indicates whether the person is in the EU.
    Example: true

  - `contact.data.jobTitle` (object)

  - `contact.data.jobTitle.seniority` (string, required)
    The seniority of the person.
    Example: "Director"

  - `contact.data.jobTitle.title` (string, required)
    The title of the person.
    Example: "Director of Platform"

  - `contact.data.jobTitle.departments` (array, required)
    The departments of the person.
    Example: ["Engineering","Operations"]

  - `contact.data.socialLinks` (object)

  - `contact.data.socialLinks.linkedin` (string, required)
    The LinkedIn URL of the person
    Example: "https://www.linkedin.com/in/dustin/"

  - `contact.data.jobStartDate` (string)
    The start date at current position
    Example: "2020-01-01"

  - `contact.data.previousJob` (object)

  - `contact.data.previousJob.company` (object, required)

  - `contact.data.previousJob.company.name` (string)
    The name of the company, Required if no domain.
    Example: "Lusha"

  - `contact.data.previousJob.company.domain` (string)
    The domain of the company, Required if no name.
    Example: "lusha.com"

  - `contact.data.previousJob.company.isCurrent` (boolean, required)
    Indicates whether this is the person's current company
    Example: true

  - `contact.data.previousJob.company.jobTitle` (string)
    The job title of the person at the company
    Example: "Software Engineer"

  - `contact.data.previousJob.company.fqdn` (string)
    The fully qualified domain name of the company
    Example: "https://lusha.com"

  - `contact.data.previousJob.company.companySocialId` (string)
    The social ID associated with the company (if available)
    Example: "1234567890"

  - `contact.data.contactTags` (array)
    Tags associated with the contact

  - `contact.data.contactTags.id` (string, required)
    The ID of the contact tag
    Example: "123"

  - `contact.data.contactTags.name` (string, required)
    The name of the contact tag
    Example: "Prospect"

  - `contact.data.contactTags.color` (string, required)
    The color of the contact tag
    Example: "#000000"

  - `contact.data.updateDate` (string)
    The last update date of the contact data
    Example: "2020-01-01"

  - `contact.data.required` (any)

## Response 400 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 401 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 403 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 404 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 429 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 451 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 500 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]