Lusha Search API

openapi: 3.2.0
info:
  title: Lusha API Documentation Search API
  version: ''
  x-logo:
    url: https://www.lusha.com/logo.png
  license:
    name: Proprietary
    url: https://lusha.com/legal/terms
  description: '**This is the Lusha API V3 documentation.**


    V3 introduces a new search-then-enrich pattern, bulk operations, AI-powered lookalikes, and richer filter capabilities.'
  contact:
    name: Lusha Support
    url: https://api.lusha.com
    email: support@lusha.com
  termsOfService: https://lusha.com/legal/terms
  x-privacy-policy:
    name: Privacy Policy
    url: https://lusha.com/legal/privacy-notice/
servers:
- url: https://api.lusha.com
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Search
  description: '**Search APIs:** Find contacts or companies using known identifiers.


    Look up contacts by `id`, `linkedinUrl`, `email`, or `firstName` + `lastName` + `companyName`/`companyDomain`. Look up companies by `id`, `name`, or `domain`.


    Returns a non-PII preview of each profile with a `has` field listing available data points and a `canReveal` field showing what can be unlocked via Enrich.


    > **Billing:** Charged per successful result via the `api_search` action.'
  x-tag-expanded: true
paths:
  /v3/contacts/search:
    post:
      tags:
      - Search
      summary: Search Contacts
      operationId: searchContacts
      description: 'Look up contacts by identifier. Returns a non-PII preview of each profile — no emails or phone numbers.


        **Accepted identifiers (one required per contact):**

        - Lusha contact `id`

        - `linkedinUrl`

        - `email`

        - `firstName` + `lastName` + `companyName` or `companyDomain`


        Up to 100 contacts per request. Each result includes:

        - `has` — data points available on this profile

        - `canReveal` — what you can unlock via Enrich Contacts, and the credit cost


        Pass a `signals` filter to narrow results to contacts with recent activity (e.g. promotion, job change).


        > **Billing:** Charged per successful result via the `api_search` action.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ContactsSearchRequest'
            example:
              contacts:
              - clientReferenceId: my-ref-1
                firstName: Orit
                lastName: Shilvock
                companyName: Lusha
                companyDomain: lusha.com
              - clientReferenceId: my-ref-2
                linkedinUrl: https://www.linkedin.com/in/shmulikwillinger
              - clientReferenceId: my-ref-3
                email: gal.ashkelon@lusha.com
              - clientReferenceId: my-ref-4
                id: '12345'
              options:
                includePartialProfiles: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ContactsSearchResponse'
              example:
                requestId: 6e4b1192-9440-42c4-9a3e-793ddef6d73c
                results:
                - clientReferenceId: my-ref-1
                  id: '4415824633'
                  firstName: Orit
                  lastName: Shilvock
                  jobTitle:
                    title: Vice President of Partnerships
                    departments:
                    - Business Development
                    seniority: Vice President
                  company:
                    id: '16303253'
                    name: Lusha
                    domain: www.lusha.com
                    industry: Technology, Information & Media
                  location:
                    country: Israel
                    city: Tel Aviv
                  socialLinks:
                    linkedin: https://www.linkedin.com/in/orit-shilvock-6243bb5
                  has:
                  - firstName
                  - lastName
                  - jobTitle
                  - location
                  - socialLinks
                  - emails
                  canReveal:
                  - field: emails
                    credits: 1
                - clientReferenceId: my-ref-2
                  id: '4415824679'
                  firstName: Shmulik
                  lastName: Willinger
                  jobTitle:
                    title: Chief Architect
                    departments:
                    - Engineering & Technical
                    seniority: C-Suite
                  company:
                    id: '16303253'
                    name: Lusha
                    domain: www.lusha.com
                    industry: Technology, Information & Media
                  location:
                    country: Israel
                    city: Tel Aviv
                  socialLinks:
                    linkedin: https://www.linkedin.com/in/shmulikwillinger
                  has:
                  - firstName
                  - lastName
                  - jobTitle
                  - location
                  - socialLinks
                  - emails
                  canReveal:
                  - field: emails
                    credits: 1
                - clientReferenceId: my-ref-3
                  id: '4415824664'
                  firstName: Gal
                  lastName: Ashkelon
                  jobTitle:
                    title: Global Partner Program Manager
                    departments:
                    - Business Development
                    seniority: Manager
                  company:
                    id: '16303253'
                    name: Lusha
                    domain: www.lusha.com
                    industry: Technology, Information & Media
                  location:
                    country: Israel
                    city: Tel Aviv
                  socialLinks:
                    linkedin: https://www.linkedin.com/in/gal-ashkelon-39408557
                  has:
                  - firstName
                  - lastName
                  - jobTitle
                  - location
                  - socialLinks
                  - emails
                  canReveal:
                  - field: emails
                    credits: 1
                - clientReferenceId: my-ref-4
                  error:
                    code: NOT_FOUND
                    message: Contact not found
                billing:
                  creditsCharged: 1
                  resultsReturned: 3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v3/companies/search:
    post:
      tags:
      - Search
      summary: Search Companies
      operationId: searchCompanies
      description: 'Look up companies by identifier. Returns a preview of each company profile.


        **Accepted identifiers (at least one required per company):**

        - Lusha company `id`

        - `name`

        - `domain`


        Up to 100 companies per request. Each result includes a `has` field listing the data available via Enrich Companies.


        Pass a `signals` filter to narrow results to companies showing specific activity (e.g. headcount growth, hiring surge).


        > **Billing:** Charged per successful result via the `api_search` action.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3CompaniesSearchRequest'
            example:
              companies:
              - clientReferenceId: comp-ref-1
                name: Lusha
              - clientReferenceId: comp-ref-2
                domain: salesforce.com
              - clientReferenceId: comp-ref-3
                id: '16303253'
              options:
                includePartialProfiles: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3CompaniesSearchResponse'
              example:
                requestId: abd4a213-d33b-4565-b9b6-55c19c65cc47
                results:
                - clientReferenceId: comp-ref-1
                  id: '16303253'
                  name: Lusha
                  domain: www.lusha.com
                  employeeCount:
                    exact: 364
                    min: 201
                    max: 500
                  industry: Technology, Information & Media
                  location:
                    city: Boston
                    state: Massachusetts
                    country: United States
                    countryIso2: US
                    continent: North America
                  socialLinks:
                    linkedin: https://www.linkedin.com/company/lushadata
                  has:
                  - alternativeName
                  - alternativeDomains
                  - description
                  - companyType
                  - yearFounded
                  - subIndustry
                  - specialities
                  - sicCodes
                  - naicsCodes
                  - additionalLocations
                  - linkedinFollowers
                  - funding
                  - popularityTier
                  - logoUrl
                  - employeesByDepartment
                  - employeesByLocation
                  - employeesBySeniority
                  - competitors
                  - businessModel
                  - emails
                  - keywords
                  - socialLinks
                  canReveal:
                  - field: employeesByDepartment
                    credits: 1
                  - field: employeesByLocation
                    credits: 1
                  - field: employeesBySeniority
                    credits: 1
                  - field: competitors
                    credits: 1
                - clientReferenceId: comp-ref-2
                  id: '12790225'
                  name: Salesforce
                  domain: www.salesforce.com
                  employeeCount:
                    exact: 88711
                    min: 100001
                    max: 10000000
                  industry: Technology, Information & Media
                  location:
                    city: San Francisco
                    state: California
                    country: United States
                    countryIso2: US
                    continent: North America
                  socialLinks:
                    linkedin: https://www.linkedin.com/company/salesforce
                  has:
                  - alternativeName
                  - alternativeDomains
                  - description
                  - companyType
                  - subIndustry
                  - sicCodes
                  - naicsCodes
                  - additionalLocations
                  - linkedinFollowers
                  - revenueRange
                  - intent
                  - popularityTier
                  - logoUrl
                  - employeesByDepartment
                  - employeesByLocation
                  - employeesBySeniority
                  - competitors
                  - phones
                  - emails
                  - socialLinks
                  canReveal:
                  - field: employeesByDepartment
                    credits: 1
                  - field: employeesByLocation
                    credits: 1
                  - field: employeesBySeniority
                    credits: 1
                  - field: competitors
                    credits: 1
                  - field: intent
                    credits: 0
                billing:
                  creditsCharged: 1
                  resultsReturned: 3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - statusCode
      - message
      properties:
        statusCode:
          type: integer
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Error message
          example: Validation failed
        errors:
          type: array
          items:
            type: string
          description: Detailed error messages (optional, only for validation errors)
          example:
          - 'entityType must be one of: contact, company'
    V3ItemError:
      type: object
      description: Per-item error in a batch response
      properties:
        code:
          type: string
          enum:
          - NOT_FOUND
          - COMPLIANCE_RESTRICTED
          - ENRICH_FAILED
          - NO_SCORE
          example: NOT_FOUND
        message:
          type: string
          example: Contact not found
    V3SearchOptions:
      type: object
      description: Additional options for search requests
      properties:
        includePartialProfiles:
          type: boolean
          description: Include partial profiles in results
          example: true
    V3CompanyPreview:
      type: object
      properties:
        clientReferenceId:
          type: string
          example: comp-ref-1
        id:
          type: string
          example: '16303253'
        name:
          type: string
          example: Lusha
        domain:
          type: string
          example: www.lusha.com
        employeeCount:
          type: object
          properties:
            exact:
              type: integer
              example: 364
            min:
              type: integer
              example: 201
            max:
              type: integer
              example: 500
        industry:
          type: string
          example: Technology, Information & Media
        location:
          type: object
          properties:
            city:
              type: string
              example: London
            state:
              type: string
              example: England
            stateCode:
              type: string
              description: Free field. ISO/postal state or region code, when available.
              example: MA
            country:
              type: string
              example: United Kingdom
            countryIso2:
              type: string
              example: GB
            continent:
              type: string
              example: Europe
        socialLinks:
          type: object
          properties:
            linkedin:
              type: string
              example: https://www.linkedin.com/company/lushadata
        has:
          type: array
          items:
            type: string
          description: 'Available data points that can be revealed via Enrich Companies. Includes base firmographic fields plus new revealable fields: employeesByDepartment, employeesByLocation, employeesBySeniority, competitors, businessModel, phones, emails, keywords, socialLinks, estimatedAnnualItSpend, monthlyWebsiteTraffic.

            '
          example:
          - alternativeName
          - alternativeDomains
          - description
          - companyType
          - yearFounded
          - subIndustry
          - specialities
          - sicCodes
          - naicsCodes
          - additionalLocations
          - linkedinFollowers
          - popularityTier
          - logoUrl
          - employeesByDepartment
          - employeesByLocation
          - employeesBySeniority
          - competitors
          - businessModel
          - phones
          - emails
          - keywords
          - socialLinks
          - estimatedAnnualItSpend
          - monthlyWebsiteTraffic
        canReveal:
          type: array
          description: 'Data fields that can be revealed via Enrich Companies, with the credit cost per field. A cost of 0 means the field has already been revealed for this account.

            '
          items:
            $ref: '#/components/schemas/V3CanRevealItem'
          example:
          - field: employeesByDepartment
            credits: 1
          - field: employeesByLocation
            credits: 1
          - field: employeesBySeniority
            credits: 1
          - field: competitors
            credits: 1
          - field: intent
            credits: 0
          - field: estimatedAnnualItSpend
            credits: 1
          - field: monthlyWebsiteTraffic
            credits: 1
        signalTypes:
          type: array
          items:
            type: string
          example:
          - headcountIncrease3m
        error:
          $ref: '#/components/schemas/V3ItemError'
    V3ContactSignalsDto:
      type: object
      required:
      - types
      properties:
        types:
          type: array
          items:
            type: string
            enum:
            - allSignals
            - promotion
            - companyChange
          example:
          - promotion
          - companyChange
        startDate:
          type: string
          format: date
          example: '2025-01-01'
        maxResultsPerSignal:
          type: integer
          minimum: 1
          maximum: 100
          example: 10
    V3ContactSearchItem:
      type: object
      properties:
        clientReferenceId:
          type: string
          example: my-ref-1
        id:
          type: string
          example: '12345'
        linkedinUrl:
          type: string
          example: https://www.linkedin.com/in/orit-shilvock-6243bb5
        email:
          type: string
          format: email
          example: orit.shilvock@lusha.com
        firstName:
          type: string
          example: Orit
        lastName:
          type: string
          example: Shilvock
        companyName:
          type: string
          example: Lusha
        companyDomain:
          type: string
          example: lusha.com
    V3Billing:
      type: object
      description: Credit usage summary for a V3 API request
      properties:
        creditsCharged:
          type: integer
          description: Total credits charged for this request
          example: 3
        resultsReturned:
          type: integer
          description: Number of successful results returned
          example: 1
    V3ContactsSearchResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          example: 3c7f6d96-4a72-40cd-96c1-2efcfabeb727
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3ContactPreview'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3CompanySearchItem:
      type: object
      properties:
        clientReferenceId:
          type: string
          example: comp-ref-1
        id:
          type: string
          example: '16303253'
        name:
          type: string
          example: Lusha
        domain:
          type: string
          example: lusha.com
    V3CompaniesSearchResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3CompanyPreview'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3ContactsSearchRequest:
      type: object
      required:
      - contacts
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/V3ContactSearchItem'
          minItems: 1
          maxItems: 100
        options:
          $ref: '#/components/schemas/V3SearchOptions'
        signals:
          $ref: '#/components/schemas/V3ContactSignalsDto'
    V3ContactPreview:
      type: object
      properties:
        clientReferenceId:
          type: string
          example: my-ref-1
        id:
          type: string
          example: '4389064704'
        firstName:
          type: string
          example: Orit
        lastName:
          type: string
          example: Shilvock
        jobTitle:
          type: object
          properties:
            title:
              type: string
              example: Vice President of Partnerships
            departments:
              type: array
              items:
                type: string
              example:
              - Business Development
            seniority:
              type: string
              example: Vice President
        company:
          type: object
          properties:
            id:
              type: string
              example: '16303253'
            name:
              type: string
              example: Lusha
            domain:
              type: string
              example: www.lusha.com
        location:
          type: object
          properties:
            country:
              type: string
              example: Israel
            state:
              type: string
              example: Tel Aviv District
            city:
              type: string
              example: Tel Aviv
        socialLinks:
          type: object
          properties:
            linkedin:
              type: string
              example: https://www.linkedin.com/in/orit-shilvock-6243bb5
        has:
          type: array
          items:
            type: string
          example:
          - firstName
          - lastName
          - jobTitle
          - location
          - socialLinks
          - emails
        canReveal:
          type: array
          items:
            $ref: '#/components/schemas/V3CanRevealItem'
        signalTypes:
          type: array
          items:
            type: string
          example:
          - promotion
          - companyChange
        error:
          $ref: '#/components/schemas/V3ItemError'
    V3CanRevealItem:
      type: object
      description: Indicates a data type that can be revealed and its credit cost
      properties:
        field:
          type: string
          enum:
          - emails
          - phones
          example: emails
        credits:
          type: integer
          description: Credit cost (0 when already revealed for this account)
          example: 1
    V3CompaniesSearchRequest:
      type: object
      required:
      - companies
      properties:
        companies:
          type: array
          items:
            $ref: '#/components/schemas/V3CompanySearchItem'
          minItems: 1
          maxItems: 100
        options:
          $ref: '#/components/schemas/V3SearchOptions'
        signals:
          $ref: '#/components/schemas/V3CompanySignalsDto'
    V3CompanySignalsDto:
      type: object
      required:
      - types
      properties:
        types:
          type: array
          items:
            type: string
            enum:
            - allSignals
            - linkedinActivityIntent
            - websiteTrafficDecrease
            - websiteTrafficIncrease
            - itSpendIncrease
            - itSpendDecrease
            - surgeInHiring
            - headcountIncrease1m
            - headcountIncrease3m
            - headcountIncrease6m
            - headcountIncrease12m
            - headcountDecrease1m
            - headcountDecrease3m
            - headcountDecrease6m
            - headcountDecrease12m
            - surgeInHiringByDepartment
            - surgeInHiringByLocation
            - riskNews
            - commercialActivityNews
            - corporateStrategyNews
            - financialEventsNews
            - peopleNews
            - marketIntelligenceNews
            - productActivityNews
          example:
          - headcountIncrease3m
          - surgeInHiring
        startDate:
          type: string
          format: date
          example: '2025-01-01'
        maxResultsPerSignal:
          type: integer
          minimum: 1
          maximum: 100
          example: 10
  responses:
    BadRequest:
      description: Bad request - invalid input data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 400
            message: Invalid request parameters
    TooManyRequests:
      description: Too many requests - rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 429
            message: Too many requests. Please wait before making another request.
      headers:
        x-rate-limit-daily:
          description: Total requests allowed per day
          schema:
            type: integer
        x-daily-requests-left:
          description: Requests remaining in daily quota
          schema:
            type: integer
        x-rate-limit-hourly:
          description: Total requests allowed per hour
          schema:
            type: integer
        x-hourly-requests-left:
          description: Requests remaining in hourly quota
          schema:
            type: integer
        x-rate-limit-minute:
          description: Total requests allowed per minute
          schema:
            type: integer
        x-minute-requests-left:
          description: Requests remaining in current minute window
          schema:
            type: integer
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 401
            message: Invalid API key
    Forbidden:
      description: Forbidden - account inactive, V3 access not enabled, or plan does not include this feature
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            accountInactive:
              summary: Account inactive
              value:
                statusCode: 403
                message: Your account is not active. Please reach out to support at support@lusha.com
            v3NotEnabled:
              summary: V3 access not enabled
              value:
                statusCode: 403
                message: V3 API access is not enabled for your account
    PaymentRequired:
      description: Payment required - insufficient credits
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 402
            message: Insufficient credits for this operation
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: 'Your Lusha API key. You can find this in your Lusha dashboard under API settings.

        Include this key in the `api_key` header for all requests.

        '