openapi: 3.0.3
info:
  title: Lusha API Documentation
  version: ''
  x-logo:
    url: https://www.lusha.com/logo.png
  license:
    name: Proprietary
    url: https://lusha.com/legal/terms
  description: >
    <blockquote class="callout">

     **This is the Lusha API V3 documentation.** 
     
     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/`.

      For more information on V3, refer to the [Migration Guide](/tutorials/v3-migration-guide).

    </blockquote>

      --- 

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


    Use the Lusha API to **search for new prospects**, **enrich existing
    records**, **react to real-world changes**, and **expand coverage** with
    AI-powered lookalike recommendations.


    > All API requests must be made over **HTTPS**. All responses are returned
    in **JSON** format.


    --- 

    ## Available Endpoints


    | Category | Description |

    |---|---|

    | [**Enrichment**](#tag/Enrichment) | Search and enrich contacts and
    companies by identifier |

    | [**Prospecting**](#tag/Prospecting) | Filter-based search across contacts
    and companies |

    | [**Lookalikes**](#tag/Lookalikes) | AI-powered recommendations for similar
    contacts and companies |

    | [**Signals**](#tag/Signals) | Real-world activity data for contacts and
    companies |

    | [**Filters**](#tag/Filters) | Discover valid filter values for prospecting
    |

    | [**Webhooks**](#tag/Webhooks) | Real-time signal notifications via HTTP
    callbacks |

    | [**Account**](#tag/Account) | Usage, credits, rate limits, and pricing |


    ---


    ## Data Source and Privacy


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


    For more details on how we collect and handle data, see our [Privacy
    Policy](https://lusha.com/legal/privacy-notice/).


    ---


    ## Authentication


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


    > Generate and manage your API key in the [Lusha
    dashboard](https://dashboard.lusha.com/enrich/api).


    Store your API key securely and use it only in **server-side environments**.


    ---


    ## Rate Limiting


    Lusha enforces rate limits to ensure fair usage and protect against
    excessive load.


    | Scope | Limit |

    |-------|-------|

    | General endpoints | 25 requests per second |

    | Credit Usage API | 5 requests per minute |


    > Rate limits may vary by account type and plan. Contact your account
    manager or [Lusha support](mailto:support@lusha.com) if you frequently hit
    limits.


    **Rate Limit Response Headers**


    | Header | Description |

    |--------|-------------|

    | `x-rate-limit-daily` | Total requests allowed per day |

    | `x-daily-requests-left` | Requests remaining in your daily quota |

    | `x-daily-usage` | Requests made in the current daily period |

    | `x-rate-limit-hourly` | Total requests allowed per hour |

    | `x-hourly-requests-left` | Requests remaining in your hourly quota |

    | `x-hourly-usage` | Requests made in the current hourly period |

    | `x-rate-limit-minute` | Total requests allowed per minute |

    | `x-minute-requests-left` | Requests remaining in the current minute window
    |

    | `x-minute-usage` | Requests made in the current minute window |


    ---

    ## Error Codes


    Lusha uses standard HTTP status codes to indicate the result of each
    request.


    | Code | Name | Description |

    |------|------|-------------|

    | `200` | OK | Request was successful |

    | `400` | Bad Request | Request is malformed or missing required fields |

    | `401` | Unauthorized | API key is missing or invalid |

    | `402` | Payment Required | Insufficient credits or payment needed |

    | `403` | Forbidden | Account is inactive. Contact support@lusha.com |

    | `404` | Not Found | Endpoint or resource does not exist |

    | `429` | Too Many Requests | Rate limit or daily quota exceeded |

    | `451` | Unavailable For Legal Reasons | Request blocked due to GDPR
    regulations |

    | `499` | Client Closed Request | Request timed out before completing |

    | `5XX` | Server Error | Issue on Lusha's end. Retry with exponential
    backoff |


    **Error Response Format**


    ```json

    {
      "statusCode": 400,
      "message": "Invalid request parameters"
    }

    ```


    **Tips for Handling Errors**


    - Verify your API key is correct and active

    - Read the `message` field for specific troubleshooting details

    - For `429` errors, wait before retrying

    - For `5XX` errors, use exponential backoff before retrying
  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: Enrichment
    description: >
      **Enrichment APIs:** Search and enrich contacts and companies.


      The V3 API uses a **search-then-enrich** pattern:


      1. **Search** — Find contacts or companies by identifier. Returns previews
      with non-PII data and a `has` field listing available data points.

      2. **Enrich** — Reveal full data (emails, phones, firmographics) using IDs
      from search.


      You can also use **Search and Enrich** to combine both steps in a single
      call.


      **Supported identifiers**

      - Contacts: `id`, LinkedIn URL, email, or name + company

      - Companies: `id`, name, or domain


      Optionally filter results by signal types using the `signals` parameter
      (see **Signals** section).


      **Billing:** Search uses a capture/charge model (`api_search`). Enrich
      charges per data point revealed (`revealEmail`, `revealPhone`,
      `reveal_company`).
    x-tag-expanded: true
  - name: Prospecting
    description: >
      **Prospecting APIs:** Filter-based search for contacts and companies.


      Use prospecting to find new records that match your Ideal Customer Profile
      (ICP). Apply rich filters across:


      - **Contact attributes:** title, seniority, location, signals

      - **Company attributes:** size, revenue, industry, technologies, intent


      Results are paginated: up to **1,000 pages x 50 results = 50,000 results**
      per query. Responses use the same `ContactPreview` and `CompanyPreview`
      structures as the search endpoints.


      **Billing:** Uses the capture/charge model with `api_search` actions.
      Signal charges apply additionally.
    x-tag-expanded: true
  - name: Lookalikes
    description: >
      **Lookalike APIs:** Use AI-powered recommendations to discover contacts
      and companies similar to your best existing customers. The Contact
      Lookalikes and Company Lookalikes endpoints return paginated results you
      can pipe directly into Enrich for full data.
    x-tag-expanded: true
  - name: Signals
    description: >
      Real-world activity data for contacts and companies.


      Signals are available as standalone endpoints or as an optional `signals`
      filter on Search and Prospecting endpoints.


      **Contact signal types:** `promotion`, `companyChange`, `allSignals`


      **Company signal types:** `headcountIncrease1m/3m/6m/12m`,
      `headcountDecrease1m/3m/6m/12m`, `surgeInHiring`,
      `surgeInHiringByDepartment`, `surgeInHiringByLocation`,
      `websiteTrafficIncrease`, `websiteTrafficDecrease`, `itSpendIncrease`,
      `itSpendDecrease`, `riskNews`, `commercialActivityNews`,
      `corporateStrategyNews`, `financialEventsNews`, `peopleNews`,
      `marketIntelligenceNews`, `productActivityNews`, `allSignals`


      Credits are charged per matched signal per result via `showSignalsContact`
      or `showSignalsCompany`.
    x-tag-expanded: true
  - name: Filters
    description: >
      **Filter APIs:** Retrieve available filter values for prospecting.


      Use the discovery endpoints to list all available filter types, then fetch
      valid values for a specific filter type before building a prospecting
      request.


      **Contact filter types:** `departments`, `seniority`,
      `existingDataPoints`, `countries`, `locations`


      **Company filter types:** `names`, `sizes`, `revenues`, `locations`,
      `sics`, `naics`, `industriesLabels`, `intentTopics`, `technologies`
    x-tag-expanded: true
  - name: Webhooks
    description: >
      Subscribe to real-time notifications when contacts change jobs or
      companies experience key business events.


      Webhooks deliver HTTP POST requests to your endpoints when signals occur -
      from promotions and job changes to company growth.


      > For a full list of available signals, refer to [**Signal
      Options**](https://docs.lusha.com/apis/openapi/signals/getsignaloptions).

      ---

      **Key Features:**

      - Real-time contact & company signal notifications

      - Bulk subscription management (up to 25 items per request)

      - Secure delivery with HMAC-SHA256 signatures

      - Delivery monitoring with audit logs

       **Available Endpoints:**

      | Method | Endpoint | Purpose |

      |--------|----------|---------|

      | POST | `/api/subscriptions` | Create subscriptions (bulk supported) |

      | GET | `/api/subscriptions` | List all subscriptions |

      | GET | `/api/subscriptions/{id}` | Get subscription by ID |

      | PATCH | `/api/subscriptions/{id}` | Update subscription |

      | POST | `/api/subscriptions/delete` | Delete subscriptions (bulk
      supported) |

      | POST | `/api/subscriptions/{id}/test` | Test subscription delivery |

      | GET | `/api/audit-logs` | Get webhook delivery logs |

      | GET | `/api/audit-logs/stats` | Get delivery statistics |

      | GET | `/api/account/secret` | Get account webhook secret |

      | POST | `/api/account/secret/regenerate` | Regenerate account secret |

      | POST | `/api/subscriptions/opt-out` | Subscribe to contact opt-out
      notifications |


      > **Webhook Delivery Acknowledgment:** When receiving webhook deliveries
      (POST requests), your endpoint must acknowledge with a specific response
      format. See the [Create Subscription](#operation/createSubscription)
      endpoint for the required acknowledgment structure.
            ---

      <details>

      <summary><strong>Rate Limits</strong></summary>


      | Operation | Limit |

      |-----------|-------|

      | API Requests | 100 requests/minute per account |

      | Create Subscriptions | 25 items per request |

      | Delete Subscriptions | 25 items per request |


      </details>


      ---


      <details>

      <summary><strong>Security & Verification</strong></summary>


      **HTTPS Requirement:**

      - Production webhook URLs **must** use HTTPS

      - HTTP URLs are not accepted


      **Signature Verification:**


      All webhook deliveries include an `X-Lusha-Signature` header containing an
      HMAC-SHA256 signature. Verify this signature to ensure the request is from
      Lusha:


      1. Extract the `X-Lusha-Signature` and `X-Lusha-Timestamp` headers

      2. Concatenate: `timestamp + "." + JSON.stringify(payload)`

      3. Compute HMAC-SHA256 using your webhook secret

      4. Compare the computed signature with the received signature


      **Example (Node.js):**

      ```javascript

      const crypto = require('crypto');


      function verifySignature(payload, signature, timestamp, secret) {
        const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;
        const expectedSignature = crypto
          .createHmac('sha256', secret)
          .update(signedPayload)
          .digest('hex');
        
        return crypto.timingSafeEqual(
          Buffer.from(signature),
          Buffer.from(expectedSignature)
        );
      }

      ```


      > **Security Best Practice:** Always verify webhook signatures to prevent
      spoofed requests.


      </details>


      ---


      <details>

      <summary><strong>Credits & Billing</strong></summary>


      **Credit Charges:**

      - Credits are charged when signals are detected and delivered to your
      webhook

      - The `creditsCharged` field in the webhook payload indicates how many
      credits were used

      - Credits are deducted from your account balance per signal type


      **No Duplicate Charges:**

      - Each signal is delivered once and charged once

      - Webhook delivery retries do not incur additional charges


      </details>


      ---


      <details>

      <summary><strong>Error Response Format</strong></summary>


      All error responses follow this format:

      ```json

      {
        "statusCode": 400,
        "message": "Validation failed",
        "errors": ["entityType must be one of: contact, company"]
      }

      ```


      | Field | Type | Description |

      |-------|------|-------------|

      | `statusCode` | number | HTTP status code |

      | `message` | string | Error message |

      | `errors` | string[] | Detailed error messages (optional) |


      </details>
          
      ---
    x-tag-expanded: true
  - name: Account
    description: >
      **Account API:** Retrieve account usage, credit balance, rate limits, plan
      details, and pricing.


      Use this endpoint to monitor consumption and understand the credit cost of
      each action type in the public API flow.


      > **Rate limit:** 5 requests per minute.
    x-tag-expanded: true
paths:
  /v3/contacts/search:
    post:
      tags:
        - Enrichment
      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/contacts/enrich:
    post:
      tags:
        - Enrichment
      summary: Enrich Contacts
      operationId: enrichContacts
      description: >
        Reveal full contact data for contacts you've already found via Search
        Contacts.


        Pass up to 100 contact `ids` (from the search response). Use the
        `reveal` field to control what gets unlocked:

        - `emails` — work and personal email addresses

        - `phones` — mobile and direct phone numbers

        - Omit `reveal` to get both by default


        > **Tip:** If `canReveal.credits` is `0` in the search response, that
        data has already been revealed for your account — re-enriching it is
        free.


        > **Billing:** Charged per revealed field (email or phone) via
        per-datapoint pricing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ContactsEnrichRequest'
            example:
              ids:
                - '4389064654'
                - '4389064624'
              reveal:
                - emails
                - phones
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ContactsEnrichResponse'
              example:
                requestId: 71581363-f73d-46e1-9115-ecbd771b964b
                results:
                  - id: '4389064654'
                    firstName: Daniel
                    lastName: Turgeman
                    fullName: Daniel Turgeman
                    jobTitle:
                      title: Technical Product Manager
                      departments:
                        - Product
                      seniority: Manager
                    location:
                      country: Israel
                      countryIso2: IL
                      city: Tel Aviv
                      continent: Asia
                      coordinates:
                        - 34.78057098388672
                        - 32.08087921142578
                      isEuContact: false
                    tags: []
                    emails:
                      - email: daniel.t@lusha.com
                        type: work
                        confidence: A+
                        updateDate: '2026-04-23'
                    phones: []
                    company:
                      id: '16303253'
                      name: Lusha
                      domain: www.lusha.com
                      industry: Technology, Information & Media
                    socialLinks:
                      linkedin: https://www.linkedin.com/in/daniel-turgeman-49676b161
                    previousEmployment: []
                    updateDate: '2026-04-23'
                billing:
                  creditsCharged: 2
                  resultsReturned: 2
        '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/contacts/search-and-enrich:
    post:
      tags:
        - Enrichment
      summary: Search and Enrich Contacts
      operationId: searchAndEnrichContacts
      description: >
        Find contacts and reveal their full data in a single call. Combines
        Search and Enrich into one request.


        Provide contact identifiers the same way you would for Search Contacts.
        Use the `reveal` field to control what gets unlocked (`emails`,
        `phones`, or both).


        Up to 100 contacts per request.


        > **Billing:** Two charges apply — one for the search (`api_search`) and
        one per revealed field. The `billing.creditsCharged` in the response
        reflects the total.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ContactsSearchAndEnrichRequest'
            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
              reveal:
                - emails
                - phones
              options:
                includePartialProfiles: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ContactsSearchAndEnrichResponse'
              example:
                requestId: 211ee5da-3c0d-4621-9fa5-140e393a3ced
                results:
                  - clientReferenceId: my-ref-1
                    id: '4389064704'
                    firstName: Orit
                    lastName: Shilvock
                    fullName: Orit Shilvock
                    emails:
                      - email: orit.shilvock@lusha.com
                        type: work
                        confidence: A+
                        updateDate: '2026-04-23'
                    phones: []
                    tags: []
                    previousEmployment: []
                    updateDate: '2026-04-23'
                billing:
                  creditsCharged: 2
                  resultsReturned: 2
        '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:
        - Enrichment
      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'
  /v3/companies/enrich:
    post:
      tags:
        - Enrichment
      summary: Enrich Companies
      operationId: enrichCompanies
      description: >
        Reveal full company data for companies you've already found via Search
        Companies.


        Pass up to 100 company `ids` (from the search response). Each enriched
        result includes:

        - Firmographics: size, revenue range, year founded, company type

        - Industry: primary industry, sub-industry, SIC/NAICS codes

        - Locations: HQ and additional office sites

        - Technologies, funding rounds, buyer intent topics

        - LinkedIn followers, logo URL, social links


        > **Billing:** Charged per successful result via the `reveal_company`
        action.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3CompaniesEnrichRequest'
            example:
              ids:
                - '16303253'
                - '12790225'
              reveal:
                - employeesByLocation
                - employeesByDepartment
                - employeesBySeniority
                - competitors
                - intent
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3CompaniesEnrichResponse'
              example:
                requestId: 5e8f5993-a0a3-4510-bc90-7b4506272c68
                results:
                  - id: '16303253'
                    name: Lusha
                    alternativeName: lusha
                    domain: www.lusha.com
                    alternativeDomains:
                      - lusha.com
                    description: >-
                      Lusha is the leader in Sales Streaming – a new sales
                      paradigm that streams top leads straight to salespeople
                      and handles all the outreach, so they can escape the lead
                      grind and just sell.
                    companyType: Private Company
                    yearFounded: 2016
                    employeeCount:
                      exact: 364
                      min: 201
                      max: 500
                    industry: Technology, Information & Media
                    subIndustry: Software Development
                    specialities:
                      - data accuracy
                      - data enrichment
                      - lead discovery
                      - lead generation
                      - prospecting
                      - sales enablement
                      - sales intelligence
                      - software development
                    sicCodes:
                      - code: 7371
                        description: Custom computer programming services
                    naicsCodes:
                      - code: 541511
                        description: Custom Computer Programming Services
                    location:
                      city: Boston
                      state: Massachusetts
                      country: United States
                      countryIso2: US
                      continent: North America
                      zipCode: '02199'
                    additionalLocations:
                      - city: New York City
                        state: New York
                        country: United States
                        countryIso2: US
                        continent: North America
                    socialLinks:
                      linkedin: https://www.linkedin.com/company/lushadata
                    linkedinFollowers: 64339
                    funding:
                      rounds:
                        - currency: USD
                          roundAmount: 205000000
                          roundType: Private Equity Round
                          roundDate: Nov 10, 2021
                        - currency: USD
                          roundAmount: 40000000
                          roundType: Private Equity Round
                          roundDate: Feb 10, 2021
                      totalRounds: 2
                      totalRoundsAmount: 245000000
                      currency: USD
                      isIpo: false
                      lastRoundType: Private Equity Round
                      lastRoundAmount: 205000000
                      lastRoundDate: Nov 10, 2021
                    technologies:
                      - amazon
                      - google analytics
                    popularityTier: 1
                    logoUrl: >-
                      https://logo.lusha.co/brightdata/year=2024/month=05/day=03/j_lvq47h0g13te1b3wpu.e7b0795e7affc9953dadd43e6fce99a2c5260043.file_lvq4cfwv17kcb9m4ej.logo_cached.jpg
                    employeesByDepartment:
                      - department: Business Development
                        count: 14
                      - department: Consulting
                        count: 10
                      - department: Customer Service
                        count: 28
                      - department: Engineering & Technical
                        count: 95
                      - department: Finance
                        count: 14
                      - department: General Management
                        count: 41
                      - department: Human Resources
                        count: 16
                      - department: Information Technology
                        count: 13
                      - department: Legal
                        count: 7
                      - department: Marketing
                        count: 31
                      - department: Operations
                        count: 22
                      - department: Other
                        count: 35
                      - department: Product
                        count: 38
                      - department: Research & Analytics
                        count: 42
                      - department: Sales
                        count: 72
                    employeesByLocation:
                      - country: Israel
                        state: null
                        count: 301
                      - country: United States
                        state: null
                        count: 45
                      - country: United States
                        state: Massachusetts
                        count: 30
                      - country: Brazil
                        state: null
                        count: 22
                      - country: France
                        state: null
                        count: 10
                    employeesBySeniority:
                      - seniority: C-Suite
                        count: 12
                      - seniority: Director
                        count: 35
                      - seniority: Founder
                        count: 33
                      - seniority: Intern
                        count: 1
                      - seniority: Manager
                        count: 141
                      - seniority: Non-Manager
                        count: 163
                      - seniority: Partner
                        count: 6
                      - seniority: Senior
                        count: 59
                      - seniority: Vice President
                        count: 9
                    competitors:
                      - id: '2497917'
                        name: Clearbit
                        domain: clearbit.com
                      - id: '9781263'
                        name: Hunter.io
                        domain: hunter.io
                      - id: '40857684'
                        name: MCJ Solutions Inc
                        domain: zoominfo.com
                      - id: '157961346'
                        name: PMc
                        domain: apollo.io
                    businessModel:
                      - B2B
                    emails:
                      - email: Support@Lusha.com
                    keywords:
                      - contact information
                      - data accuracy
                      - data enrichment
                      - lead discovery
                      - lead generation
                      - prospecting
                      - sales cadence
                      - sales enablement
                      - sales intelligence
                      - sales playlist
                      - sales streaming
                      - software development
                  - id: '12790225'
                    name: Salesforce
                    alternativeName: salesforce
                    domain: www.salesforce.com
                    alternativeDomains:
                      - salesforce.com
                    description: >-
                      We're the #1 AI CRM—where humans with agents drive
                      customer success together with AI, data, and Customer 360
                      apps on one platform.
                    companyType: Public Company
                    employeeCount:
                      exact: 88711
                      min: 100001
                      max: 10000000
                    industry: Technology, Information & Media
                    subIndustry: Software Development
                    sicCodes:
                      - code: 7371
                        description: Custom computer programming services
                    naicsCodes:
                      - code: 541511
                        description: Custom Computer Programming Services
                    location:
                      city: San Francisco
                      state: California
                      country: United States
                      countryIso2: US
                      continent: North America
                      zipCode: '94105'
                    additionalLocations:
                      - country: United States
                        countryIso2: US
                        continent: North America
                      - city: Chicago
                        state: Illinois
                        country: United States
                        countryIso2: US
                        continent: North America
                      - city: London
                        country: United Kingdom
                        countryIso2: GB
                        continent: Europe
                      - city: Tel Aviv
                        country: Israel
                        countryIso2: IL
                        continent: Asia
                    socialLinks:
                      linkedin: https://www.linkedin.com/company/salesforce
                    linkedinFollowers: 6417067
                    revenueRange:
                      min: 10000000000
                      max: 100000000000
                    intent:
                      detectedTopics:
                        - topicName: Cognism Limited
                          metadata:
                            topicScore: 85
                            topicTrend: '+24'
                      topicCount: 1
                    technologies:
                      - amazon
                      - paypal
                      - google analytics
                    popularityTier: 1
                    logoUrl: >-
                      https://logo.lusha.co/brightdata/year=2024/month=05/day=20/j_lwej8xik12ncr6ge4u.9e1ec373903019beff129694cb926761f065e9af.file_lwejc8mispkz3m1ng.logo_cached.jpg
                    employeesByDepartment:
                      - department: Business Development
                        count: 2820
                      - department: Consulting
                        count: 4963
                      - department: Engineering & Technical
                        count: 29167
                      - department: Finance
                        count: 2126
                      - department: Marketing
                        count: 4793
                      - department: Operations
                        count: 6117
                      - department: Sales
                        count: 22316
                    employeesByLocation:
                      - country: United States
                        state: null
                        count: 46090
                      - country: United States
                        state: California
                        count: 9928
                      - country: India
                        state: null
                        count: 18527
                      - country: United Kingdom
                        state: null
                        count: 3682
                      - country: Ireland
                        state: null
                        count: 3226
                    employeesBySeniority:
                      - seniority: C-Suite
                        count: 1039
                      - seniority: Director
                        count: 11538
                      - seniority: Manager
                        count: 18836
                      - seniority: Non-Manager
                        count: 49493
                      - seniority: Senior
                        count: 20509
                      - seniority: Vice President
                        count: 3104
                    competitors:
                      - id: '4269625'
                        name: iGroup Vietnam - Solutions for Enterprise
                        domain: monday.com
                      - id: '7237482'
                        name: Pipedrive
                        domain: pipedrive.com
                      - id: '9740086'
                        name: Microsoft
                        domain: microsoft.com
                      - id: '156097472'
                        name: Hub Spot
                        domain: hubspot.com
                    phones:
                      - number: +1 800-420-7332
                    emails:
                      - email: datasubjectrequest@salesforce.com
                billing:
                  creditsCharged: 10
                  resultsReturned: 2
        '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-and-enrich:
    post:
      tags:
        - Enrichment
      summary: Search and Enrich Companies
      operationId: searchAndEnrichCompanies
      description: >
        Find companies and reveal their full data in a single call. Combines
        Search and Enrich into one request.


        Provide company identifiers the same way you would for Search Companies.
        Up to 100 companies per request.


        > **Billing:** Same as Enrich Companies — charged per successful result
        via the `reveal_company` action.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3CompaniesSearchAndEnrichRequest'
            example:
              companies:
                - clientReferenceId: comp-ref-1
                  name: Lusha
                - clientReferenceId: comp-ref-2
                  domain: salesforce.com
              options:
                includePartialProfiles: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3CompaniesSearchAndEnrichResponse'
              example:
                requestId: 21fe0733-65d6-436a-8d0c-2c9ac6f263f8
                results:
                  - clientReferenceId: comp-ref-1
                    id: '16303253'
                    name: Lusha
                    alternativeName: lusha
                    domain: www.lusha.com
                    alternativeDomains:
                      - lusha.com
                    description: >-
                      Lusha is the leader in Sales Streaming – a new sales
                      paradigm that streams top leads straight to salespeople
                      and handles all the outreach, so they can escape the lead
                      grind and just sell.
                    companyType: Private Company
                    yearFounded: 2016
                    employeeCount:
                      exact: 364
                      min: 201
                      max: 500
                    industry: Technology, Information & Media
                    subIndustry: Software Development
                    specialities:
                      - data accuracy
                      - data enrichment
                      - lead discovery
                      - lead generation
                      - prospecting
                      - sales enablement
                      - sales intelligence
                      - software development
                    sicCodes:
                      - code: 7371
                        description: Custom computer programming services
                    naicsCodes:
                      - code: 541511
                        description: Custom Computer Programming Services
                    location:
                      city: Boston
                      state: Massachusetts
                      country: United States
                      countryIso2: US
                      continent: North America
                      zipCode: '02199'
                    additionalLocations:
                      - city: New York City
                        state: New York
                        country: United States
                        countryIso2: US
                        continent: North America
                    socialLinks:
                      linkedin: https://www.linkedin.com/company/lushadata
                    linkedinFollowers: 64339
                    funding:
                      rounds:
                        - currency: USD
                          roundAmount: 205000000
                          roundType: Private Equity Round
                          roundDate: Nov 10, 2021
                        - currency: USD
                          roundAmount: 40000000
                          roundType: Private Equity Round
                          roundDate: Feb 10, 2021
                      totalRounds: 2
                      totalRoundsAmount: 245000000
                      currency: USD
                      isIpo: false
                      lastRoundType: Private Equity Round
                      lastRoundAmount: 205000000
                      lastRoundDate: Nov 10, 2021
                    technologies:
                      - amazon
                      - google analytics
                    popularityTier: 1
                    logoUrl: >-
                      https://logo.lusha.co/brightdata/year=2024/month=05/day=03/j_lvq47h0g13te1b3wpu.e7b0795e7affc9953dadd43e6fce99a2c5260043.file_lvq4cfwv17kcb9m4ej.logo_cached.jpg
                    businessModel:
                      - B2B
                    emails:
                      - email: Support@Lusha.com
                    keywords:
                      - contact information
                      - data accuracy
                      - data enrichment
                      - lead discovery
                      - lead generation
                      - prospecting
                      - sales enablement
                      - sales intelligence
                      - software development
                  - clientReferenceId: comp-ref-2
                    id: '12790225'
                    name: Salesforce
                    alternativeName: salesforce
                    domain: www.salesforce.com
                    alternativeDomains:
                      - salesforce.com
                    description: >-
                      We're the #1 AI CRM—where humans with agents drive
                      customer success together with AI, data, and Customer 360
                      apps on one platform.
                    companyType: Public Company
                    employeeCount:
                      exact: 88711
                      min: 100001
                      max: 10000000
                    industry: Technology, Information & Media
                    subIndustry: Software Development
                    sicCodes:
                      - code: 7371
                        description: Custom computer programming services
                    naicsCodes:
                      - code: 541511
                        description: Custom Computer Programming Services
                    location:
                      city: San Francisco
                      state: California
                      country: United States
                      countryIso2: US
                      continent: North America
                      zipCode: '94105'
                    additionalLocations:
                      - country: United States
                        countryIso2: US
                        continent: North America
                      - city: Chicago
                        state: Illinois
                        country: United States
                        countryIso2: US
                        continent: North America
                      - city: London
                        country: United Kingdom
                        countryIso2: GB
                        continent: Europe
                      - city: Tel Aviv
                        country: Israel
                        countryIso2: IL
                        continent: Asia
                    socialLinks:
                      linkedin: https://www.linkedin.com/company/salesforce
                    linkedinFollowers: 6417067
                    revenueRange:
                      min: 10000000000
                      max: 100000000000
                    intent:
                      detectedTopics:
                        - topicName: Cognism Limited
                          metadata:
                            topicScore: 85
                            topicTrend: '+24'
                      topicCount: 1
                    technologies:
                      - amazon
                      - paypal
                      - google analytics
                    popularityTier: 1
                    logoUrl: >-
                      https://logo.lusha.co/brightdata/year=2024/month=05/day=20/j_lwej8xik12ncr6ge4u.9e1ec373903019beff129694cb926761f065e9af.file_lwejc8mispkz3m1ng.logo_cached.jpg
                    phones:
                      - number: +1 800-420-7332
                    emails:
                      - email: datasubjectrequest@salesforce.com
                billing:
                  creditsCharged: 3
                  resultsReturned: 2
        '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/contacts/prospecting:
    post:
      tags:
        - Prospecting
      summary: Prospecting Contacts
      operationId: prospectingContacts
      description: >
        Search for contacts that match your Ideal Customer Profile using rich
        filter criteria.


        **Filter by contact attributes:**

        - Job title, seniority, department

        - Location (city, state, country, continent)

        - Existing data points (e.g. only contacts with a known work email)

        - Signal activity (promotion, job change)


        **Filter by company attributes:**

        - Size, revenue, industry, technologies

        - Location, intent topics, funding


        Results are paginated up to 50,000 total (1,000 pages × 50 results). Use
        the returned contact `id` values with Enrich Contacts to reveal emails
        and phones.


        > **Billing:** Charged per result via `api_search`. If signals are
        requested, an additional charge applies per matched signal per result.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ProspectingContactsRequest'
            example:
              pagination:
                page: 0
                size: 50
              filters:
                contacts:
                  include:
                    departments:
                      - Sales
                    locations:
                      - country: United States
                    existingDataPoints:
                      - work_email
                companies:
                  include:
                    locations:
                      - country: United States
                  exclude:
                    domains:
                      - competitor.com
              options:
                maxContactsPerCompany: 25
                includePartialProfiles: true
                excludeDnc: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ProspectingContactsResponse'
              example:
                requestId: fa828378-7a8e-4e5d-9f72-0270e7f7ab51
                pagination:
                  page: 0
                  size: 50
                  total: 670550
                results:
                  - id: '670138733'
                    firstName: Ting
                    lastName: Tsou
                billing:
                  creditsCharged: 0
                  resultsReturned: 50
        '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/prospecting:
    post:
      tags:
        - Prospecting
      summary: Prospecting Companies
      operationId: prospectingCompanies
      description: >
        Search for companies that match your target market using rich filter
        criteria.


        **Filter by:**

        - Size, revenue range, industry, sub-industry

        - Technologies in use

        - Locations (HQ country, state, city)

        - SIC and NAICS codes

        - Buyer intent topics

        - Signal activity (headcount changes, hiring surges, news events)


        Results are paginated up to 50,000 total. Use the returned company `id`
        values with Enrich Companies to get full firmographic data.


        > **Billing:** Charged per result via `api_search`. If signals are
        requested, an additional charge applies per matched signal per result.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ProspectingCompaniesRequest'
            example:
              pagination:
                page: 0
                size: 25
              filters:
                companies:
                  include:
                    sizes:
                      - min: 100
                        max: 1000
                    revenues:
                      - min: 10000000
                    locations:
                      - country: United States
                    technologies:
                      - React
                      - Node.js
                    technologiesCondition: or
                    mainIndustriesIds:
                      - 1
                      - 5
                    intentTopics:
                      - Cloud Migration
                    signals:
                      types:
                        - headcountIncrease3m
                        - surgeInHiring
                      startDate: '2025-01-01'
                  exclude:
                    domains:
                      - competitor.com
              options:
                maxContactsPerCompany: 10
                includePartialProfiles: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ProspectingCompaniesResponse'
              example:
                requestId: f6a7b8c9-d0e1-2345-fabc-678901234567
                results:
                  - id: '16303253'
                    name: Lusha
                    domain: lusha.com
                pagination:
                  page: 0
                  size: 25
                  total: 87
                billing:
                  creditsCharged: 1
                  resultsReturned: 1
        '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/contacts/lookalike:
    post:
      tags:
        - Lookalikes
      summary: Contact Lookalikes
      operationId: getContactLookalikes
      description: >
        Find contacts similar to a set of seed contacts using AI-powered
        recommendations.


        Provide 5-100 seed contacts via LinkedIn URLs, emails, Lusha IDs, or
        name + company. The API returns contacts who share similar roles,
        seniority, and company profiles.


        **Pagination without duplicates:**

        On your first request, omit `dedupeSessionId` — the server generates one
        and returns it. Pass it on every subsequent request to get more results
        without repeating contacts already seen. Sessions are retained for 30
        days.


        Use the `exclude` field to always filter out specific contacts (e.g.
        existing customers).


        Results are lightweight previews. Use Enrich Contacts with the returned
        `id` to get emails and phones.


        > **Billing:** Charged per result via the `lookalikeContact` action.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactLookalikesRequest'
            examples:
              firstRequest:
                summary: First request (server generates dedupeSessionId)
                value:
                  seeds:
                    linkedinUrls:
                      - https://www.linkedin.com/in/orit-shilvock-6243bb5
                    emails:
                      - gal.ashkelon@lusha.com
                    ids:
                      - '1234'
                  exclude:
                    emails:
                      - existing@customer.com
                  limit: 25
              secondRequest:
                summary: Second request (get more using dedupeSessionId)
                value:
                  dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
                  seeds:
                    linkedinUrls:
                      - https://www.linkedin.com/in/shmulikwillinger
                  limit: 25
      responses:
        '200':
          description: Successfully retrieved contact lookalikes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactLookalikesResponse'
              example:
                dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
                results:
                  - id: '9659196'
                    firstName: Sarah
                    lastName: Johnson
                meta:
                  returned: 1
                  hasMore: true
                billing:
                  creditsCharged: 3
                  resultsReturned: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          description: Insufficient credits
        '403':
          $ref: '#/components/responses/Forbidden'
        '410':
          description: dedupeSessionId is invalid or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DedupeSessionInvalidError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v3/companies/lookalike:
    post:
      tags:
        - Lookalikes
      summary: Company Lookalikes
      operationId: getCompanyLookalikes
      description: >
        Find companies similar to a set of seed companies using AI-powered
        recommendations.


        Provide 5-100 seed companies via domains or LinkedIn URLs. The API
        returns companies with similar size, industry, and profile.


        **Pagination without duplicates:**

        On your first request, omit `dedupeSessionId` — the server generates one
        and returns it. Pass it on every subsequent request to get more results
        without repeating companies already seen. Sessions are retained for 30
        days.


        Use the `exclude` field to always filter out specific companies (e.g.
        existing customers or competitors).


        Results are lightweight previews. Use Enrich Companies with the returned
        `id` to get full firmographic data.


        > **Billing:** Charged per result via the `lookalikeCompany` action.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyLookalikesRequest'
            examples:
              firstRequest:
                summary: First request (server generates dedupeSessionId)
                value:
                  seeds:
                    domains:
                      - sap.com
                      - oracle.com
                    linkedinUrls:
                      - https://www.linkedin.com/company/google
                  exclude:
                    domains:
                      - existingcustomer.com
                  limit: 100
              secondRequest:
                summary: Second request (get more using dedupeSessionId)
                value:
                  dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
                  seeds:
                    domains:
                      - sap.com
                  limit: 100
      responses:
        '200':
          description: Successfully retrieved company lookalikes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyLookalikesResponse'
              example:
                dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
                results:
                  - id: '12345'
                    name: Marriott International
                    domain: marriott.com
                meta:
                  returned: 1
                  hasMore: true
                billing:
                  creditsCharged: 3
                  resultsReturned: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          description: Insufficient credits
        '403':
          $ref: '#/components/responses/Forbidden'
        '410':
          description: dedupeSessionId is invalid or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v3/contacts/signals:
    post:
      tags:
        - Signals
      summary: Contact Signals
      operationId: getContactSignals
      description: >
        Retrieve signal events for a list of contacts — job changes and
        promotions.


        Pass up to 100 contact `ids`. Use `signalTypes` to specify which events
        to return (`promotion`, `companyChange`, or `allSignals`). Optionally
        set a `startDate` to limit results to recent activity.


        > **Billing:** Charged per matched signal per result via the
        `showSignalsContact` action.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ContactSignalsRequest'
            example:
              ids:
                - '4389064624'
                - '4389064654'
              signalTypes:
                - allSignals
              startDate: '2025-01-01'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ContactSignalsResponse'
              example:
                results:
                  - id: '115889'
                    companyChange:
                      - id: '115889'
                        signalDate: '2025-02-01'
                        previousCompany: ZoomInfo
                        newCompany: Lusha
                    promotion: []
                startDate: '2025-01-01'
                endDate: '2025-03-01'
                billing:
                  creditsCharged: 1
                  resultsReturned: 1
        '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/signals:
    post:
      tags:
        - Signals
      summary: Company Signals
      operationId: getCompanySignals
      description: >
        Retrieve signal events for a list of companies — hiring activity,
        headcount changes, web traffic, IT spend, and news.


        Pass up to 100 company `ids`. Use `signalTypes` to specify which signals
        to return (or use `allSignals`). Optionally set a `startDate` to limit
        results to recent activity.


        > **Billing:** Charged per matched signal per result via the
        `showSignalsCompany` action.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3CompanySignalsRequest'
            example:
              ids:
                - '16303253'
              signalTypes:
                - allSignals
              startDate: '2025-01-01'
              maxResultsPerSignal: 10
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3CompanySignalsResponse'
        '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/contacts/signals/types:
    get:
      tags:
        - Signals
      summary: Get Contact Signal Types
      operationId: getContactSignalTypes
      description: |
        Returns the full list of supported signal types for contacts.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactSignalTypesResponse'
              example:
                signalTypes:
                  - allSignals
                  - promotion
                  - companyChange
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/companies/signals/types:
    get:
      tags:
        - Signals
      summary: Get Company Signal Types
      operationId: getCompanySignalTypes
      description: |
        Returns the full list of supported signal types for companies.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanySignalTypesResponse'
              example:
                signalTypes:
                  - allSignals
                  - websiteTrafficDecrease
                  - websiteTrafficIncrease
                  - itSpendIncrease
                  - itSpendDecrease
                  - surgeInHiring
                  - headcountIncrease1m
                  - headcountIncrease3m
                  - headcountIncrease6m
                  - headcountIncrease12m
                  - headcountDecrease1m
                  - headcountDecrease3m
                  - headcountDecrease6m
                  - headcountDecrease12m
                  - surgeInHiringByDepartment
                  - surgeInHiringByLocation
                  - riskNews
                  - commercialActivityNews
                  - corporateStrategyNews
                  - financialEventsNews
                  - peopleNews
                  - marketIntelligenceNews
                  - productActivityNews
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/companies/signals/filters:
    get:
      tags:
        - Signals
      summary: Get Company Signal Filters (Discovery)
      operationId: getCompanySignalFilters
      description: >
        Returns all available filter types for company signals and whether each
        requires a search query.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterTypesDiscoveryResponse'
              example:
                availableFilters:
                  - filterType: newsEventTypes
                    requiresQuery: false
                  - filterType: hiringByDepartments
                    requiresQuery: false
                  - filterType: hiringByLocations
                    requiresQuery: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/companies/signals/filters/{filterType}:
    get:
      tags:
        - Signals
      summary: Get Company Signal Filter Values
      operationId: getCompanySignalFilterValues
      description: |
        Returns valid values for a single company signal filter type.

        | Filter type | Query required? |
        |---|---|
        | `newsEventTypes` | No |
        | `hiringByDepartments` | No |
        | `hiringByLocations` | Yes (2-256 chars) |
      parameters:
        - name: filterType
          in: path
          required: true
          schema:
            type: string
            enum:
              - newsEventTypes
              - hiringByDepartments
              - hiringByLocations
        - name: query
          in: query
          required: false
          schema:
            type: string
            minLength: 2
            maxLength: 256
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterValuesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/contacts/prospecting/filters:
    get:
      tags:
        - Filters
      summary: Get Contact Filter Types (Discovery)
      operationId: getContactFilterTypes
      description: >
        Returns all available filter types for contact prospecting and whether
        each requires a search query.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterTypesDiscoveryResponse'
              example:
                availableFilters:
                  - filterType: locations
                    requiresQuery: true
                  - filterType: departments
                    requiresQuery: false
                  - filterType: seniority
                    requiresQuery: false
                  - filterType: countries
                    requiresQuery: false
                  - filterType: existingDataPoints
                    requiresQuery: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/contacts/prospecting/filters/{filterType}:
    get:
      tags:
        - Filters
      summary: Get Contact Filter Values
      operationId: getContactFilterValues
      description: |
        Returns valid values for a single contact filter type.

        | Filter type | Query required? |
        |---|---|
        | `departments` | No |
        | `seniority` | No |
        | `existingDataPoints` | No |
        | `countries` | No |
        | `locations` | Yes (2-256 chars) |
      parameters:
        - name: filterType
          in: path
          required: true
          schema:
            type: string
            enum:
              - departments
              - seniority
              - existingDataPoints
              - countries
              - locations
        - name: query
          in: query
          required: false
          schema:
            type: string
            minLength: 2
            maxLength: 256
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterValuesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v3/companies/prospecting/filters:
    get:
      tags:
        - Filters
      summary: Get Company Filter Types (Discovery)
      operationId: getCompanyFilterTypes
      description: >
        Returns all available filter types for company prospecting and whether
        each requires a search query.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterTypesDiscoveryResponse'
              example:
                availableFilters:
                  - filterType: names
                    requiresQuery: true
                  - filterType: technologies
                    requiresQuery: true
                  - filterType: industriesLabels
                    requiresQuery: false
                  - filterType: sizes
                    requiresQuery: false
                  - filterType: revenues
                    requiresQuery: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/companies/prospecting/filters/{filterType}:
    get:
      tags:
        - Filters
      summary: Get Company Filter Values
      operationId: getCompanyFilterValues
      description: |
        Returns valid values for a single company filter type.

        | Filter type | Query required? |
        |---|---|
        | `sizes` | No |
        | `revenues` | No |
        | `sics` | No |
        | `naics` | No |
        | `intentTopics` | No |
        | `industriesLabels` | No |
        | `names` | Yes (2-256 chars) |
        | `technologies` | Yes (2-256 chars) |
        | `locations` | Yes (2-256 chars) |
      parameters:
        - name: filterType
          in: path
          required: true
          schema:
            type: string
            enum:
              - names
              - sizes
              - revenues
              - locations
              - sics
              - naics
              - industriesLabels
              - intentTopics
              - technologies
        - name: query
          in: query
          required: false
          schema:
            type: string
            minLength: 2
            maxLength: 256
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterValuesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/subscriptions:
    post:
      tags:
        - Webhooks
      summary: Create Subscription
      description: >
        Creates one or more webhook subscriptions for real-time signal
        notifications.


        **Delivery & Reliability:**

        - Webhooks are delivered with automatic retry on failures

        - Maximum 3 retry attempts with exponential backoff

        - Subscriptions auto-disable after max retries exceeded

        - All deliveries are logged in audit logs


        > **Note:** Your webhook endpoint must respond with a proper
        acknowledgment. 
         See Client Response Format below for details.

        > **Limit:** Maximum 25 subscriptions per request


        *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions**


        ---


        ### Webhook Payload You'll Receive
         When a signal is triggered, this payload is sent to your webhook URL:
        ```json
            {
              "id": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c",
              "type": "promotion",
              "entityType": "contact",
              "entityId": "4158887495",
              "subscriptionId": "507f1f77bcf86cd799439011",
              "data": {
                "personId": 4158887495,
                "currentCompanyId": 40823133,
                "currentCompanyName": "OMG Hospitality Group LLC",
                "currentDomain": "omghospitalitygroup.com",
                "currentTitle": "Bartender",
                "currentDepartments": [
                  { "id": 7, "value": "Other" }
                ],
                "previousCompanyName": "First Watch Restaurants",
                "previousDomain": "firstwatch.com",
                "signalDate": "2025-07-01"
              },
              "timestamp": "2026-01-14T16:16:35.841Z",
              "billing": {
                "creditsCharged": 1
              }
            }
            ```
                    **Example — Company News Signal:**
            ```json
                    {
                      "id": "a7c92f14-1234-4b3e-9d22-8b4fe1d0bc45",
                      "type": "commercialActivityNews",
                      "entityType": "company",
                      "entityId": "33222678",
                      "subscriptionId": "507f1f77bcf86cd799439011",
                      "data": {
                        "companyId": "33222678",
                        "companyName": "Lusha",
                        "domain": "lusha.com",
                        "signalId": "1503910",
                        "eventType": "partnership",
                        "eventSummary": "Lusha announced a strategic partnership with Salesforce.",
                        "articlePublishedDate": "2025-06-15",
                        "articleTitle": "Lusha Partners with Salesforce",
                        "articleHighlight": "The partnership enables Salesforce users to access Lusha data directly within their CRM.",
                        "eventEffectiveDate": "2025-06-10",
                        "articleUrl": "https://example.com/lusha-salesforce-partnership"
                      },
                      "timestamp": "2026-01-14T16:16:35.841Z",
                      "billing": {
                        "creditsCharged": 1
                      }
                    }
                  ```

              **Headers Included:**

              | Header | Description |
              |--------|-------------|
              | `X-Lusha-Signature` | HMAC-SHA256 signature for verification |
              | `X-Lusha-Timestamp` | Unix timestamp of the request |
              | `Content-Type` | application/json |
              | `User-Agent` | Lusha-Webhooks/1.0 |


        ---

        ⚠️ **Important:** Ensure your account has a webhook secret before
        creating subscriptions.

        Create one via the [Regenerate Account
        Secret](#operation/regenerateAccountSecret) endpoint.


        ---


        ### Client Response Format (Required)


        When your webhook endpoint receives a delivery, it **must** acknowledge
        receipt with this response:

          **Required Response:**
          ````json
          {
            "received": true,
            "timestamp": "2026-02-05T10:30:45.123Z",
            "webhookId": "f3b87e05-0402-4f3e-8e26-6a38fd0ad62c"
          }
          ````

        <details>

        <summary><strong>Response Requirements</strong></summary>

          | Requirement | Value |
          |-------------|-------|
          | **HTTP Status** | `201 Created` (recommended) or any `2xx` status |
          | **Content-Type** | `application/json` |
          | **Response Time** | Within 10 seconds |
        </details>



        <details>

        <summary><strong>Field Descriptions & Implementation
        Guide</strong></summary>

          **Field Descriptions:**
          * `received` (boolean, required): Confirmation flag - must be `true`
          * `timestamp` (string, required): ISO 8601 timestamp of receipt
          * `webhookId` (string, required): Echo the `id` from webhook payload

          **Implementation Example:**
          ```javascript
          app.post('/webhook', async (req, res) => {
            // 1. Verify signature
            if (!verifyWebhookSignature(req)) {
              return res.status(401).json({ error: 'Invalid signature' });
            }
            
            // 2. Queue for async processing
            await queueWebhook(req.body);
            
            // 3. Acknowledge immediately
            res.status(201).json({
              received: true,
              timestamp: new Date().toISOString(),
              webhookId: req.body.id
            });
            ```

          **Important Notes:**
          * Return acknowledgment **before** heavy processing
          * Non-2xx responses trigger retry mechanism
          * After 3 failed retries, subscription is disabled

          </details>

        ----
      operationId: createSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
            examples:
              singleSubscription:
                summary: Create a single subscription
                value:
                  defaults:
                    entityType: contact
                    signalTypes:
                      - promotion
                      - companyChange
                    url: https://example.com/webhooks/lusha
                  subscriptions:
                    - entityId: '123456'
                      name: My Test Webhook
              multipleSubscriptions:
                summary: Create multiple subscriptions with shared URL
                value:
                  defaults:
                    entityType: contact
                    signalTypes:
                      - promotion
                      - companyChange
                    url: https://example.com/webhooks/lusha
                  subscriptions:
                    - entityId: '123'
                      name: Contact 123
                    - entityId: '456'
                      name: Contact 456
                    - entityId: '789'
                      name: Contact 789
              mixedEntityTypes:
                summary: Mixed entity types with shared URL
                value:
                  defaults:
                    signalTypes:
                      - promotion
                      - itSpendIncrease
                    url: https://example.com/webhooks/lusha
                  subscriptions:
                    - entityType: contact
                      entityId: '123'
                    - entityType: company
                      entityId: '456'
      responses:
        '201':
          description: Subscriptions created (full or partial success)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSubscriptionResponse'
              examples:
                allSuccessful:
                  summary: All subscriptions created successfully
                  value:
                    total: 3
                    successful: 3
                    failed: 0
                    results:
                      - index: 0
                        success: true
                        subscription:
                          id: 507f1f77bcf86cd799439011
                          entityType: contact
                          entityId: '123'
                          signalTypes:
                            - promotion
                            - companyChange
                          url: https://example.com/webhooks/lusha
                          name: Contact 123
                          isActive: true
                          createdAt: '2026-02-02T10:00:00.000Z'
                          updatedAt: '2026-02-02T10:00:00.000Z'
                partialSuccess:
                  summary: Some subscriptions failed (partial success)
                  value:
                    total: 3
                    successful: 2
                    failed: 1
                    results:
                      - index: 0
                        success: true
                        subscription:
                          id: 507f1f77bcf86cd799439011
                          entityType: contact
                          entityId: '123'
                          signalTypes:
                            - promotion
                            - companyChange
                          url: https://example.com/webhooks/lusha
                          name: Contact 123
                          isActive: true
                          createdAt: '2026-02-02T10:00:00.000Z'
                          updatedAt: '2026-02-02T10:00:00.000Z'
                      - index: 1
                        success: false
                        error:
                          code: DUPLICATE_SUBSCRIPTION
                          message: >-
                            Subscription already exists for entity type
                            'contact' with entity ID '456'
        '400':
          description: Bad request - URL validation failed or invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 400
                message: Validation failed
                errors:
                  - 'entityType must be one of: contact, company'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden - feature not available or limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 403
                message: Maximum subscriptions limit reached for your account
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
        - Webhooks
      summary: List Subscriptions
      description: >
        Returns all webhook subscriptions for your account with pagination
        support.


        *Endpoint*: **(GET) https://api.lusha.com/api/subscriptions**


        **Pagination:**

        - Results are sorted by `createdAt` in descending order (newest first)

        - Default limit: 10, max limit: 100

        - Use `offset` for pagination through large result sets


        > **Note:** The webhook `secret` is never returned in list responses for
        security.
      operationId: listSubscriptions
      parameters:
        - name: limit
          in: query
          required: false
          description: Maximum number of results (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          example: 10
        - name: offset
          in: query
          required: false
          description: Number of results to skip
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
      responses:
        '200':
          description: List of subscriptions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListResponse'
              example:
                data:
                  - id: 507f1f77bcf86cd799439011
                    entityType: contact
                    entityId: '123456'
                    signalTypes:
                      - promotion
                      - companyChange
                    url: https://example.com/webhook
                    name: My Contact Webhook
                    isActive: true
                    createdAt: '2024-01-01T00:00:00.000Z'
                    updatedAt: '2024-01-01T00:00:00.000Z'
                pagination:
                  total: 25
                  limit: 10
                  offset: 0
                  hasMore: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/subscriptions/{id}:
    get:
      tags:
        - Webhooks
      summary: Get Subscription by ID
      description: |
        Returns a single webhook subscription by ID.

        *Endpoint*: **(GET) https://api.lusha.com/api/subscriptions/{id}**
      operationId: getSubscriptionById
      parameters:
        - name: id
          in: path
          required: true
          description: Subscription ID
          schema:
            type: string
          example: 507f1f77bcf86cd799439011
      responses:
        '200':
          description: Subscription retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionWithoutSecret'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Webhooks
      summary: Update Subscription
      description: >
        Updates an existing webhook subscription. All fields are optional.


        *Endpoint*: **(PATCH) https://api.lusha.com/api/subscriptions/{id}**


        ---

        **Reactivating Disabled Subscriptions:**


        When setting `isActive: true` on a previously disabled subscription, the
        system automatically:

        - Clears the `blockReason` field

        - Clears the `blockedAt` timestamp

        - Resets the retry counter


        **Regenerating Secrets:**


        Set `regenerateSecret: true` to generate a new webhook secret. The new
        secret:

        - Affects **all subscriptions** for your account

        - Is only shown once in the response

        - Immediately invalidates the old secret

        ---
      operationId: updateSubscription
      parameters:
        - name: id
          in: path
          required: true
          description: Subscription ID
          schema:
            type: string
          example: 507f1f77bcf86cd799439011
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionRequest'
            examples:
              disableSubscription:
                summary: Disable a subscription
                value:
                  isActive: false
              updateSignals:
                summary: Change subscribed signals
                value:
                  signalTypes:
                    - promotion
                    - companyChange
              regenerateSecret:
                summary: Regenerate webhook secret
                value:
                  regenerateSecret: true
              updateUrl:
                summary: Update webhook URL
                value:
                  url: https://new-domain.com/webhooks/lusha
      responses:
        '200':
          description: Subscription updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/subscriptions/{id}/test:
    post:
      tags:
        - Webhooks
      summary: Test Subscription
      description: >
        Test a webhook subscription by sending a test signal. Supports three
        test modes.


        *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/{id}/test**

        ---

        **Test Modes:**

        - `direct` - Quick HTTP check only (validates URL responds correctly)

        - `kafka` - Fanout handler only (tests Kafka message processing)

        - `full` - Complete Kafka flow (default - end-to-end test)


        **Important Notes:**

        - Test deliveries do NOT consume credits

        - Test payloads use mock data

        - Useful for verifying webhook configuration before going live
      operationId: testSubscription
      parameters:
        - name: id
          in: path
          required: true
          description: Subscription ID
          schema:
            type: string
          example: 507f1f77bcf86cd799439011
        - name: mode
          in: query
          required: false
          description: Test mode
          schema:
            type: string
            enum:
              - direct
              - kafka
              - full
            default: full
          example: full
      responses:
        '200':
          description: Test executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSubscriptionResponse'
              example:
                subscriptionId: 507f1f77bcf86cd799439011
                subscriptionName: My Test Webhook
                url: https://example.com/webhook
                mode: full
                flowCheck:
                  success: true
                  statusCode: 200
                  durationMs: 150
                testPayload:
                  entityType: contact
                  signalType: promotion
                  data: {}
                isSuccess: true
                timestamp: '2024-01-01T00:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Subscription does not belong to your account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 403
                message: Subscription does not belong to your account
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/subscriptions/delete:
    post:
      tags:
        - Webhooks
      summary: Delete Subscriptions
      description: >
        Delete one or more webhook subscriptions. Returns detailed results for
        each deletion with partial success support.


        *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/delete**


        ---


        **Behavior:**

        - Each subscription is processed independently

        - Returns detailed results for each item including deleted subscription
        info

        - Invalid ID formats are gracefully handled and reported as NOT_FOUND

        - Duplicate IDs are automatically deduplicated

        - Deletion is permanent and cannot be undone
      operationId: deleteSubscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ids
              properties:
                ids:
                  type: array
                  minItems: 1
                  maxItems: 25
                  items:
                    type: string
                  description: Array of subscription IDs to delete
                  example:
                    - 507f1f77bcf86cd799439011
                    - 507f1f77bcf86cd799439012
            examples:
              singleDelete:
                summary: Delete a single subscription
                value:
                  ids:
                    - sub-123
              multipleDelete:
                summary: Delete multiple subscriptions
                value:
                  ids:
                    - sub-123
                    - sub-456
                    - sub-789
      responses:
        '200':
          description: Delete operation completed (full or partial success)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSubscriptionResponse'
              examples:
                allSuccessful:
                  summary: All subscriptions deleted successfully
                  value:
                    total: 3
                    successful: 3
                    failed: 0
                    results:
                      - index: 0
                        success: true
                        subscription:
                          id: sub-123
                          entityType: contact
                          entityId: '123'
                          name: Contact Webhook
                partialSuccess:
                  summary: Some deletions failed
                  value:
                    total: 3
                    successful: 2
                    failed: 1
                    results:
                      - index: 0
                        success: true
                        subscription:
                          id: sub-123
                          entityType: contact
                          entityId: '123'
                          name: Contact Webhook
                      - index: 1
                        success: false
                        error:
                          code: NOT_FOUND
                          message: Subscription with id 'sub-456' not found
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/audit-logs:
    get:
      tags:
        - Webhooks
      summary: Get Audit Logs
      description: >
        Retrieve webhook delivery logs for your account.


        *Endpoint*: **(GET) https://api.lusha.com/api/audit-logs**


        **What's Logged:**

        - All webhook delivery attempts (success and failures)

        - HTTP status codes and response times

        - Error messages for failed deliveries

        - Delivery timestamps and duration metrics


        **Filtering:**

        - Filter by subscription ID to see logs for specific subscriptions

        - Filter by status to see only successes, failures, or permanent
        failures


        **Rate Limit:** 100 requests/minute per account


        > **Note:** Logs are retained for 90 days (successful) and 180 days
        (failed/DLQ)
      operationId: getAuditLogs
      parameters:
        - name: subscriptionId
          in: query
          required: false
          description: Filter by subscription ID
          schema:
            type: string
          example: 507f1f77bcf86cd799439011
        - name: status
          in: query
          required: false
          description: Filter by delivery status
          schema:
            type: string
            enum:
              - success
              - failed
              - permanent_failure
          example: success
        - name: limit
          in: query
          required: false
          description: Maximum number of results (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          example: 50
        - name: offset
          in: query
          required: false
          description: Number of results to skip
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
      responses:
        '200':
          description: Audit logs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogsResponse'
              example:
                data:
                  - id: log-123
                    subscriptionId: sub-123
                    payloadId: payload-456
                    status: success
                    statusCode: 200
                    url: https://example.com/webhook
                    deliveredAt: '2024-01-01T00:00:00.000Z'
                    durationMs: 150
                    error: null
                pagination:
                  total: 100
                  limit: 50
                  offset: 0
                  hasMore: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/audit-logs/stats:
    get:
      tags:
        - Webhooks
      summary: Get Audit Log Statistics
      description: |
        Get delivery statistics for your account.

        *Endpoint*: **(GET) https://api.lusha.com/api/audit-logs/stats**
      operationId: getAuditLogStats
      parameters:
        - name: subscriptionId
          in: query
          required: false
          description: Filter statistics by subscription ID
          schema:
            type: string
          example: sub-123
      responses:
        '200':
          description: Statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogStatsResponse'
              example:
                total: 1000
                success: 950
                failed: 50
                successRate: 95.00%
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/account/secret:
    get:
      tags:
        - Webhooks
      summary: Get Account Secret
      description: |
        Retrieve the current account webhook secret.

        *Endpoint*: **(GET) https://api.lusha.com/api/account/secret**
      operationId: getAccountSecret
      responses:
        '200':
          description: Account secret retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - secret
                properties:
                  secret:
                    type: string
                    description: Current account webhook secret
                    example: whsec_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Account secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 404
                message: Account secret not found. Please generate one first.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/account/secret/regenerate:
    post:
      tags:
        - Webhooks
      summary: Regenerate Account Secret
      description: >
        Regenerate the account webhook secret. Affects **all subscriptions** for
        the account.


        *Endpoint*: **(POST)
        https://api.lusha.com/api/account/secret/regenerate**


        **Behavior:**

        - If a secret already exists: Replaces with new secret (old secret is
        invalidated)

        - If no secret exists: Creates new secret automatically


        **Important Notes:**

        - The secret is only shown once in the response. Store it securely.

        - This endpoint always succeeds (upsert operation)

        - Regenerating invalidates the old secret for **all subscriptions** (if
        one existed)

        - An account secret must exist before webhooks can be delivered
      operationId: regenerateAccountSecret
      responses:
        '200':
          description: Account secret regenerated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - secret
                properties:
                  secret:
                    type: string
                    description: >-
                      Newly generated account webhook secret (store securely -
                      only shown once)
                    example: whsec_new_secret_here_abc123def456ghi789jkl012mno345
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/subscriptions/opt-out:
    post:
      tags:
        - Webhooks
      summary: Create Opt-Out Subscription
      description: >
        Subscribe to real-time notifications when a contact opts out of data
        processing. When a contact requests removal, Lusha sends an
        `OptOutWebhookPayload` to your endpoint so you can action the removal in
        your own systems (CRM, outreach tools, etc.).


        *Endpoint*: **(POST) https://api.lusha.com/api/subscriptions/opt-out**


        ---


        **How it works:**

        - Create one opt-out subscription per account (scoped to `contact`
        entity type)

        - Lusha delivers a POST request to your URL whenever a contact opts out

        - The payload includes the contact identity, opt-out date, and the
        specific data points (emails and/or phones) that must be removed


        **Payload you'll receive:**

        ```json

        {
          "contactId": "987654321",
          "fullName": "Jane Doe",
          "companyName": "Acme Corp",
          "jobTitle": "Director of Product",
          "linkedinUrl": "https://www.linkedin.com/in/jane-doe",
          "contactOptOutDate": "2026-04-22 14:32:11.412",
          "contactExposureDate": "2025-08-03 09:15:47",
          "datapoints": [
            { "datapointId": "+14155550199", "datapointType": "phone" },
            { "datapointId": "jane.doe@acme.com", "datapointType": "email" }
          ],
          "partnerClientId": "acme-crm-tenant-42"
        }

        ```


        > **Important:** Signature verification applies the same way as standard
        webhook deliveries. See [Security & Verification](#tag/Webhooks) for
        details.


        > **Note:** Ensure your account has a webhook secret before creating
        this subscription. See [Regenerate Account
        Secret](#operation/regenerateAccountSecret).
      operationId: createOptOutSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOptOutSubscriptionRequest'
            example:
              entityType: contact
              url: https://example.com/webhook
              name: Account opt-out webhook
      responses:
        '201':
          description: Opt-out subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutSubscriptionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Forbidden - feature not available or opt-out subscription already
            exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 403
                message: An opt-out subscription already exists for this account
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v3/account/usage:
    get:
      tags:
        - Account
      summary: Get Account Usage
      operationId: getAccountUsage
      description: >
        Returns a full snapshot of your account status:

        - **Credits** — total, used, and remaining for the current billing cycle

        - **Rate limits** — current usage and reset times for daily, hourly, and
        per-minute windows

        - **Plan** — your current plan category and renewal dates

        - **Pricing** — credit cost per action type across all public API
        endpoints


        > **Rate limit:** This endpoint is limited to 5 requests per minute.
      responses:
        '200':
          description: Successfully retrieved account usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUsageResponse'
              example:
                credits:
                  total: 10000
                  used: 1500
                  remaining: 8500
                rateLimits:
                  daily:
                    limit: 5000
                    used: 120
                    remaining: 4880
                    resetsAt: '2026-03-31T00:00:00.000Z'
                plan:
                  category: professional
                  renewalType: annual
                  startDate: '2026-01-01T00:00:00.000Z'
                  endDate: '2027-01-01T00:00:00.000Z'
                pricing:
                  revealEmail:
                    credits: 1
                    perQuantity: 1
                  revealPhone:
                    credits: 5
                    perQuantity: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  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.
  responses:
    BadRequest:
      description: Bad request - invalid input data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 400
            message: Invalid request parameters
    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
    Forbidden:
      description: Forbidden - account inactive or V3 access not enabled
      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
    NotFound:
      description: Not found - resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 404
            message: Resource not found
    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
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 500
            message: Internal server error. Please try again later.
  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'
    DedupeSessionInvalidError:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: DEDUPE_SESSION_INVALID
        message:
          type: string
          example: >-
            The provided dedupeSessionId is invalid or expired. Generate a new
            request without dedupeSessionId to start a fresh run.
    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
    V3SearchOptions:
      type: object
      description: Additional options for search requests
      properties:
        includePartialProfiles:
          type: boolean
          description: Include partial profiles in results
          example: true
    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
    V3ItemError:
      type: object
      description: Per-item error in a batch response
      properties:
        code:
          type: string
          enum:
            - NOT_FOUND
            - COMPLIANCE_RESTRICTED
            - ENRICH_FAILED
          example: NOT_FOUND
        message:
          type: string
          example: Contact not found
    V3Location:
      type: object
      description: Location filter object used in prospecting requests
      properties:
        city:
          type: string
          example: San Francisco
        state:
          type: string
          example: California
        country:
          type: string
          example: United States
        continent:
          type: string
          example: North America
        countryGrouping:
          type: string
          example: EMEA
    V3Range:
      type: object
      description: Numeric range filter
      properties:
        min:
          type: integer
          minimum: 0
          example: 100
        max:
          type: integer
          example: 1000
    V3PaginationRequest:
      type: object
      required:
        - page
        - size
      properties:
        page:
          type: integer
          minimum: 0
          maximum: 1000
          default: 0
          example: 0
        size:
          type: integer
          minimum: 10
          maximum: 100
          default: 25
          example: 25
    V3PaginationResponse:
      type: object
      properties:
        page:
          type: integer
          example: 0
        size:
          type: integer
          example: 25
        total:
          type: integer
          example: 150
    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
    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
    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'
    V3EmailAddress:
      type: object
      properties:
        email:
          type: string
          format: email
          example: orit.shilvock@lusha.com
        type:
          type: string
          enum:
            - work
            - private
            - unknown
          example: work
        confidence:
          type: string
          nullable: true
          example: A+
        updateDate:
          type: string
          format: date
          example: '2026-04-23'
    V3PhoneNumber:
      type: object
      properties:
        number:
          type: string
          example: '+14155551234'
        type:
          type: string
          enum:
            - mobile
            - direct
            - work
            - unknown
          example: mobile
        doNotCall:
          type: boolean
          example: false
        updateDate:
          type: string
          format: date
          example: '2026-04-23'
    V3ContactTag:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        color:
          type: string
          example: '#FF5733'
    V3EnrichedContactCompanyRef:
      type: object
      properties:
        id:
          type: string
          example: '16303253'
        name:
          type: string
          example: Lusha
        domain:
          type: string
          example: www.lusha.com
        industry:
          type: string
          example: Technology, Information & Media
    V3EnrichedContact:
      type: object
      properties:
        id:
          type: string
          example: '4389064704'
        firstName:
          type: string
          example: Orit
        lastName:
          type: string
          example: Shilvock
        fullName:
          type: string
          example: Orit 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
        location:
          type: object
          properties:
            country:
              type: string
              example: Israel
            countryIso2:
              type: string
              example: IL
            state:
              type: string
              example: Tel Aviv District
            city:
              type: string
              example: Tel Aviv
            continent:
              type: string
              example: Asia
            coordinates:
              type: array
              items:
                type: number
              example:
                - 34.78057098388672
                - 32.08087921142578
            isEuContact:
              type: boolean
              example: false
        tags:
          type: array
          items:
            $ref: '#/components/schemas/V3ContactTag'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/V3EmailAddress'
        phones:
          type: array
          items:
            $ref: '#/components/schemas/V3PhoneNumber'
        company:
          $ref: '#/components/schemas/V3EnrichedContactCompanyRef'
        socialLinks:
          type: object
          properties:
            linkedin:
              type: string
              example: https://www.linkedin.com/in/orit-shilvock-6243bb5
            xUrl:
              type: string
              example: https://twitter.com/lushaofficial
        previousEmployment:
          type: array
          items:
            type: object
            properties:
              company:
                type: object
                properties:
                  name:
                    type: string
                  domain:
                    type: string
              jobTitle:
                type: object
                properties:
                  title:
                    type: string
                  departments:
                    type: array
                    items:
                      type: string
                  seniority:
                    type: string
        updateDate:
          type: string
          format: date
          example: '2026-04-23'
        error:
          $ref: '#/components/schemas/V3ItemError'
    V3SearchAndEnrichContactResult:
      allOf:
        - $ref: '#/components/schemas/V3EnrichedContact'
        - type: object
          properties:
            clientReferenceId:
              type: string
              example: my-ref-1
    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
    V3CompanySignalsDto:
      type: object
      required:
        - types
      properties:
        types:
          type: array
          items:
            type: string
            enum:
              - allSignals
              - 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
    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
            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.
          example:
            - alternativeName
            - alternativeDomains
            - description
            - companyType
            - yearFounded
            - subIndustry
            - specialities
            - sicCodes
            - naicsCodes
            - additionalLocations
            - linkedinFollowers
            - popularityTier
            - logoUrl
            - employeesByDepartment
            - employeesByLocation
            - employeesBySeniority
            - competitors
            - businessModel
            - phones
            - emails
            - keywords
            - socialLinks
        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
        signalTypes:
          type: array
          items:
            type: string
          example:
            - headcountIncrease3m
        error:
          $ref: '#/components/schemas/V3ItemError'
    V3CompanyLocation:
      type: object
      properties:
        city:
          type: string
          example: London
        state:
          type: string
          example: England
        country:
          type: string
          example: United Kingdom
        countryIso2:
          type: string
          example: GB
        continent:
          type: string
          example: Europe
        zipCode:
          type: string
          description: Postal/ZIP code (present on HQ location when available)
          example: '80904'
    V3SicCode:
      type: object
      properties:
        code:
          type: integer
          example: 7371
        description:
          type: string
          example: Custom computer programming services
    V3NaicsCode:
      type: object
      properties:
        code:
          type: integer
          example: 541511
        description:
          type: string
          example: Custom Computer Programming Services
    V3EnrichedCompany:
      type: object
      properties:
        id:
          type: string
          example: '16303253'
        name:
          type: string
          example: Lusha
        alternativeName:
          type: string
          example: lusha
        domain:
          type: string
          example: www.lusha.com
        alternativeDomains:
          type: array
          items:
            type: string
          example:
            - lusha.com
        description:
          type: string
          example: Lusha is the leader in Sales Streaming.
        companyType:
          type: string
          example: Private Company
        yearFounded:
          type: number
          example: 2016
        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
        subIndustry:
          type: string
          example: Software Development
        specialities:
          type: array
          items:
            type: string
          example:
            - data enrichment
            - sales intelligence
        industryTags:
          type: array
          items:
            type: string
          example:
            - saas
            - b2b
        sicCodes:
          type: array
          items:
            $ref: '#/components/schemas/V3SicCode'
        naicsCodes:
          type: array
          items:
            $ref: '#/components/schemas/V3NaicsCode'
        location:
          $ref: '#/components/schemas/V3CompanyLocation'
        additionalLocations:
          type: array
          items:
            $ref: '#/components/schemas/V3CompanyLocation'
        socialLinks:
          type: object
          properties:
            linkedin:
              type: string
              example: https://www.linkedin.com/company/lushadata
        linkedinFollowers:
          type: number
          example: 64339
        revenueRange:
          type: object
          properties:
            min:
              type: number
              example: 10000000
            max:
              type: number
              example: 50000000
        funding:
          description: Funding payload when present
        intent:
          description: Intent payload when present
        technologies:
          type: array
          items:
            type: string
          example:
            - react
            - node.js
            - aws
        popularityTier:
          type: number
          example: 1
        logoUrl:
          type: string
          example: https://logo.lusha.co/logo.jpg
        employeesByDepartment:
          type: array
          description: >
            Breakdown of employees by department. Revealed via `reveal:
            ["employeesByDepartment"]` in Enrich Companies.
          items:
            type: object
            properties:
              department:
                type: string
                description: Department name
                example: Engineering & Technical
              count:
                type: integer
                description: Number of employees in this department
                example: 14
          example:
            - department: Engineering & Technical
              count: 14
            - department: Operations
              count: 40
            - department: Other
              count: 104
        employeesByLocation:
          type: array
          description: >
            Breakdown of employees by country and state. Revealed via `reveal:
            ["employeesByLocation"]` in Enrich Companies.
          items:
            type: object
            properties:
              country:
                type: string
                description: Country name
                example: United States
              state:
                type: string
                nullable: true
                description: State or region (null when not available)
                example: Colorado
              count:
                type: integer
                description: Number of employees in this location
                example: 54
          example:
            - country: United States
              state: Colorado
              count: 54
            - country: United States
              state: Texas
              count: 44
            - country: United States
              state: null
              count: 162
        employeesBySeniority:
          type: array
          description: >
            Breakdown of employees by seniority level. Revealed via `reveal:
            ["employeesBySeniority"]` in Enrich Companies.
          items:
            type: object
            properties:
              seniority:
                type: string
                description: Seniority level
                example: Manager
              count:
                type: integer
                description: Number of employees at this seniority level
                example: 39
          example:
            - seniority: Non-Manager
              count: 122
            - seniority: Manager
              count: 39
            - seniority: Vice President
              count: 3
        competitors:
          type: array
          description: >
            List of competitor companies. Revealed via `reveal: ["competitors"]`
            in Enrich Companies. Use Enrich Companies with the returned IDs to
            get full firmographic data on each competitor.
          items:
            type: object
            properties:
              id:
                type: string
                description: Lusha company ID of the competitor
                example: '2497917'
              name:
                type: string
                description: Company name of the competitor
                example: Clearbit
              domain:
                type: string
                description: Primary domain of the competitor
                example: clearbit.com
          example:
            - id: '2497917'
              name: Clearbit
              domain: clearbit.com
            - id: '9781263'
              name: Hunter.io
              domain: hunter.io
            - id: '40857684'
              name: MCJ Solutions Inc
              domain: zoominfo.com
        businessModel:
          type: array
          description: Company business model classification (e.g. B2B, B2C)
          items:
            type: string
          example:
            - B2B
        phone:
          type: string
          description: Company phone number
          example: (480) 729-6394
        email:
          type: string
          description: Company contact email address
          example: info@cobbmechanical.com
        keywords:
          type: array
          description: >-
            Keywords associated with the company (normalized from specialities
            and description)
          items:
            type: string
          example:
            - construction
            - hvac
            - plumbing
            - mechanical system
        specialitiesRefactored:
          type: array
          description: Normalized version of the specialities list
          items:
            type: string
          example:
            - construction
            - hvac
            - industrial piping
            - mechanical systems
            - plumbing
        error:
          $ref: '#/components/schemas/V3ItemError'
    V3SearchAndEnrichCompanyResult:
      allOf:
        - $ref: '#/components/schemas/V3EnrichedCompany'
        - type: object
          properties:
            clientReferenceId:
              type: string
              example: comp-ref-1
    ContactLookalikesRequest:
      type: object
      additionalProperties: false
      required:
        - seeds
      properties:
        dedupeSessionId:
          type: string
          format: uuid
          example: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
        seeds:
          $ref: '#/components/schemas/ContactIdentifiersBatch'
        exclude:
          $ref: '#/components/schemas/ContactIdentifiersBatch'
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
          example: 25
    ContactIdentifiersBatch:
      type: object
      additionalProperties: false
      properties:
        linkedinUrls:
          type: array
          items:
            type: string
          maxItems: 100
          example:
            - https://www.linkedin.com/in/orit-shilvock-6243bb5
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/ContactItem'
          maxItems: 100
        emails:
          type: array
          items:
            type: string
            format: email
          maxItems: 100
          example:
            - gal.ashkelon@lusha.com
        ids:
          type: array
          items:
            type: string
          maxItems: 100
          description: Lusha contact IDs as strings (preferred)
          example:
            - '1234'
            - '4567'
        contactIds:
          type: array
          items:
            type: integer
          maxItems: 100
          description: Lusha contact IDs as numbers (legacy; prefer ids)
          example:
            - 1234
            - 4567
      nullable: true
    ContactItem:
      type: object
      additionalProperties: false
      required:
        - firstName
        - lastName
      description: At least one of companyDomain or companyName is required.
      properties:
        firstName:
          type: string
          example: Miri
        lastName:
          type: string
          example: Tamir
        companyDomain:
          type: string
          example: lusha.com
        companyName:
          type: string
          example: Lusha
    ContactLookalikesResponse:
      type: object
      additionalProperties: false
      required:
        - dedupeSessionId
        - results
        - meta
      properties:
        dedupeSessionId:
          type: string
          format: uuid
          nullable: true
          example: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3LookAlikeContactResult'
        meta:
          $ref: '#/components/schemas/ContactLookalikesMeta'
        billing:
          $ref: '#/components/schemas/V3Billing'
    ContactLookalikesMeta:
      type: object
      additionalProperties: false
      required:
        - returned
        - hasMore
      properties:
        returned:
          type: integer
          example: 25
        hasMore:
          type: boolean
          example: true
    CompanyIdentifiersBatch:
      type: object
      properties:
        domains:
          type: array
          items:
            type: string
          maxItems: 100
          example:
            - sap.com
            - oracle.com
        linkedinUrls:
          type: array
          items:
            type: string
          maxItems: 100
          example:
            - https://www.linkedin.com/company/sap
      minProperties: 1
    CompanyLookalikesRequest:
      type: object
      required:
        - seeds
      properties:
        dedupeSessionId:
          type: string
          format: uuid
          example: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
        seeds:
          $ref: '#/components/schemas/CompanyIdentifiersBatch'
        exclude:
          $ref: '#/components/schemas/CompanyIdentifiersBatch'
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
          example: 25
    CompanyLookalikesResponse:
      type: object
      required:
        - dedupeSessionId
        - results
        - meta
      properties:
        dedupeSessionId:
          type: string
          format: uuid
          example: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3LookAlikeCompanyResult'
        meta:
          $ref: '#/components/schemas/CompanyLookalikesMeta'
        billing:
          $ref: '#/components/schemas/V3Billing'
    CompanyLookalikesMeta:
      type: object
      required:
        - returned
        - hasMore
      properties:
        returned:
          type: integer
          example: 1
        hasMore:
          type: boolean
          example: true
    V3LookAlikeCompanyResult:
      type: object
      properties:
        id:
          type: string
          example: '16303253'
        name:
          type: string
          example: Marriott International
        domain:
          type: string
          example: marriott.com
        employeeCount:
          type: object
          properties:
            exact:
              type: integer
              example: 255334
        industry:
          type: string
          example: Hospitality
        location:
          type: object
          properties:
            country:
              type: string
              example: United States
            state:
              type: string
              example: Maryland
            city:
              type: string
              example: Bethesda
        socialLinks:
          type: object
          properties:
            linkedin:
              type: string
              example: https://www.linkedin.com/company/marriott-international
    V3LookAlikeContactResult:
      type: object
      properties:
        id:
          type: string
          example: '4389064624'
        firstName:
          type: string
          example: Yehuda
        lastName:
          type: string
          example: Rapp
        socialLinks:
          type: object
          properties:
            linkedin:
              type: string
              example: https://www.linkedin.com/in/yehuda-rapp-53909b99
        company:
          type: object
          properties:
            id:
              type: string
              example: '16303253'
            name:
              type: string
              example: Lusha
            domain:
              type: string
              example: www.lusha.com
        jobTitle:
          type: object
          properties:
            title:
              type: string
              example: Senior Solutions Engineer
            departments:
              type: array
              items:
                type: string
              example:
                - Engineering & Technical
            seniority:
              type: string
              example: Senior
        location:
          type: object
          properties:
            country:
              type: string
              example: Israel
            state:
              type: string
              example: Tel Aviv District
            city:
              type: string
              example: Tel Aviv
    V3ProspectingContactFilters:
      type: object
      properties:
        contacts:
          type: object
          properties:
            include:
              $ref: '#/components/schemas/V3ContactFilterCriteria'
            exclude:
              $ref: '#/components/schemas/V3ContactFilterCriteria'
        companies:
          type: object
          properties:
            include:
              $ref: '#/components/schemas/V3CompanyFilterCriteria'
            exclude:
              $ref: '#/components/schemas/V3CompanyFilterCriteria'
    V3ContactFilterCriteria:
      type: object
      properties:
        names:
          type: array
          items:
            type: string
        jobTitles:
          type: array
          items:
            type: string
          example:
            - VP Sales
            - Director of Sales
        jobTitlesExactMatch:
          type: array
          items:
            type: string
        normalizedJobTitles:
          type: array
          items:
            type: string
        searchText:
          type: string
          maxLength: 200
        countries:
          type: array
          items:
            type: string
          example:
            - US
            - CA
        locations:
          type: array
          items:
            $ref: '#/components/schemas/V3Location'
        seniorityIds:
          type: array
          items:
            type: integer
          example:
            - 4
            - 5
        departments:
          type: array
          items:
            type: string
          example:
            - Sales
            - Engineering
        linkedinUrls:
          type: array
          items:
            type: string
        existingDataPoints:
          type: array
          items:
            type: string
          example:
            - work_email
            - work_phone
        signals:
          type: object
          properties:
            types:
              type: array
              items:
                type: string
                enum:
                  - allSignals
                  - promotion
                  - companyChange
            startDate:
              type: string
              format: date
    V3CompanyFilterCriteria:
      type: object
      properties:
        names:
          type: array
          items:
            type: string
        domains:
          type: array
          items:
            type: string
          example:
            - lusha.com
        ids:
          type: array
          items:
            type: string
        locations:
          type: array
          items:
            $ref: '#/components/schemas/V3Location'
        sizes:
          type: array
          items:
            $ref: '#/components/schemas/V3Range'
          example:
            - min: 50
              max: 500
        revenues:
          type: array
          items:
            $ref: '#/components/schemas/V3Range'
        technologies:
          type: array
          items:
            type: string
          example:
            - Salesforce
            - HubSpot
        technologiesCondition:
          type: string
          enum:
            - or
            - and
          example: or
        industriesLabels:
          type: array
          items:
            type: string
          example:
            - Software
            - SaaS
        mainIndustriesIds:
          type: array
          items:
            type: integer
        subIndustriesIds:
          type: array
          items:
            type: integer
        intentTopics:
          type: array
          items:
            type: string
          example:
            - Cloud Migration
        intentTopicsCondition:
          type: string
          enum:
            - or
            - and
        topicCountThreshold:
          type: array
          items:
            $ref: '#/components/schemas/V3Range'
        sicCodes:
          type: array
          items:
            type: string
        naicsCodes:
          type: array
          items:
            type: string
        funding:
          type: object
          properties:
            isIpo:
              type: boolean
            ranges:
              type: array
              items:
                $ref: '#/components/schemas/V3Range'
            types:
              type: array
              items:
                type: string
              example:
                - Series B
                - Series C
            investors:
              type: array
              items:
                type: string
    V3CompanyProspectingFilters:
      type: object
      properties:
        names:
          type: array
          items:
            type: string
        domains:
          type: array
          items:
            type: string
        ids:
          type: array
          items:
            type: string
        searchText:
          type: string
          maxLength: 200
        locations:
          type: array
          items:
            $ref: '#/components/schemas/V3Location'
        sizes:
          type: array
          items:
            $ref: '#/components/schemas/V3Range'
        revenues:
          type: array
          items:
            $ref: '#/components/schemas/V3Range'
        technologies:
          type: array
          items:
            type: string
        technologiesCondition:
          type: string
          enum:
            - or
            - and
        mainIndustriesIds:
          type: array
          items:
            type: integer
        subIndustriesIds:
          type: array
          items:
            type: integer
        intentTopics:
          type: array
          items:
            type: string
        intentTopicsCondition:
          type: string
          enum:
            - or
            - and
        topicCountThreshold:
          type: array
          items:
            $ref: '#/components/schemas/V3Range'
        sicCodes:
          type: array
          items:
            type: string
        naicsCodes:
          type: array
          items:
            type: string
        signals:
          type: object
          properties:
            types:
              type: array
              items:
                type: string
              example:
                - headcountIncrease3m
                - surgeInHiring
            startDate:
              type: string
              format: date
            filterByLocation:
              type: array
              items:
                type: object
                properties:
                  country:
                    type: string
                  state:
                    type: string
                  startDate:
                    type: string
                    format: date
            filterByDepartment:
              type: array
              items:
                type: object
                required:
                  - department
                properties:
                  department:
                    type: string
                    example: Engineering & Technical
                  startDate:
                    type: string
                    format: date
    V3ContactSignalsRequest:
      type: object
      required:
        - ids
        - signalTypes
      properties:
        ids:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          example:
            - '4389064624'
            - '4389064654'
        signalTypes:
          type: array
          items:
            type: string
            enum:
              - allSignals
              - promotion
              - companyChange
          example:
            - allSignals
        startDate:
          type: string
          format: date
          example: '2025-01-01'
        maxResultsPerSignal:
          type: integer
          minimum: 1
          maximum: 100
          example: 10
    V3ContactSignalsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: '4389064624'
              companyChange:
                type: array
                items:
                  type: object
              promotion:
                type: array
                items:
                  type: object
        startDate:
          type: string
        endDate:
          type: string
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3CompanySignalsRequest:
      type: object
      required:
        - ids
        - signalTypes
      properties:
        ids:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          example:
            - '16303253'
        signalTypes:
          type: array
          items:
            type: string
            enum:
              - allSignals
              - websiteTrafficDecrease
              - websiteTrafficIncrease
              - itSpendIncrease
              - itSpendDecrease
              - surgeInHiring
              - headcountIncrease1m
              - headcountIncrease3m
              - headcountIncrease6m
              - headcountIncrease12m
              - headcountDecrease1m
              - headcountDecrease3m
              - headcountDecrease6m
              - headcountDecrease12m
              - surgeInHiringByDepartment
              - surgeInHiringByLocation
              - riskNews
              - commercialActivityNews
              - corporateStrategyNews
              - financialEventsNews
              - peopleNews
              - marketIntelligenceNews
              - productActivityNews
          example:
            - allSignals
        startDate:
          type: string
          format: date
          example: '2025-01-01'
        maxResultsPerSignal:
          type: integer
          minimum: 1
          maximum: 100
          example: 10
    V3CompanySignalsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: '16303253'
              companyName:
                type: string
                example: Lusha
              domain:
                type: string
                example: lusha.com
            additionalProperties:
              type: array
              items:
                type: object
                additionalProperties: true
        startDate:
          type: string
        endDate:
          type: string
        billing:
          $ref: '#/components/schemas/V3Billing'
    ContactSignalTypesResponse:
      type: object
      properties:
        signalTypes:
          type: array
          items:
            type: string
          example:
            - allSignals
            - promotion
            - companyChange
    CompanySignalTypesResponse:
      type: object
      properties:
        signalTypes:
          type: array
          items:
            type: string
    FilterTypesDiscoveryResponse:
      type: object
      properties:
        availableFilters:
          type: array
          items:
            type: object
            properties:
              filterType:
                type: string
              requiresQuery:
                type: boolean
    FilterValuesResponse:
      type: object
      properties:
        values:
          description: Filter values (shape depends on filter type)
          nullable: true
    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'
    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'
    V3ContactsEnrichRequest:
      type: object
      required:
        - ids
      properties:
        ids:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          example:
            - '4389064654'
            - '4389064624'
        reveal:
          type: array
          items:
            type: string
            enum:
              - emails
              - phones
          example:
            - emails
            - phones
    V3ContactsEnrichResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3EnrichedContact'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3ContactsSearchAndEnrichRequest:
      type: object
      required:
        - contacts
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/V3ContactSearchItem'
          minItems: 1
          maxItems: 100
        reveal:
          type: array
          items:
            type: string
            enum:
              - emails
              - phones
          example:
            - emails
            - phones
        options:
          $ref: '#/components/schemas/V3SearchOptions'
    V3ContactsSearchAndEnrichResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3SearchAndEnrichContactResult'
        billing:
          $ref: '#/components/schemas/V3Billing'
    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'
    V3CompaniesSearchResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3CompanyPreview'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3CompaniesEnrichRequest:
      type: object
      required:
        - ids
      properties:
        ids:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: Company IDs from search results (strings)
          example:
            - '16303253'
            - '12790225'
        reveal:
          type: array
          items:
            type: string
            enum:
              - employeesByDepartment
              - employeesByLocation
              - employeesBySeniority
              - competitors
              - intent
          description: >
            Additional data fields to reveal. Each field is charged separately
            per result.

            - `employeesByDepartment` — breakdown of employees by department

            - `employeesByLocation` — breakdown of employees by country/state

            - `employeesBySeniority` — breakdown of employees by seniority level

            - `competitors` — list of competitor company IDs

            - `intent` — buyer intent topics
          example:
            - employeesByDepartment
            - employeesByLocation
            - employeesBySeniority
            - competitors
            - intent
    V3CompaniesEnrichResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3EnrichedCompany'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3CompaniesSearchAndEnrichRequest:
      type: object
      required:
        - companies
      properties:
        companies:
          type: array
          items:
            $ref: '#/components/schemas/V3CompanySearchItem'
          minItems: 1
          maxItems: 100
        options:
          $ref: '#/components/schemas/V3SearchOptions'
    V3CompaniesSearchAndEnrichResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3SearchAndEnrichCompanyResult'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3ProspectingContactsRequest:
      type: object
      required:
        - pagination
        - filters
      properties:
        pagination:
          $ref: '#/components/schemas/V3PaginationRequest'
        filters:
          $ref: '#/components/schemas/V3ProspectingContactFilters'
        options:
          type: object
          properties:
            maxContactsPerCompany:
              type: integer
            includePartialProfiles:
              type: boolean
              default: true
            excludeDnc:
              type: boolean
    V3ProspectingContactsResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3ContactPreview'
        pagination:
          $ref: '#/components/schemas/V3PaginationResponse'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3ProspectingCompaniesRequest:
      type: object
      required:
        - pagination
        - filters
      properties:
        pagination:
          $ref: '#/components/schemas/V3PaginationRequest'
        filters:
          type: object
          required:
            - companies
          properties:
            companies:
              type: object
              required:
                - include
              properties:
                include:
                  $ref: '#/components/schemas/V3CompanyProspectingFilters'
                exclude:
                  $ref: '#/components/schemas/V3CompanyProspectingFilters'
        options:
          type: object
          properties:
            maxContactsPerCompany:
              type: integer
              minimum: 1
              maximum: 500
            includePartialProfiles:
              type: boolean
              default: false
    V3ProspectingCompaniesResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3CompanyPreview'
        pagination:
          $ref: '#/components/schemas/V3PaginationResponse'
        billing:
          $ref: '#/components/schemas/V3Billing'
    CreditsUsage:
      type: object
      properties:
        total:
          type: number
          example: 10000
        used:
          type: number
          example: 1500
        remaining:
          type: number
          example: 8500
    RateLimitTier:
      type: object
      properties:
        limit:
          type: number
          example: 5000
        used:
          type: number
          example: 120
        remaining:
          type: number
          example: 4880
        resetsAt:
          type: string
          format: date-time
          example: '2026-03-31T00:00:00.000Z'
    RateLimits:
      type: object
      properties:
        daily:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RateLimitTier'
        hourly:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RateLimitTier'
        minute:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RateLimitTier'
    PlanInfo:
      type: object
      properties:
        category:
          type: string
          example: professional
        renewalType:
          type: string
          example: annual
        startDate:
          type: string
          format: date-time
          example: '2026-01-01T00:00:00.000Z'
        endDate:
          type: string
          format: date-time
          example: '2027-01-01T00:00:00.000Z'
    PricingEntry:
      type: object
      properties:
        credits:
          type: number
          example: 1
        perQuantity:
          type: number
          example: 25
    AccountUsageResponse:
      type: object
      properties:
        credits:
          $ref: '#/components/schemas/CreditsUsage'
        rateLimits:
          $ref: '#/components/schemas/RateLimits'
        plan:
          $ref: '#/components/schemas/PlanInfo'
        pricing:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PricingEntry'
    CreateSubscriptionRequest:
      type: object
      required:
        - defaults
        - subscriptions
      properties:
        defaults:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              format: uri
              maxLength: 2048
              description: Webhook URL (HTTPS required in production)
              example: https://example.com/webhooks/lusha
            entityType:
              type: string
              enum:
                - contact
                - company
              description: Default entity type for all subscriptions
              example: contact
            signalTypes:
              type: array
              items:
                type: string
              description: Default signal types for all subscriptions
              example:
                - promotion
        name:
          type: string
          maxLength: 100
          description: Default subscription name prefix
          example: Contact Webhook
        subscriptions:
          type: array
          minItems: 1
          maxItems: 25
          description: Array of subscriptions to create (max 25)
          items:
            type: object
            required:
              - entityId
            properties:
              entityId:
                type: string
                maxLength: 255
                description: Entity ID (always required per item)
                example: '123'
              entityType:
                type: string
                enum:
                  - contact
                  - company
                description: Overrides default entityType
              signalTypes:
                type: array
                items:
                  type: string
                description: Overrides default signalTypes
              name:
                type: string
                maxLength: 100
                description: Overrides default name
    CreateSubscriptionResponse:
      type: object
      required:
        - total
        - successful
        - failed
        - results
      properties:
        total:
          type: integer
          example: 3
        successful:
          type: integer
          example: 2
        failed:
          type: integer
          example: 1
        results:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/CreateSubscriptionSuccessResult'
              - $ref: '#/components/schemas/CreateSubscriptionErrorResult'
    CreateSubscriptionSuccessResult:
      type: object
      required:
        - index
        - success
        - subscription
      properties:
        index:
          type: integer
          example: 0
        success:
          type: boolean
          enum:
            - true
          example: true
        subscription:
          $ref: '#/components/schemas/SubscriptionWithoutSecret'
    CreateSubscriptionErrorResult:
      type: object
      required:
        - index
        - success
        - error
      properties:
        index:
          type: integer
          example: 1
        success:
          type: boolean
          enum:
            - false
          example: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - VALIDATION_ERROR
                - DUPLICATE_SUBSCRIPTION
                - URL_VALIDATION_FAILED
                - WEBHOOK_VERIFICATION_FAILED
                - FORBIDDEN
                - UNKNOWN_ERROR
              example: DUPLICATE_SUBSCRIPTION
            message:
              type: string
              example: >-
                Subscription already exists for entity type 'contact' with
                entity ID '456'
    DeleteSubscriptionResponse:
      type: object
      required:
        - total
        - successful
        - failed
        - results
      properties:
        total:
          type: integer
          example: 3
        successful:
          type: integer
          example: 2
        failed:
          type: integer
          example: 1
        results:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/DeleteSubscriptionSuccessResult'
              - $ref: '#/components/schemas/DeleteSubscriptionErrorResult'
    DeleteSubscriptionSuccessResult:
      type: object
      required:
        - index
        - success
        - subscription
      properties:
        index:
          type: integer
          example: 0
        success:
          type: boolean
          enum:
            - true
          example: true
        subscription:
          type: object
          properties:
            id:
              type: string
              example: sub-123
            entityType:
              type: string
              example: contact
            entityId:
              type: string
              example: '123'
            name:
              type: string
              example: Contact Webhook
    DeleteSubscriptionErrorResult:
      type: object
      required:
        - index
        - success
        - error
      properties:
        index:
          type: integer
          example: 1
        success:
          type: boolean
          enum:
            - false
          example: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - NOT_FOUND
                - VALIDATION_ERROR
                - FORBIDDEN
                - UNKNOWN_ERROR
              example: NOT_FOUND
            message:
              type: string
              example: Subscription with id 'sub-456' not found
    UpdateSubscriptionRequest:
      type: object
      properties:
        signalTypes:
          type: array
          items:
            type: string
          description: New signal types to subscribe to
        url:
          type: string
          format: uri
          maxLength: 2048
          description: New webhook URL
        name:
          type: string
          maxLength: 100
          description: New subscription name
        isActive:
          type: boolean
          description: Enable or disable subscription
        regenerateSecret:
          type: boolean
          description: Generate new webhook secret (secret will be returned in response)
    SubscriptionResponse:
      type: object
      properties:
        id:
          type: string
          example: 507f1f77bcf86cd799439011
        entityType:
          type: string
          enum:
            - contact
            - company
          example: contact
        entityId:
          type: string
          example: '123456'
        signalTypes:
          type: array
          items:
            type: string
          example:
            - promotion
            - companyChange
        url:
          type: string
          format: uri
          example: https://example.com/webhooks/lusha
        name:
          type: string
          example: Contact Promotion Tracker
        isActive:
          type: boolean
          example: true
        secret:
          type: string
          description: Webhook secret (only returned during creation or regeneration)
          example: whsec_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
        createdAt:
          type: string
          format: date-time
          example: '2026-01-14T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-01-14T10:00:00.000Z'
    SubscriptionWithoutSecret:
      type: object
      required:
        - id
        - entityType
        - entityId
        - signalTypes
        - url
        - isActive
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: 507f1f77bcf86cd799439011
        entityType:
          type: string
          enum:
            - contact
            - company
          example: contact
        entityId:
          type: string
          example: '123456'
        signalTypes:
          type: array
          items:
            type: string
          example:
            - promotion
            - companyChange
        url:
          type: string
          format: uri
          example: https://example.com/webhooks/lusha
        name:
          type: string
          example: Contact Promotion Tracker
        isActive:
          type: boolean
          example: true
        blockReason:
          type: string
          nullable: true
          description: Reason subscription was disabled (null if active)
          example: Max retries exceeded
        blockedAt:
          type: string
          format: date-time
          nullable: true
          description: When subscription was disabled (null if active)
          example: '2026-01-14T10:00:00.000Z'
        createdAt:
          type: string
          format: date-time
          example: '2026-01-14T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-01-14T10:00:00.000Z'
    OptOutSubscriptionResponse:
      type: object
      description: >-
        Response body returned when an opt-out subscription is created
        successfully
      required:
        - id
        - entityType
        - entityId
        - signalTypes
        - url
        - isActive
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: 6a0ca910b402df368d2aff07
        entityType:
          type: string
          enum:
            - contact
          example: contact
        entityId:
          type: string
          example: '431705'
        signalTypes:
          type: array
          items:
            type: string
          example:
            - optOut
        url:
          type: string
          format: uri
          example: https://example.com/webhook
        name:
          type: string
          example: Account opt-out webhook
        isActive:
          type: boolean
          example: true
        createdAt:
          type: string
          format: date-time
          example: '2026-05-19T18:16:48.360Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-05-19T18:16:48.360Z'
    WebhookPayload:
      type: object
      description: Payload sent to your webhook URL when a signal is triggered
      required:
        - id
        - type
        - entityType
        - entityId
        - subscriptionId
        - data
        - timestamp
        - billing
      properties:
        id:
          type: string
          format: uuid
          description: Unique payload ID
          example: f3b87e05-0402-4f3e-8e26-6a38fd0ad62c
        type:
          type: string
          description: Signal type that triggered the webhook
          example: promotion
        entityType:
          type: string
          enum:
            - contact
            - company
          example: contact
        entityId:
          type: string
          example: '4158887495'
        subscriptionId:
          type: string
          example: 507f1f77bcf86cd799439011
        data:
          type: object
          description: Signal-specific payload data. Structure varies by signal type.
        timestamp:
          type: string
          format: date-time
          example: '2026-01-14T16:16:35.841Z'
        billing:
          type: object
          required:
            - creditsCharged
          properties:
            creditsCharged:
              type: integer
              example: 1
    AuditLogEntry:
      type: object
      required:
        - id
        - subscriptionId
        - payloadId
        - status
        - url
        - deliveredAt
      properties:
        id:
          type: string
          example: log-123
        subscriptionId:
          type: string
          example: sub-123
        payloadId:
          type: string
          example: payload-456
        status:
          type: string
          enum:
            - success
            - failed
            - permanent_failure
          example: success
        statusCode:
          type: integer
          example: 200
        url:
          type: string
          format: uri
          example: https://example.com/webhook
        deliveredAt:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
        durationMs:
          type: integer
          example: 150
        error:
          type: string
          nullable: true
          example: null
    PaginationResponse:
      type: object
      required:
        - total
        - limit
        - offset
        - hasMore
      properties:
        total:
          type: integer
          example: 100
        limit:
          type: integer
          example: 50
        offset:
          type: integer
          example: 0
        hasMore:
          type: boolean
          example: true
    AuditLogsResponse:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AuditLogEntry'
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
    AuditLogStatsResponse:
      type: object
      required:
        - total
        - success
        - failed
        - successRate
      properties:
        total:
          type: integer
          example: 1000
        success:
          type: integer
          example: 950
        failed:
          type: integer
          example: 50
        successRate:
          type: string
          example: 95.00%
    SubscriptionListResponse:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionWithoutSecret'
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
    CreateOptOutSubscriptionRequest:
      type: object
      required:
        - entityType
        - url
      description: Request body for creating an opt-out webhook subscription
      properties:
        entityType:
          type: string
          enum:
            - contact
          description: >-
            Entity type for opt-out subscriptions. Currently only `contact` is
            supported.
          example: contact
        url:
          type: string
          format: uri
          maxLength: 2048
          description: Your webhook endpoint URL (HTTPS required in production)
          example: https://example.com/webhook
        name:
          type: string
          maxLength: 100
          description: Descriptive name for this subscription
          example: Account opt-out webhook
    OptOutDatapoint:
      type: object
      description: >-
        A single contact data point that must be removed following an opt-out
        request
      required:
        - datapointId
        - datapointType
      properties:
        datapointId:
          type: string
          description: The actual value of the data point (phone number or email address)
          example: '+14155550199'
        datapointType:
          type: string
          enum:
            - phone
            - email
          description: Type of data point
          example: phone
    OptOutWebhookPayload:
      type: object
      description: >
        Payload delivered to your opt-out webhook URL when a contact requests
        data removal.


        Your system must process this payload to remove the listed data points
        from any internal records, CRM entries, or outreach sequences.
      required:
        - contactId
        - fullName
        - contactOptOutDate
        - contactExposureDate
        - datapoints
      properties:
        contactId:
          type: string
          description: Lusha contact ID of the person who opted out
          example: '987654321'
        fullName:
          type: string
          description: Full name of the contact
          example: Jane Doe
        companyName:
          type: string
          description: Company the contact is associated with
          example: Acme Corp
        jobTitle:
          type: string
          description: Job title of the contact
          example: Director of Product
        linkedinUrl:
          type: string
          description: LinkedIn profile URL of the contact
          example: https://www.linkedin.com/in/jane-doe
        contactOptOutDate:
          type: string
          description: Timestamp when the contact submitted their opt-out request (UTC)
          example: '2026-04-22 14:32:11.412'
        contactExposureDate:
          type: string
          description: >-
            Timestamp when this contact's data was first exposed to your account
            (UTC)
          example: '2025-08-03 09:15:47'
        datapoints:
          type: array
          description: >-
            List of specific data points (emails and/or phones) that must be
            removed
          items:
            $ref: '#/components/schemas/OptOutDatapoint'
          example:
            - datapointId: '+14155550199'
              datapointType: phone
            - datapointId: jane.doe@acme.com
              datapointType: email
        partnerClientId:
          type: string
          nullable: true
          description: >
            Your internal client/tenant identifier, if provided when the contact
            data was originally revealed. Useful for multi-tenant setups to
            route the removal to the correct system.
          example: acme-crm-tenant-42
    TestSubscriptionResponse:
      type: object
      required:
        - subscriptionId
        - url
        - mode
        - isSuccess
        - timestamp
      properties:
        subscriptionId:
          type: string
          example: 507f1f77bcf86cd799439011
        subscriptionName:
          type: string
          example: My Test Webhook
        url:
          type: string
          format: uri
          example: https://example.com/webhook
        mode:
          type: string
          enum:
            - direct
            - kafka
            - full
          example: full
        flowCheck:
          type: object
          properties:
            success:
              type: boolean
              example: true
            statusCode:
              type: integer
              example: 200
            durationMs:
              type: integer
              example: 150
        testPayload:
          type: object
          properties:
            entityType:
              type: string
              example: contact
            signalType:
              type: string
              example: promotion
            data:
              type: object
        isSuccess:
          type: boolean
          example: true
        timestamp:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
