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: "<blockquote class=\"callout\">\n\n **This is the Lusha API V3 documentation.** \n \n V3 introduces a new search-then-enrich pattern, bulk operations, AI-powered lookalikes, and richer filter capabilities. All endpoints are under `https://api.lusha.com/v3/`.\n\n  For more information on V3, refer to the [Migration Guide](/tutorials/v3-migration-guide).\n\n</blockquote>\n\n  --- \n\nLusha provides a RESTful API for querying a comprehensive dataset of business profiles and company information. Built for teams running prospecting, enrichment, automation, and analytics workflows that need accurate, continuously updated business data. The API supports both real-time and bulk use cases.\n\nUse the Lusha API to **search for new prospects**, **enrich existing records**, **react to real-world changes**, and **expand coverage** with AI-powered lookalike recommendations.\n\n> All API requests must be made over **HTTPS**. All responses are returned in **JSON** format.\n\n--- \n## Available Endpoints\n\n| Category | Description |\n|---|---|\n| [**Search**](#tag/Search) | Find contacts or companies using known identifiers |\n| [**Enrich**](#tag/Enrich) | Retrieve full profile data for contacts or companies by ID |\n| [**Search & Enrich**](#tag/Search-and-Enrich) | Find and retrieve full contact or company data in a single call |\n| [**Prospecting**](#tag/Prospecting) | Filter-based search across contacts and companies |\n| [**Lookalikes**](#tag/Lookalikes) | AI-powered recommendations for similar contacts and companies |\n| [**Buying Group**](#tag/Buying-Group) | Identify decision makers, champions, and end users within target accounts |\n| [**Contacts Tables**](#tag/Contacts-Tables) | Persist, organize, and enrich contacts in reusable tables |\n| [**Companies Tables**](#tag/Companies-Tables) | Persist, organize, and enrich companies in reusable tables |\n| [**Signals**](#tag/Signals) | Real-world activity data for contacts and companies |\n| [**Website Visitors**](#tag/Website-Visits) | Companies ranked by website-visit signals for your tracked domains |\n| [**Filters**](#tag/Filters) | Discover valid filter values for prospecting |\n| [**Webhooks**](#tag/Webhooks) | Real-time signal notifications via HTTP callbacks |\n| [**Account**](#tag/Account) | Usage, credits, rate limits, and pricing |\n\n<blockquote class=\"callout\">\n\n **Waterfall Reveal for Contact Enrichment.**\n\n  Enrich Contacts now supports `waterfallEnabled`. Fall through to your enabled third-party providers when Lusha's own data has no match, for extra reach on hard-to-match contacts. On by default once your account has it turned on - pass `waterfallEnabled: false` to opt a specific call out. [See Enrich Contacts](#operation/enrichContacts).\n\n</blockquote>\n\n---\n\n## Data Source and Privacy\n\n**Lusha is a search platform.** The data provided is not created or directly managed by Lusha. It is sourced from publicly available information and trusted business partners.\n\nFor more details on how we collect and handle data, see our [Privacy Policy](https://lusha.com/legal/privacy-notice/).\n\n---\n\n## Authentication\n\nAll API requests require an **API key** linked to your Lusha account and plan. Pass your key in the `api_key` request header on every call.\n\n> Generate and manage your API key in the [Lusha dashboard](https://dashboard.lusha.com/enrich/api).\n\nStore your API key securely and use it only in **server-side environments**.\n\n---\n\n## Rate Limiting\n\nLusha enforces rate limits on a per-plan basis to ensure fair usage and platform stability. Limits are applied across multiple time windows (per minute, per hour, and per day), and vary depending on your account plan.\n\nRate limits for the **Credit Usage API** differ from standard endpoint limits.\n\n> **Note:** To check your current plan's limits, visit the [Lusha Help Center](https://info.lusha.com/en/articles/163856-all-there-is-to-know-about-lusha-s-api) or contact your account manager.\n\n**Rate Limit Response Headers**\n\n| Header | Description |\n|--------|-------------|\n| `x-rate-limit-daily` | Total requests allowed per day |\n| `x-daily-requests-left` | Requests remaining in your daily quota |\n| `x-daily-usage` | Requests made in the current daily period |\n| `x-rate-limit-hourly` | Total requests allowed per hour |\n| `x-hourly-requests-left` | Requests remaining in your hourly quota |\n| `x-hourly-usage` | Requests made in the current hourly period |\n| `x-rate-limit-minute` | Total requests allowed per minute |\n| `x-minute-requests-left` | Requests remaining in the current minute window |\n| `x-minute-usage` | Requests made in the current minute window |\n\n---\n## Error Codes\n\nLusha uses standard HTTP status codes to indicate the result of each request.\n\n| Code | Name | Description |\n|------|------|-------------|\n| `200` | OK | Request was successful |\n| `400` | Bad Request | Request is malformed or missing required fields |\n| `401` | Unauthorized | API key is missing or invalid |\n| `402` | Payment Required | Insufficient credits or payment needed |\n| `403` | Forbidden | Account is inactive. Contact support@lusha.com |\n| `404` | Not Found | Endpoint or resource does not exist |\n| `429` | Too Many Requests | Rate limit or daily quota exceeded |\n| `451` | Unavailable For Legal Reasons | Request blocked due to GDPR regulations |\n| `499` | Client Closed Request | Request timed out before completing |\n| `5XX` | Server Error | Issue on Lusha's end. Retry with exponential backoff |\n\n**Error Response Format**\n\n```json\n{\n  \"statusCode\": 400,\n  \"message\": \"Invalid request parameters\"\n}\n```\n\n**Tables-specific error codes**\n\n| Code | Status | Meaning |\n|---|---|---|\n| `TABLE_NOT_FOUND` | 404 | The `table_id` does not exist or is not accessible to this account |\n| `COLUMN_NOT_FOUND` | 404 | The `column_id` does not exist on the given table |\n| `TABLE_NAME_CONFLICT` | 409 | A table with this name already exists |\n\nTables error bodies use the shape `{ \"message\": \"...\", \"code\": <status>, ... }` rather than the `statusCode`/`errors` shape used elsewhere in this doc.\n\n**Limits:** up to 500 entity IDs per add/remove call · max 50,000 entities per table · max 500 tables per account · `page` 0–100 · `size` default 100.\n\n**Tips for Handling Errors**\n\n- Verify your API key is correct and active\n- Read the `message` field for specific troubleshooting details\n- For `429` errors, wait before retrying\n- For `5XX` errors, use exponential backoff before retrying\n"
  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:
    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
    V3CompaniesSearchResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3CompanyPreview'
        billing:
          $ref: '#/components/schemas/V3Billing'
    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'
    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'
    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
    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
    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'
    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'
    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'
    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
    V3SearchOptions:
      type: object
      description: Additional options for search requests
      properties:
        includePartialProfiles:
          type: boolean
          description: Include partial profiles in results
          example: true
    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
    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'
    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
  responses:
    BadRequest:
      description: Bad request - invalid input data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 400
            message: Invalid request parameters
    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
    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
    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.

        '