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 |

    |---|---|

    | [**Search**](#tag/Search) | Find contacts or companies using known
    identifiers |

    | [**Enrich**](#tag/Enrich) | Retrieve full profile data for contacts or
    companies by ID |

    | [**Search & Enrich**](#tag/Search-and-Enrich) | Find and retrieve full
    contact or company data in a single call |

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

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

    | [**Buying Group**](#tag/Buying-Group) | Identify decision makers,
    champions, and end users within target accounts |

    | [**Contacts Tables**](#tag/Contacts-Tables) | Persist, organize, and
    enrich contacts in reusable tables |

    | [**Companies Tables**](#tag/Companies-Tables) | Persist, organize, and
    enrich companies in reusable tables |

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

    | [**Website Visitors**](#tag/Website-Visits) | Companies ranked by
    website-visit signals for your tracked domains |

    | [**Conversations**](#tag/Conversations) | Search recorded sales
    conversations and fetch their transcripts |

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


    <blockquote class="callout">

     **Waterfall Reveal for Contact Enrichment.**

      Enrich Contacts now supports `waterfallEnabled`. Fall through to your enabled third-party providers when Lusha's own data has no match, for extra reach on hard-to-match contacts. On by default once your account has it turned on - pass `waterfallEnabled: false` to opt a specific call out. [See Enrich Contacts](#operation/enrichContacts).

    </blockquote>


    ---


    ## 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 on a per-plan basis to ensure fair usage and
    platform stability. Limits are applied across multiple time windows (per
    minute, per hour, and per day), and vary depending on your account plan.


    Rate limits for the **Credit Usage API** differ from standard endpoint
    limits.


    > **Note:** To check your current plan's limits, visit the [Lusha Help
    Center](https://info.lusha.com/en/articles/163856-all-there-is-to-know-about-lusha-s-api)
    or contact your account manager.


    **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"
    }

    ```


    **Tables-specific error codes**


    | Code | Status | Meaning |

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

    | `TABLE_NOT_FOUND` | 404 | The `table_id` does not exist or is not
    accessible to this account |

    | `COLUMN_NOT_FOUND` | 404 | The `column_id` does not exist on the given
    table |

    | `TABLE_NAME_CONFLICT` | 409 | A table with this name already exists |


    Tables error bodies use the shape `{ "message": "...", "code": <status>, ...
    }` rather than the `statusCode`/`errors` shape used elsewhere in this doc.


    **Limits:** up to 500 entity IDs per add/remove call · max 50,000 entities
    per table · max 500 tables per account · `page` 0–100 · `size` default 100.


    **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: Search
    description: >
      **Search APIs:** Find contacts or companies using known identifiers.


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


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


      > **Billing:** Charged per successful result via the `api_search` action.
    x-tag-expanded: true
  - name: Enrich
    description: >
      **Enrich APIs:** Retrieve full profile data for contacts or companies by
      ID.


      Pass IDs from Search results to reveal emails, phones, and full
      firmographic data.


      > **Billing:** Charged per revealed field via per-datapoint pricing
      (`revealEmail`, `revealPhone`, `reveal_company`).
    x-tag-expanded: true
  - name: Search & Enrich
    description: >
      **Search & Enrich APIs:** Find and retrieve full contact or company data
      in a single call.


      Combines Search and Enrich into one request. Provide identifiers and
      control what gets revealed via the `reveal` field.


      > **Billing:** Two charges apply — one for the search (`api_search`) and
      one per revealed field.
    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


      Pass `tableId` to also persist matching results into an existing table.
      See [Contacts Tables](#tag/Contacts-Tables) or [Companies
      Tables](#tag/Companies-Tables).


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


      Pass `tableId` to also persist matching results into an existing table.
      See [Contacts Tables](#tag/Contacts-Tables) or [Companies
      Tables](#tag/Companies-Tables).
    x-tag-expanded: true
  - name: Buying Group
    description: >
      **Buying Group API:** Identify and prioritize the buying committee within
      a set of target companies.


      Supply up to 25 companies by `domain` or Lusha company `id`. The model
      scores and labels each returned contact with a persona role -
      `decision_maker`, `potential_champion`, or `end_user` - so you can
      prioritize outreach across the buying committee instead of working one
      contact at a time.


      Results are lightweight previews grouped by company. Use [Enrich
      Contacts](#operation/enrichContacts) with the returned `id` to reveal
      emails and phones.


      > **Billing:** Charged per contact returned via the `buyingGroupContact`
      action.
    x-tag-expanded: true
  - name: Contacts Tables
    description: >
      **Contacts Tables API:** Create and manage persistent tables of contacts
      inside Lusha.


      Tables are spreadsheets with configurable columns — default Lusha fields,
      enrichment data, Signals, AI insights, premium data points, CRM fields,
      and custom fields. Populate a table directly through the endpoints below,
      or pass `tableId` on Prospecting, Enrich, Signals, or Lookalike calls to
      persist those results automatically.


      Every surface that touches table data — this API, MCP, and the Workspace
      UI — reads and writes the same underlying data. Changes made through one
      surface are reflected on the others.


      **Working with tables:**

      - **Tables** — create, list, get status, update
      (rename/archive/visibility), delete

      - **Entities** — add, remove, or read the rows in a table

      - **Columns** — list, remove, or run a column across a table's rows


      **Owner resolution:** `owner.email` resolves to a user on your account and
      determines table ownership. **Required on every call when authenticating
      with an API key** — omitting it returns `400`. Optional for OAuth/token
      callers, since the caller is already identified by the token. Sent in the
      body as `owner: { email }` on `POST`/`PATCH` calls (and on `DELETE
      .../entities`, which carries a body); sent as a `?email=` query parameter
      on other `GET`/`DELETE` calls, which have no body.


      **Billing:**

      - Adding contacts to a table is free.

      - Reading entities (`GET .../entities`) charges per row returned.

      - Create / List / Get / Update / Delete / List Columns / Remove Column /
      Remove Entities are free.

      - Running a column charges per row per the column's tier (contact
      enrichment per row with data; signal/AI/score per row per run).

      - Non-public-API-plan accounts always resolve to `0` credits charged.


      **Limits:** up to 500 entity IDs per add/remove call · max 50,000 entities
      per table · max 500 tables per account.


      See also: [Companies Tables](#tag/Companies-Tables).
    x-tag-expanded: true
  - name: Companies Tables
    description: >
      **Companies Tables API:** Create and manage persistent tables of companies
      inside Lusha.


      Tables are spreadsheets with configurable columns — default Lusha fields,
      enrichment data, Signals, AI insights, premium data points, CRM fields,
      and custom fields. Populate a table directly through the endpoints below,
      or pass `tableId` on Prospecting, Enrich, Signals, or Lookalike calls to
      persist those results automatically.


      Every surface that touches table data — this API, MCP, and the Workspace
      UI — reads and writes the same underlying data. Changes made through one
      surface are reflected on the others.


      **Working with tables:**

      - **Tables** — create, list, get status, update
      (rename/archive/visibility), delete

      - **Entities** — add, remove, or read the rows in a table

      - **Columns** — list, remove, or run a column across a table's rows


      **Owner resolution:** `owner.email` resolves to a user on your account and
      determines table ownership. **Required on every call when authenticating
      with an API key** — omitting it returns `400`. Optional for OAuth/token
      callers, since the caller is already identified by the token. Sent in the
      body as `owner: { email }` on `POST`/`PATCH` calls (and on `DELETE
      .../entities`, which carries a body); sent as a `?email=` query parameter
      on other `GET`/`DELETE` calls, which have no body.


      **Billing:**

      - Adding companies to a table charges `reveal_company` per **newly added**
      company, deduped so duplicates and already-present companies aren't
      charged again.

      - Reading entities (`GET .../entities`) charges per row returned.

      - Create / List / Get / Update / Delete / List Columns / Remove Column /
      Remove Entities are free.

      - Running a column charges per row per the column's tier (company
      enrichment once per company per table — re-runs on an already-paid company
      are free; signal/AI/score per row per run).

      - Non-public-API-plan accounts always resolve to `0` credits charged.


      **Limits:** up to 500 entity IDs per add/remove call · max 50,000 entities
      per table · max 500 tables per account.


      See also: [Contacts Tables](#tag/Contacts-Tables).
    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`


      ----


      **Signal Score:** Use [Score Companies by Signal
      Activity](#operation/getCompanySignalScores) or [Score Contacts by Signal
      Activity](#operation/getContactSignalScores) to get a single aggregate
      momentum score ([0,1]) plus the active signal breakdown for a batch of
      entities, rather than a raw event list.


      ----


      Credits are charged per matched signal per result via `showSignalsContact`
      or `showSignalsCompany`.


      Pass `tableId` to also persist matching results into an existing table.
      See [Contacts Tables](#tag/Contacts-Tables) or [Companies
      Tables](#tag/Companies-Tables).
    x-tag-expanded: true
  - name: Website Visits
    description: >
      Retrieve companies ranked by website-visit signals for your tracked
      domains.

       Domains must be configured for tracking in the dashboard. Each result combines a V3 company firmographic preview with behavioral visit metrics (score, sessions, unique visitors, avg session length, and more).
    x-tag-expanded: true
  - name: Conversations
    description: >
      **Conversations API:** Search the sales conversations recorded by Lusha
      Conversations for your account, and fetch speaker-attributed transcripts.


      Search Conversations returns each conversation's metadata, AI summary,
      action items, risks, objections, competitor mentions, coaching analysis,
      and chapters — transcripts are not included. Fetch the transcript for a
      single conversation separately.


      **Two search modes on one contract:**

      - **Keyword mode** — supply `query` to rank conversations by transcript
      content. All other filters are ignored.

      - **Filter mode** — omit `query` and supply the structural filters (dates,
      contact names, company domains, meeting titles).


      Only conversations belonging to your account whose post-call processing
      has completed are returned. `summary`, `coaching`, and `chapters` come
      from an asynchronous pipeline and are `null`/empty until it has run — a
      `null` summary means "analysis not ready yet", not "nothing found".


      > **Billing:** Search charges 1 credit per block of up to 25 conversations
      returned (via `ci_meeting_data_export`); a request that returns nothing is
      free. Transcript charges 1 credit per successful request (via
      `ci_transcript_analysis`); a `404` is never charged. While the relevant
      action isn't yet seeded on your account's pricebook, the endpoint stays
      free (`billing.creditsCharged` is `0`).
    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:
        - Search
      summary: Search Contacts
      operationId: searchContacts
      description: >
        Look up contacts by identifier. Returns a non-PII preview of each
        profile — no emails or phone numbers.


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

        - Lusha contact `id`

        - `linkedinUrl`

        - `email`

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


        Up to 100 contacts per request. Each result includes:

        - `has` — data points available on this profile

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


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


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


        ---


        ###  Waterfall Reveal

        Fall through to your enabled third-party providers when Lusha's own data
        has no match, for extra reach on hard-to-match contacts.


        If **Data Waterfall** is enabled on your account, with specific
        providers turned on under **Account > Waterfall**, the waterfall runs
        automatically on every Enrich Contacts call - you don't need to pass
        anything to trigger it.



        Pass `waterfallEnabled: false` to opt a specific call out:

          ```json
                          "reveal": ["emails", "phones"],
                          "waterfallEnabled": false
          ```

        - `reveal` controls **which fields** come back.

        - `waterfallEnabled` controls whether the waterfall runs for this call
        at all. Defaults to `true` whenever Data Waterfall is enabled on your
        account; pass `false` to disable it just for this call.

        - Provider order isn't configurable - Lusha manages that internally.

        - If Data Waterfall is off or no providers are enabled on your account,
        `waterfallEnabled` has no effect either way.

        ---

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


        > **Persisting to a table:** Pass `tableId` to also add these contacts
        to an existing table and populate the Work email / Phone columns. See
        [Contacts Tables](#tag/Contacts-Tables).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ContactsEnrichRequest'
            examples:
              standard:
                summary: >-
                  Standard reveal (waterfall runs automatically if enabled on
                  your account)
                value:
                  ids:
                    - '4389064654'
                    - '4389064624'
                  reveal:
                    - emails
                    - phones
              waterfallDisabled:
                summary: Opt this call out of the waterfall
                value:
                  ids:
                    - '4389064654'
                    - '4389064624'
                  reveal:
                    - emails
                    - phones
                  waterfallEnabled: false
      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:
        - Search & Enrich
      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:
        - Search
      summary: Search Companies
      operationId: searchCompanies
      description: >
        Look up companies by identifier. Returns a preview of each company
        profile.


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

        - Lusha company `id`

        - `name`

        - `domain`


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


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


        > **Billing:** Charged per successful result via the `api_search`
        action.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3CompaniesSearchRequest'
            example:
              companies:
                - clientReferenceId: comp-ref-1
                  name: Lusha
                - clientReferenceId: comp-ref-2
                  domain: salesforce.com
                - clientReferenceId: comp-ref-3
                  id: '16303253'
              options:
                includePartialProfiles: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3CompaniesSearchResponse'
              example:
                requestId: abd4a213-d33b-4565-b9b6-55c19c65cc47
                results:
                  - clientReferenceId: comp-ref-1
                    id: '16303253'
                    name: Lusha
                    domain: www.lusha.com
                    employeeCount:
                      exact: 364
                      min: 201
                      max: 500
                    industry: Technology, Information & Media
                    location:
                      city: Boston
                      state: Massachusetts
                      country: United States
                      countryIso2: US
                      continent: North America
                    socialLinks:
                      linkedin: https://www.linkedin.com/company/lushadata
                    has:
                      - alternativeName
                      - alternativeDomains
                      - description
                      - companyType
                      - yearFounded
                      - subIndustry
                      - specialities
                      - sicCodes
                      - naicsCodes
                      - additionalLocations
                      - linkedinFollowers
                      - funding
                      - popularityTier
                      - logoUrl
                      - employeesByDepartment
                      - employeesByLocation
                      - employeesBySeniority
                      - competitors
                      - businessModel
                      - emails
                      - keywords
                      - socialLinks
                    canReveal:
                      - field: employeesByDepartment
                        credits: 1
                      - field: employeesByLocation
                        credits: 1
                      - field: employeesBySeniority
                        credits: 1
                      - field: competitors
                        credits: 1
                  - clientReferenceId: comp-ref-2
                    id: '12790225'
                    name: Salesforce
                    domain: www.salesforce.com
                    employeeCount:
                      exact: 88711
                      min: 100001
                      max: 10000000
                    industry: Technology, Information & Media
                    location:
                      city: San Francisco
                      state: California
                      country: United States
                      countryIso2: US
                      continent: North America
                    socialLinks:
                      linkedin: https://www.linkedin.com/company/salesforce
                    has:
                      - alternativeName
                      - alternativeDomains
                      - description
                      - companyType
                      - subIndustry
                      - sicCodes
                      - naicsCodes
                      - additionalLocations
                      - linkedinFollowers
                      - revenueRange
                      - intent
                      - popularityTier
                      - logoUrl
                      - employeesByDepartment
                      - employeesByLocation
                      - employeesBySeniority
                      - competitors
                      - phones
                      - emails
                      - socialLinks
                    canReveal:
                      - field: employeesByDepartment
                        credits: 1
                      - field: employeesByLocation
                        credits: 1
                      - field: employeesBySeniority
                        credits: 1
                      - field: competitors
                        credits: 1
                      - field: intent
                        credits: 0
                billing:
                  creditsCharged: 1
                  resultsReturned: 3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v3/companies/enrich:
    post:
      tags:
        - Enrich
      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

        - Open job posting counts: total and breakdowns by department, location,
        and seniority


        > **Billing:** Charged per successful result via the `reveal_company`
        action.


        > **Persisting to a table:** Pass `tableId` to also add these companies
        to an existing table and populate the relevant enrichment columns. See
        [Companies Tables](#tag/Companies-Tables).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3CompaniesEnrichRequest'
            example:
              ids:
                - '16303253'
                - '12790225'
              reveal:
                - employeesByLocation
                - employeesByDepartment
                - employeesBySeniority
                - competitors
                - intent
                - openJobsTotal
                - openJobsByDepartment
      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
                      facebook: https://www.facebook.com/lusha
                      x: https://x.com/lusha
                    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
                    openJobs:
                      total: 47
                      byDepartment:
                        - department: Engineering & Technical
                          count: 21
                        - department: Sales
                          count: 9
                  - 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: 12
                  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:
        - Search & Enrich
      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


        Use `options.maxContactsPerCompany` (1–20) to cap how many contacts are
        returned per company; `pagination.size` still controls the page size. 


        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.


        > **Persisting to a table:** Pass `tableId` to also persist matching
        results into an existing table. This is additive — the primary response
        is unchanged, and a `tableWrite` object is added showing what happened
        on the table side. See [Contacts Tables](#tag/Contacts-Tables).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ProspectingContactsRequest'
            example:
              pagination:
                page: 0
                size: 100
              filters:
                contacts:
                  include:
                    departments:
                      - Sales
                    locations:
                      - country: United States
                    existingDataPoints:
                      - work_email
                companies:
                  include:
                    locations:
                      - country: United States
                    foundedYear:
                      - min: 2000
                    businessModel:
                      - B2B
                    companyType:
                      - Public Company
                    linkedinUrls:
                      - https://www.linkedin.com/company/google
                    keywords:
                      - fintech
                  exclude:
                    domains:
                      - competitor.com
                    companyType:
                      - Self Employed
              tableId: '482910'
              options:
                includePartialProfiles: true
                excludeDnc: false
                maxContactsPerCompany: 2
      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
                  totalGuaranteed: true
                  totalDescription: Exact contact count (up to 2 per company)
                results:
                  - id: '670138733'
                    firstName: Ting
                    lastName: Tsou
                tableWrite:
                  tableId: '482910'
                  added: 48
                  alreadyPresent: 2
                  columnsCreated: []
                  rowsProcessed: 50
                  rowsCharged: 48
                  rowsAlreadyPaidInTable: 2
                billing:
                  creditsCharged: 2
                  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,
        LinkedIn activity intent)


        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.


        > **Persisting to a table:** Pass `tableId` to also persist matching
        results into an existing table. This is additive — the primary response
        is unchanged, and a `tableWrite` object is added showing what happened
        on the table side. See [Companies Tables](#tag/Companies-Tables).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ProspectingCompaniesRequest'
            example:
              pagination:
                page: 0
                size: 25
              filters:
                companies:
                  include:
                    sizes:
                      - min: 1
                        max: 1000
                    revenues:
                      - min: 10000000
                    locations:
                      - country: United States
                    technologies:
                      - React
                      - Node.js
                    technologiesCondition: or
                    mainIndustriesIds:
                      - 1
                      - 5
                    intentTopics:
                      - Cloud Migration
                    foundedYear:
                      - min: 1990
                        max: 2020
                    businessModel:
                      - B2B
                      - B2G
                    companyType:
                      - Public Company
                      - Private Company
                    linkedinUrls:
                      - https://www.linkedin.com/company/microsoft
                    keywords:
                      - cloud
                      - artificial intelligence
                    signals:
                      types:
                        - headcountIncrease3m
                        - surgeInHiring
                      startDate: '2025-01-01'
                  exclude:
                    domains:
                      - competitor.com
                    businessModel:
                      - B2C
                    companyType:
                      - Non Profit
                    keywords:
                      - staffing
              tableId: '583021'
              options:
                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
                tableWrite:
                  tableId: '583021'
                  added: 1
                  alreadyPresent: 0
                  columnsCreated: []
                  rowsProcessed: 1
                  rowsCharged: 1
                  rowsAlreadyPaidInTable: 0
                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.


        > **Persisting to a table:** Pass `tableId` to also persist matching
        results into an existing table. See [Contacts
        Tables](#tag/Contacts-Tables).
      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.


        > **Persisting to a table:** Pass `tableId` to also persist matching
        results into an existing table. See [Companies
        Tables](#tag/Companies-Tables).
      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/buying-group:
    post:
      tags:
        - Buying Group
      summary: Get Buying Group Contacts
      operationId: getContactsBuyingGroup
      description: >
        Identify the buying group within a set of target companies. Supply
        companies by `domain` or Lusha company `id` - the model scores and
        labels each returned contact with a persona role.


        **Personas:**

        - `decision_maker` — has budget or sign-off authority

        - `potential_champion` — likely internal advocate for the purchase

        - `end_user` — likely day-to-day user of the product


        Pass `personas` to filter to specific roles, or omit it to get all
        three. Use `contactsLimit` to cap how many contacts are returned per
        company (default 60).


        Results are lightweight previews grouped by company. Each contact
        includes a `has` field listing available data points, a `canReveal`
        field showing what can be unlocked via Enrich, a `roles` array with the
        assigned persona(s), and a `score` (0-1) reflecting relevance to the
        assigned role.


        Use Enrich Contacts with the returned contact `id` to reveal emails and
        phones.


        > **Billing:** Charged per contact returned via the `buyingGroupContact`
        action.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3BuyingGroupRequest'
            example:
              companies:
                - clientReferenceId: comp-ref-1
                  domain: acme.com
                - clientReferenceId: comp-ref-2
                  id: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
              personas:
                - decision_maker
                - potential_champion
              contactsLimit: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3BuyingGroupResponse'
              example:
                requestId: 951d46da-24f9-4608-84bf-5e70a10bf851
                results:
                  - companyId: v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP
                    contacts:
                      - id: v1.VdKU4HkaDb7CE4CEImoUcm7bxUGUUz-aOQ
                        firstName: Mohammed
                        lastName: Alam
                        jobTitle:
                          title: RF/Analog IC Design Engineer
                          departments:
                            - Engineering & Technical
                          seniority: Non-Manager
                        company:
                          id: v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP
                          name: Intel
                          domain: www.intel.com
                        location:
                          country: United States
                          state: Arizona
                          city: Chandler
                        socialLinks:
                          linkedin: https://www.linkedin.com/in/mohammed-alam-83759111
                        has:
                          - firstName
                          - lastName
                          - jobTitle
                          - company
                          - location
                          - socialLinks
                          - phones
                          - previousEmployment
                          - jobStartDate
                        canReveal:
                          - field: phones
                            credits: 5
                        roles:
                          - potential_champion
                        score: 0.8872673511505127
                pagination:
                  page: 0
                  size: 100
                  total: 1
                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/tables:
    post:
      tags:
        - Contacts Tables
      summary: Create Contacts Table
      operationId: createContactsTable
      description: >
        Create a new, empty contacts table, optionally seeded with an initial
        list of contact IDs.


        > **Billing:** Free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableCreateRequest'
            example:
              name: VP Sales US Tech Q2
              visibility: private
              owner:
                email: user@example.com
              ids:
                - '10042851'
                - '10042852'
      responses:
        '201':
          description: Table created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/TableNameConflict'
  /v3/contacts/tables/list:
    post:
      tags:
        - Contacts Tables
      summary: List Contacts Tables
      operationId: listContactsTables
      description: >
        List contacts tables owned by the given user, plus any tables shared
        with the account.


        > **Billing:** Free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableListRequest'
            example:
              owner:
                email: user@example.com
              page: 0
              size: 10
              status: active
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/contacts/tables/{table_id}:
    get:
      tags:
        - Contacts Tables
      summary: Get Contacts Table
      operationId: getContactsTable
      description: |
        Get a table's metadata and current processing status.

        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/OwnerEmailQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
    patch:
      tags:
        - Contacts Tables
      summary: Update Contacts Table
      operationId: updateContactsTable
      description: >
        Rename a table, change its visibility, or reassign its owner. All fields
        except `owner` are optional — send only what changes.


        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableUpdateRequest'
            example:
              name: postman-renamed
              visibility: shared
              owner:
                email: user@example.com
      responses:
        '200':
          description: Table updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
    delete:
      tags:
        - Contacts Tables
      summary: Delete Contacts Table
      operationId: deleteContactsTable
      description: |
        Permanently delete a table and all its data. This cannot be undone.

        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/OwnerEmailQuery'
      responses:
        '200':
          description: Table deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  tableId:
                    type: string
                    example: '482910'
                  status:
                    type: string
                    example: deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
  /v3/contacts/tables/{table_id}/entities:
    get:
      tags:
        - Contacts Tables
      summary: Get Contacts Table Entities
      operationId: getContactsTableEntities
      description: >
        Read a page of rows in the table, with all column values and per-cell
        status.


        > **Billing:** Charged per row returned via `export_api`.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/OwnerEmailQuery'
        - name: page
          in: query
          schema:
            type: integer
            maximum: 100
            default: 0
        - name: size
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitiesGetResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
    post:
      tags:
        - Contacts Tables
      summary: Add Entities to Contacts Table
      operationId: addContactsTableEntities
      description: >
        Add up to 500 contact IDs to an existing table. `entityIds` accepts
        either the encrypted Lusha token (`v{N}.…`, as returned by
        Search/Enrich/Get Entities) or the legacy numeric `personId` — an ID
        that's neither returns `400`. Already-present IDs are reported as
        `alreadyPresent` and not re-added; unresolvable IDs are not an error,
        they come back in `invalidIds` with a `200`.


        Optionally pass `companyIds` — one `lushaCompanyId` per contact,
        index-aligned with `entityIds` — to help pair company-level enrichment
        to the right company for each contact.


        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitiesAddRequest'
            example:
              entityIds:
                - '10042854'
                - '10042855'
                - '10042856'
              companyIds:
                - '16303253'
                - '16303253'
                - '12790225'
              owner:
                email: user@example.com
      responses:
        '200':
          description: Entities added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitiesAddResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
    delete:
      tags:
        - Contacts Tables
      summary: Remove Entities from Contacts Table
      operationId: removeContactsTableEntities
      description: |
        Remove specific contact IDs from a table.

        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitiesRemoveRequest'
            example:
              entityIds:
                - '10042851'
                - '10042852'
              owner:
                email: user@example.com
      responses:
        '200':
          description: Entities removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitiesRemoveResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
  /v3/contacts/tables/{table_id}/columns:
    get:
      tags:
        - Contacts Tables
      summary: List Contacts Table Columns
      operationId: listContactsTableColumns
      description: >
        List the columns on a table, with type and aggregated per-cell status
        counts.


        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/OwnerEmailQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ColumnsListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
  /v3/contacts/tables/{table_id}/columns/{column_id}:
    delete:
      tags:
        - Contacts Tables
      summary: Remove Column from Contacts Table
      operationId: removeContactsTableColumn
      description: >
        Remove a column and delete all of its cell data across the table.
        Default Lusha columns cannot be removed.


        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/ColumnIdPath'
        - $ref: '#/components/parameters/OwnerEmailQuery'
      responses:
        '200':
          description: Column removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  tableId:
                    type: string
                  columnId:
                    type: string
                  removed:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ColumnNotFound'
  /v3/contacts/tables/{table_id}/columns/{column_id}/run:
    post:
      tags:
        - Contacts Tables
      summary: Run Column on Contacts Table
      operationId: runContactsTableColumn
      description: >
        Populate or refresh a column's data for some or all rows in the table.
        This is **asynchronous** — the call returns immediately with `status:
        "processing"`; poll Get Contacts Table for `isProcessing` and per-column
        row-status counts to know when it's done, then read the values via Get
        Contacts Table Entities.


        **`runScope` values:**

        - `all` — every row, including already-processed ones (re-runs /
        refreshes). Most expensive.

        - `missing` — only rows that have never been run for this column.
        Cheapest, safe to call repeatedly.

        - `specific` — only the `entityIds` you pass. Also how you implement
        "run for this page" — fetch the page via Get Contacts Table Entities,
        then pass those IDs here.


        > **Billing:** Charged per row processed, per the column's credit tier.
        Re-running with `all` charges again for rows that already have data.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/ColumnIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ColumnsRunRequest'
            example:
              runScope: specific
              entityIds:
                - '10042851'
                - '10042852'
              owner:
                email: user@example.com
      responses:
        '200':
          description: Column run started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ColumnsRunResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ColumnNotFound'
  /v3/companies/tables:
    post:
      tags:
        - Companies Tables
      summary: Create Companies Table
      operationId: createCompaniesTable
      description: >
        Create a new, empty companies table, optionally seeded with an initial
        list of company IDs.


        > **Billing:** Free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableCreateRequest'
            example:
              name: postman-companies
              visibility: private
              owner:
                email: user@example.com
      responses:
        '201':
          description: Table created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/TableNameConflict'
  /v3/companies/tables/list:
    post:
      tags:
        - Companies Tables
      summary: List Companies Tables
      operationId: listCompaniesTables
      description: >
        List companies tables owned by the given user, plus any tables shared
        with the account.


        > **Billing:** Free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableListRequest'
            example:
              owner:
                email: user@example.com
              page: 0
              size: 10
              status: active
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/companies/tables/{table_id}:
    get:
      tags:
        - Companies Tables
      summary: Get Companies Table
      operationId: getCompaniesTable
      description: |
        Get a table's metadata and current processing status.

        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/OwnerEmailQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
    patch:
      tags:
        - Companies Tables
      summary: Update Companies Table
      operationId: updateCompaniesTable
      description: >
        Rename a table, change its visibility, or reassign its owner. All fields
        except `owner` are optional — send only what changes.


        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableUpdateRequest'
            example:
              name: postman-renamed
              visibility: shared
              owner:
                email: user@example.com
      responses:
        '200':
          description: Table updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
    delete:
      tags:
        - Companies Tables
      summary: Delete Companies Table
      operationId: deleteCompaniesTable
      description: |
        Permanently delete a table and all its data. This cannot be undone.

        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/OwnerEmailQuery'
      responses:
        '200':
          description: Table deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  tableId:
                    type: string
                    example: '583021'
                  status:
                    type: string
                    example: deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
  /v3/companies/tables/{table_id}/entities:
    get:
      tags:
        - Companies Tables
      summary: Get Companies Table Entities
      operationId: getCompaniesTableEntities
      description: >
        Read a page of rows in the table, with all column values and per-cell
        status.


        > **Billing:** Charged per row returned via `export_api`.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/OwnerEmailQuery'
        - name: page
          in: query
          schema:
            type: integer
            maximum: 100
            default: 0
        - name: size
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitiesGetResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
    post:
      tags:
        - Companies Tables
      summary: Add Entities to Companies Table
      operationId: addCompaniesTableEntities
      description: >
        Add up to 500 company IDs to an existing table. `entityIds` accepts
        either the encrypted Lusha token (`v{N}.…`, as returned by
        Search/Enrich/Get Entities) or the legacy numeric `lushaCompanyId` — an
        ID that's neither returns `400`. Already-present IDs are reported as
        `alreadyPresent` and not re-added; unresolvable IDs are not an error,
        they come back in `invalidIds` with a `200`.


        > **Billing:** Charges `reveal_company` per newly-added company, deduped
        via row-count delta — duplicates and already-present companies aren't
        charged again.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitiesAddRequest'
            example:
              entityIds:
                - '30058211'
                - '30058212'
              owner:
                email: user@example.com
      responses:
        '200':
          description: Entities added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitiesAddResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
    delete:
      tags:
        - Companies Tables
      summary: Remove Entities from Companies Table
      operationId: removeCompaniesTableEntities
      description: |
        Remove specific company IDs from a table.

        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitiesRemoveRequest'
            example:
              entityIds:
                - '10117615'
              owner:
                email: user@example.com
      responses:
        '200':
          description: Entities removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitiesRemoveResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
  /v3/companies/tables/{table_id}/columns:
    get:
      tags:
        - Companies Tables
      summary: List Companies Table Columns
      operationId: listCompaniesTableColumns
      description: >
        List the columns on a table, with type and aggregated per-cell status
        counts.


        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/OwnerEmailQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ColumnsListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TableNotFound'
  /v3/companies/tables/{table_id}/columns/{column_id}:
    delete:
      tags:
        - Companies Tables
      summary: Remove Column from Companies Table
      operationId: removeCompaniesTableColumn
      description: >
        Remove a column and delete all of its cell data across the table.
        Default Lusha columns cannot be removed.


        > **Billing:** Free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/ColumnIdPath'
        - $ref: '#/components/parameters/OwnerEmailQuery'
      responses:
        '200':
          description: Column removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  tableId:
                    type: string
                  columnId:
                    type: string
                  removed:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ColumnNotFound'
  /v3/companies/tables/{table_id}/columns/{column_id}/run:
    post:
      tags:
        - Companies Tables
      summary: Run Column on Companies Table
      operationId: runCompaniesTableColumn
      description: >
        Populate or refresh a column's data for some or all rows in the table.
        This is **asynchronous** — the call returns immediately with `status:
        "processing"`; poll Get Companies Table for `isProcessing` and
        per-column row-status counts to know when it's done, then read the
        values via Get Companies Table Entities.


        **`runScope` values:**

        - `all` — every row, including already-processed ones (re-runs /
        refreshes). Most expensive.

        - `missing` — only rows that have never been run for this column.
        Cheapest, safe to call repeatedly.

        - `specific` — only the `entityIds` you pass. Also how you implement
        "run for this page" — fetch the page via Get Companies Table Entities,
        then pass those IDs here.


        > **Billing:** Charged per row processed, per the column's credit tier.
        Company enrichment charges once per company per table — re-runs on an
        already-paid company in the same table are free.
      parameters:
        - $ref: '#/components/parameters/TableIdPath'
        - $ref: '#/components/parameters/ColumnIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ColumnsRunRequest'
            example:
              runScope: missing
              owner:
                email: user@example.com
      responses:
        '200':
          description: Column run started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ColumnsRunResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ColumnNotFound'
  /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.


        > **Persisting to a table:** Pass `tableId` to also add these contacts
        to an existing table and populate the Signals column. See [Contacts
        Tables](#tag/Contacts-Tables).
      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.


        > **Persisting to a table:** Pass `tableId` to also add these companies
        to an existing table and populate the Signals column. See [Companies
        Tables](#tag/Companies-Tables).
      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
                  - linkedinActivityIntent
                  - 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
                  - filterType: intentCategories
                    requiresQuery: false
        '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) |

        | `intentCategories` | No — the `query` parameter is not supported for
        this filter type; passing one returns `400` |
      parameters:
        - name: filterType
          in: path
          required: true
          schema:
            type: string
            enum:
              - newsEventTypes
              - hiringByDepartments
              - hiringByLocations
              - intentCategories
        - 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/companies/signal-score:
    post:
      tags:
        - Signals
      summary: Score Companies by Signal Activity
      operationId: getCompanySignalScores
      description: >
        Score companies by their active buying signals. Returns the aggregate
        Signal Score - a `[0, 1]` value reflecting the fraction of the company's
        active signals - plus the active signal breakdown.


        Accepts up to 100 companies, each identified by exactly one of `id`,
        `domain`, `name`, or `email`. All identifiers are resolved to Lusha
        company IDs server-side before scoring.


        Each result is one of:

        - A **scored entry** - `signalScore`, `signalTypes`, and
        `noActiveSignals`.

        - A **`NOT_FOUND`** entry - the company service could not resolve the
        supplied identifier.

        - A **`NO_SCORE`** entry - the company resolved, but the scoring engine
        returned nothing for it.


        > **Billing:** 1 credit is charged per scored row via
        `signal_score_company_reveal`. This action is currently
        limited-availability - while it isn't yet seeded on an account's
        pricebook, the endpoint stays free (`billing.creditsCharged` is `0`).
        Error rows (`NOT_FOUND` / `NO_SCORE`) are never charged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3SignalScoreCompaniesRequest'
            example:
              companies:
                - clientReferenceId: ref-1
                  id: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
                - clientReferenceId: ref-2
                  domain: www.microsoft.com
                - clientReferenceId: ref-3
                  name: Apple
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3SignalScoreCompaniesResponse'
              example:
                requestId: 5d6f13d2-f6b0-4e55-85d5-04e17f932c1a
                results:
                  - clientReferenceId: ref-1
                    id: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
                    name: Acme Corp
                    domain: www.acmecorp.io
                    signalScore: 0.42
                    signalTypes:
                      - hiringSignalIncrease
                      - websiteVisit
                    noActiveSignals: false
                  - clientReferenceId: ref-2
                    id: v1.6789ZyXwVuTsRqPoNmLkJiHgFeDcBa01
                    name: Microsoft
                    domain: www.microsoft.com
                    signalScore: 0
                    signalTypes: []
                    noActiveSignals: true
                  - clientReferenceId: ref-3
                    domain: nope-xyz.com
                    error:
                      code: NOT_FOUND
                      message: Company not found
                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/signal-score:
    post:
      tags:
        - Signals
      summary: Score Contacts by Signal Activity
      operationId: getContactSignalScores
      description: >
        Score contacts by their active buying signals. Returns the aggregate
        Signal Score - a `[0, 1]` value - plus the active signal breakdown per
        contact.


        Accepts up to 100 contacts. Each contact is resolved to a Lusha person
        ID and company ID server-side (identity only - no PII is revealed)
        before scoring. Provide one of:

        - `id` (encrypted Lusha contact ID)

        - `linkedinUrl`

        - `email`

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


        Each result is one of:

        - A **scored entry** - `signalScore`, `signalTypes`, and
        `noActiveSignals`.

        - A **`NOT_FOUND`** entry - identity resolution failed for the supplied
        identifier.

        - A **`NO_SCORE`** entry - the contact resolved, but the scoring engine
        returned nothing for it.


        > **Note:** A full outage of the identity-resolution provider is never
        masked as `NOT_FOUND` - it returns a retryable `502` instead, so callers
        can retry rather than treating the batch as authoritatively unresolved.


        > **Billing:** 1 credit is charged per scored row via
        `signal_score_contact_reveal`. This action is currently
        limited-availability - while it isn't yet seeded on an account's
        pricebook, the endpoint stays free (`billing.creditsCharged` is `0`).
        Error rows (`NOT_FOUND` / `NO_SCORE`) are never charged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3SignalScoreContactsRequest'
            example:
              contacts:
                - clientReferenceId: ref-1
                  id: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
                - clientReferenceId: ref-2
                  linkedinUrl: https://linkedin.com/in/johndoe
                - clientReferenceId: ref-3
                  firstName: Jane
                  lastName: Doe
                  companyDomain: acme.com
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3SignalScoreContactsResponse'
              example:
                requestId: 5d6f13d2-f6b0-4e55-85d5-04e17f932c1a
                results:
                  - clientReferenceId: ref-1
                    id: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
                    fullName: Jane Doe
                    company:
                      id: v1.6789ZyXwVuTsRqPoNmLkJiHgFeDcBa01
                      name: Acme Corp
                      domain: acme.com
                    signalScore: 0.3
                    signalTypes:
                      - promotion
                    noActiveSignals: false
                  - clientReferenceId: ref-2
                    error:
                      code: NOT_FOUND
                      message: Contact not found
                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'
        '502':
          $ref: '#/components/responses/BadGateway'
  /v3/companies/website-visits:
    post:
      tags:
        - Website Visits
      summary: Get Website Visitors
      x-badges:
        - name: Beta
          color: purple
      operationId: getWebsiteVisits
      description: >
        Returns companies ranked by website-visit signals for your tracked
        domains and date range.


        Domains must be configured for tracking in the Lusha dashboard — they
        are resolved to site IDs server-side. Each result combines a V3 company
        firmographic preview (same shape as Search Companies) with behavioral
        visit metrics.


        **Notes:**

        - Date range must be ≤ 3 months

        - If any requested domain is not configured for tracking, the entire
        request fails with `400`

        - `limit` accepts 1–150
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebsiteVisitsRequest'
            example:
              domains:
                - lusha.com
                - google.com
              startDate: '2026-01-01'
              endDate: '2026-03-18'
              pagination:
                size: 25
                page: 0
              sort:
                by: score
                order: desc
              filters:
                scoreBands:
                  - hot
                  - warm
                score:
                  min: 50
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebsiteVisitsResponse'
              example:
                requestId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                results:
                  - id: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
                    name: Lusha
                    domain: www.lusha.com
                    industry: Software Development
                    employeeCount:
                      min: 201
                      max: 500
                    location:
                      city: Tel Aviv
                      country: Israel
                      countryIso2: IL
                    socialLinks:
                      linkedin: https://www.linkedin.com/company/lusha
                    has:
                      - competitors
                      - socialLinks
                    canReveal:
                      - field: competitors
                        credits: 1
                    score: 87
                    scoreBand: hot
                    totalSessions: 12
                    uniqueVisitors: 5
                    avgSessionMinutes: 4.2
                    daysVisited: 8
                    highIntentPageviews: 10
                    daysSinceLastVisit: 6
                    lastVisit: '2026-03-20'
                    visitorCountry: US
                pagination:
                  size: 25
                  page: 0
                  total: 142
                billing:
                  creditsCharged: 0
                  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/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'
  /v3/account/conversations/search:
    post:
      tags:
        - Conversations
      summary: Search Conversations
      operationId: searchConversations
      description: >
        Search the sales conversations recorded by Lusha Conversations for your
        account. Returns each conversation's metadata, AI summary, action items,
        risks, objections, competitor mentions, coaching analysis, and chapters.
        Transcripts are not included — fetch those from [Get Conversation
        Transcript](#operation/getConversationTranscript).


        **Two modes on the same contract:**

        - **Keyword mode** — supply `query` to rank conversations by transcript
        content. All other filters are ignored.

        - **Filter mode** — omit `query` and supply the structural filters.


        Both modes return the same response shape. An empty body is valid and
        returns the first page of the account's conversations.


        **Validation notes:**

        - `companyDomains` matches on domain, not display name. Resolve a
        company name to a domain first (e.g. via [Search
        Companies](#operation/searchCompanies)).

        - `dateFrom` / `dateTo` accept date-only `YYYY-MM-DD` values. Datetimes,
        reduced precision (`2026`, `2026-01`), basic format (`20260101`), and
        impossible dates (`2026-02-31`) are rejected with `400`.

        - `pageSize` above 100 is rejected with `400` — it is not silently
        clamped.

        - `conversationIds` that don't exist, are still processing, or belong to
        another account are omitted from the response rather than erroring.


        > **Billing:** 1 credit per block of up to 25 conversations returned
        (1–25 = 1, 26–50 = 2, 51–75 = 3, 76–100 = 4), via
        `ci_meeting_data_export`. Charged on results returned, not the page size
        requested. A request that returns nothing is free. While
        `ci_meeting_data_export` isn't seeded on your account's pricebook, the
        endpoint stays free (`billing.creditsCharged` is `0`).


        > **Note:** `summary`, `coaching`, and `chapters` come from an
        asynchronous post-call pipeline. A `null` summary on a recent
        conversation means analysis isn't ready yet, not "nothing found". A
        `null` `severity` on a risk or objection means the pipeline didn't
        assess it — do not read it as "low".
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ConversationsSearchRequest'
            examples:
              keywordMode:
                summary: Keyword mode (ranks by transcript content)
                value:
                  query: pricing objection
                  page: 1
                  pageSize: 25
              filterMode:
                summary: Filter mode (structural filters)
                value:
                  dateFrom: '2026-01-01'
                  dateTo: '2026-03-31'
                  companyDomains:
                    - acme.com
                  contactNames:
                    - Jane Doe
                  meetingTitles:
                    - Quarterly review
                  page: 1
                  pageSize: 25
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ConversationsSearchResponse'
              example:
                requestId: 3f1a9c2e-7b4d-4a8e-9f10-2c5d6e7a8b90
                conversations:
                  - id: 8f2c9b1e-4a7d-4f3b-9c2e-1d6a5b8c7e90
                    title: Acme <> Lusha - Quarterly review
                    date: '2026-03-12'
                    startTime: '2026-03-12T14:00:00Z'
                    durationSeconds: 1830
                    durationFormatted: 30m 30s
                    meetingType: discovery
                    isExternal: true
                    company:
                      name: Acme Inc
                      domain: acme.com
                    participants:
                      - name: Jane Doe
                        email: jane@acme.com
                        role: VP Sales
                        isInternal: false
                      - name: Sam Rep
                        email: sam@lusha.com
                        role: AE
                        isInternal: true
                    topicLabels:
                      - pricing
                      - security
                    summary:
                      text: The team walked through the pricing tiers.
                      keyHighlights:
                        - Budget confirmed for Q3
                      actionItems:
                        - text: Send the revised pricing sheet
                          owner: Sam Rep
                          dueDate: '2026-03-19'
                      nextSteps:
                        - Schedule a technical deep dive
                      risks:
                        - text: Budget approval is still pending
                          severity: high
                      objections:
                        - text: Price is above the current spend
                          severity: null
                      competition:
                        - name: Competitor Inc
                          context: Mentioned as incumbent
                          sentiment: negative
                    coaching:
                      overallScore: 68
                      likelihoodOfSale: 45
                      sections:
                        - section: discovery
                          score: 72
                          whatHappened: The rep opened with a clear agenda.
                          whatToKeep:
                            - Strong discovery questions
                          whatToImprove:
                            - Confirm the decision process earlier
                      notes: Focus on quantifying impact.
                    chapters:
                      - index: 0
                        title: Introductions
                        startTime: '00:00:00'
                        endTime: '00:04:12'
                        summary: Participants introduced themselves.
                page:
                  page: 1
                  pageSize: 25
                  totalItems: 137
                  totalPages: 6
                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/account/conversations/{conversationId}/transcript:
    get:
      tags:
        - Conversations
      summary: Get Conversation Transcript
      operationId: getConversationTranscript
      description: >
        Returns the speaker-attributed, timestamped transcript of a single
        conversation. Get the `conversationId` from [Search
        Conversations](#operation/searchConversations).


        No request body and no query parameters.


        > **Billing:** 1 credit per successful request via
        `ci_transcript_analysis`, including repeat requests for the same
        conversation. A `404` is never charged. While `ci_transcript_analysis`
        isn't seeded on your account's pricebook, the endpoint stays free.


        > **Note:** A single `404` covers all three cases — the conversation
        doesn't exist, its processing hasn't completed, or it belongs to another
        account. Transcripts can be long; when feeding one to an LLM, budget for
        it or summarize it (Search Conversations already returns the summary,
        chapters, and coaching without the transcript).
      parameters:
        - name: conversationId
          in: path
          required: true
          description: Conversation identifier returned by Search Conversations.
          schema:
            type: string
          example: 8f2c9b1e-4a7d-4f3b-9c2e-1d6a5b8c7e90
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ConversationTranscriptResponse'
              example:
                requestId: 3f1a9c2e-7b4d-4a8e-9f10-2c5d6e7a8b90
                conversationId: 8f2c9b1e-4a7d-4f3b-9c2e-1d6a5b8c7e90
                segments:
                  - speaker: Jane Doe
                    side: external
                    text: We need to understand the pricing tiers before we commit.
                    startTime: '00:12:04'
                    endTime: '00:12:19'
                  - speaker: Sam Rep
                    side: internal
                    text: Happy to walk you through them.
                    startTime: '00:12:20'
                    endTime: '00:12:26'
                billing:
                  creditsCharged: 1
                  resultsReturned: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
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.
  parameters:
    TableIdPath:
      name: table_id
      in: path
      required: true
      description: The table's ID.
      schema:
        type: string
      example: '482910'
    ColumnIdPath:
      name: column_id
      in: path
      required: true
      description: The column's ID.
      schema:
        type: string
      example: col_signals_funding
    OwnerEmailQuery:
      name: email
      in: query
      required: false
      description: >-
        Email of the user making the request. Used to scope ownership/visibility
        checks on GET/DELETE calls, which cannot carry a body.
      schema:
        type: string
        format: email
      example: user@example.com
  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, V3 access not enabled, or plan does not
        include this feature
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            accountInactive:
              summary: Account inactive
              value:
                statusCode: 403
                message: >-
                  Your account is not active. Please reach out to support at
                  support@lusha.com
            v3NotEnabled:
              summary: V3 access not enabled
              value:
                statusCode: 403
                message: V3 API access is not enabled for your account
    BadGateway:
      description: >-
        Bad gateway - upstream identity resolution provider is unavailable.
        Retryable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 502
            message: >-
              Identity resolution provider is temporarily unavailable. Retry
              with backoff.
    NotFound:
      description: Not found - resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 404
            message: Resource not found
    TableNotFound:
      description: Not found - table does not exist or is not accessible to this account
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 404
            message: 'TABLE_NOT_FOUND: Table not found'
    ColumnNotFound:
      description: Not found - column does not exist on the given table
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 404
            message: 'COLUMN_NOT_FOUND: Column not found'
    TableNameConflict:
      description: Conflict - a table with this name already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 409
            message: 'TABLE_NAME_CONFLICT: A table with this name already exists'
    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
            - NO_SCORE
          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
        region:
          type: string
          example: California
        countryIso2:
          type: string
          example: US
    V3Range:
      type: object
      description: Numeric range filter
      properties:
        min:
          type: integer
          minimum: 0
          example: 1
        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
    V3ProspectingContactsPagination:
      type: object
      description: >
        Pagination for Prospecting Contacts. Extends the standard pagination
        object with two optional fields describing the `total` count. Both keys
        are omitted when not returned.
      allOf:
        - $ref: '#/components/schemas/V3PaginationResponse'
        - type: object
          properties:
            totalGuaranteed:
              type: boolean
              description: '`true` when `total` is an exact count rather than an estimate.'
              example: true
            totalDescription:
              type: string
              description: Human-readable explanation of `total`.
              example: Exact contact count (up to 2 per company).
    TableOwner:
      type: object
      description: >
        Identifies the user acting on the table, and resolves to a user on your
        account. Required on every table-route call when authenticating with an
        API key (there is no signed-in user) — omitting it returns `400`.
        Optional for OAuth/token callers, since the caller is already identified
        by the token; still accepted if you want to act on behalf of another
        owner.
      properties:
        email:
          type: string
          format: email
          description: >-
            Must resolve to an existing user on the account tied to your API
            key.
          example: user@example.com
    CellStatus:
      type: string
      enum:
        - not_run
        - processing
        - success
        - no_data
        - failed
      description: >
        Current state of a single cell's data. `no_data` means the run succeeded
        but found nothing — distinct from `failed`, which means the run itself
        errored.
    RunScope:
      type: string
      enum:
        - all
        - missing
        - specific
      description: >
        Controls which rows a column operation applies to. `all` re-runs every
        row, including already-processed ones. `missing` only runs rows that
        don't have a value for this column yet. `specific` requires `entityIds`.
    TableWrite:
      type: object
      description: >
        Added to a Prospecting, Enrich, Signals, or Lookalike response when
        `tableId` is passed on the request. The primary response is unaffected
        even if the table write fails.
      properties:
        tableId:
          type: string
          example: '482910'
        added:
          type: integer
          description: Number of new entities added to the table by this call.
          example: 3
        alreadyPresent:
          type: integer
          description: Number of entities from this call that were already in the table.
          example: 2
        columnsCreated:
          type: integer
          description: >-
            Number of columns auto-created by this call (e.g. a Signals column
            created on first use).
          example: 0
        rowsProcessed:
          type: integer
          description: Number of rows the column-run touched as part of this call.
          example: 5
        rowsCharged:
          type: integer
          description: Number of those rows that incurred a credit charge.
          example: 5
        rowsAlreadyPaidInTable:
          type: integer
          description: >-
            Number of those rows that were already paid for in this table and
            were not re-charged.
          example: 0
        creditsCharged:
          type: integer
          description: Credits charged specifically for this table write.
          example: 0
    CreatedBy:
      type: object
      description: Where and by whom the table was created.
      properties:
        surface:
          type: string
          enum:
            - api
            - mcp
            - workspace
          example: api
        createdByUserId:
          type: integer
          example: 12345
    AddedBy:
      type: object
      description: Where and by whom a row was added to the table.
      properties:
        surface:
          type: string
          enum:
            - api
            - mcp
            - workspace
          example: api
    TableMetadata:
      type: object
      description: TableDto — static metadata for a table.
      properties:
        tableId:
          type: string
          example: '482910'
        name:
          type: string
          example: VP Sales US Tech Q2
        entityType:
          type: string
          enum:
            - contacts
            - companies
          example: contacts
        visibility:
          type: string
          enum:
            - private
            - shared
          example: private
        status:
          type: string
          enum:
            - active
            - archived
            - deleted
          description: >
            Lifecycle state. `active` and `archived` are filterable via the List
            Tables `status` field; `deleted` is not a filterable status.
          example: active
        owner:
          $ref: '#/components/schemas/OwnerInfo'
        createdBy:
          $ref: '#/components/schemas/CreatedBy'
        workspaceUrl:
          type: string
          example: https://workspace.lusha.com/tables/482910
    OwnerInfo:
      type: object
      description: >
        Resolved owner of the table. `id` is always present; `email` and `name`
        are resolved best-effort within the API key's account and may be omitted
        if resolution fails (in which case the object contains only `id`).
        Replaces the removed top-level `ownerId` field - this is a breaking
        change from the prior response shape.
      properties:
        id:
          type: integer
          example: 12345
        email:
          type: string
          format: email
          example: owner@lusha.com
        name:
          type: string
          example: Ada Lovelace
    TableStatusData:
      type: object
      description: >-
        Response payload for Get Table — TableDto fields plus live entity/column
        counts.
      allOf:
        - $ref: '#/components/schemas/TableMetadata'
        - type: object
          properties:
            entityCount:
              type: integer
              example: 5
            isProcessing:
              type: boolean
              description: Whether any column run is currently in progress on this table.
              example: false
            columns:
              type: array
              items:
                $ref: '#/components/schemas/ColumnSummary'
    TableResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TableStatusData'
        billing:
          $ref: '#/components/schemas/V3Billing'
    TableCreateRequest:
      type: object
      required:
        - name
        - owner
      properties:
        name:
          type: string
          example: postman-companies
        visibility:
          type: string
          enum:
            - private
            - shared
          default: private
        owner:
          $ref: '#/components/schemas/TableOwner'
        ids:
          type: array
          description: Optional initial entity IDs to seed the table with.
          items:
            type: string
          example:
            - '10042851'
            - '10042852'
    TableUpdateRequest:
      type: object
      required:
        - owner
      description: >
        `name`, `visibility`, and `archived` are all optional — send any subset;
        omitted fields stay unchanged. Sending none of them is a no-op. A
        partial update re-reads the persisted table first, so fields you don't
        send are never clobbered.
      properties:
        name:
          type: string
          example: renamed
        visibility:
          type: string
          enum:
            - private
            - shared
          example: shared
        archived:
          type: boolean
          description: >-
            Set `true` to archive the table (hides it from default List Tables
            results), `false` to restore it.
          example: true
        owner:
          $ref: '#/components/schemas/TableOwner'
    TableListRequest:
      type: object
      required:
        - owner
      properties:
        owner:
          $ref: '#/components/schemas/TableOwner'
        page:
          type: integer
          minimum: 0
          maximum: 100
          default: 0
        size:
          type: integer
          default: 100
        name:
          type: string
          description: Optional filter — matches tables whose name contains this text.
          example: Q3
        status:
          type: string
          enum:
            - active
            - archived
          description: '`deleted` is not a filterable status.'
    TableListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TableMetadata'
        pagination:
          $ref: '#/components/schemas/V3PaginationResponse'
        billing:
          $ref: '#/components/schemas/V3Billing'
    EntitiesAddRequest:
      type: object
      required:
        - entityIds
        - owner
      properties:
        entityIds:
          type: array
          items:
            type: string
          maxItems: 500
          description: >
            Lusha IDs as strings — `personId` for contacts, `lushaCompanyId` for
            companies. Accepts either the encrypted token (`v{N}.…`, as returned
            by Search/Enrich/Get Entities) or the legacy numeric ID. An ID that
            is neither a valid token nor numeric returns `400`.
          example:
            - '10042854'
            - '10042855'
            - '10042856'
        companyIds:
          type: array
          items:
            type: string
          description: >
            Contacts tables only. One `lushaCompanyId` per contact (encrypted
            token or numeric), index-aligned with `entityIds`, to help pair
            company-level enrichment to the right company for each contact.
            Ignored on companies tables.
          example:
            - '16303253'
            - '16303253'
            - '12790225'
        owner:
          $ref: '#/components/schemas/TableOwner'
    EntitiesAddResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            added:
              type: integer
              example: 20
            alreadyPresent:
              type: integer
              example: 5
            invalidIds:
              type: array
              description: >-
                IDs that couldn't be resolved. Not an error — the call still
                returns `200`.
              items:
                type: string
              example: []
            addedBy:
              $ref: '#/components/schemas/AddedBy'
        billing:
          $ref: '#/components/schemas/V3Billing'
    EntitiesRemoveRequest:
      type: object
      required:
        - entityIds
        - owner
      properties:
        entityIds:
          type: array
          items:
            type: string
          description: >
            Accepts either the encrypted token (`v{N}.…`, as returned by Get
            Entities) or the legacy numeric ID. Unresolved IDs are echoed back
            in `invalidIds` in the exact form you sent them.
          example:
            - '10042851'
            - '10042852'
        owner:
          $ref: '#/components/schemas/TableOwner'
    EntitiesRemoveResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            removed:
              type: integer
              example: 10
            invalidIds:
              type: array
              items:
                type: string
              example: []
        billing:
          $ref: '#/components/schemas/V3Billing'
    EntityColumnValue:
      type: object
      description: >
        One column's value on a single row, as returned by Get Entities. This
        shape is a passthrough from the underlying Workspace service — the
        fields shown here (`id`, `name`, `type`, `sourceType`, `value`,
        `status`) are representative, not an exhaustive schema.
      properties:
        id:
          type: string
          example: f8c1a2b3
        name:
          type: string
          example: company_name
        type:
          type: string
          example: string
        sourceType:
          type: string
          example: lusha
        value:
          nullable: true
          description: The cell's data. Shape depends on the column type.
          example: Google
        status:
          $ref: '#/components/schemas/CellStatus'
    TableEntity:
      type: object
      description: >
        A single row. `id` is the **encrypted** Lusha ID (`v{N}.…`) — `personId`
        for contacts, `lushaCompanyId` for companies — in the same format used
        across V3, so it round-trips directly into Add Entities, Remove
        Entities, and Enrich. Internal fields (`accountId`, `companyLid`,
        `lushaCompanyId`, `personId`, `companyDetails`) are not returned.
        Remaining per-row fields under `columns` are owned by the Workspace
        service; this shape is representative, not an exhaustive schema.
      properties:
        id:
          type: string
          description: Encrypted Lusha ID.
          example: v1.aB3kZ9example
        columns:
          type: array
          items:
            $ref: '#/components/schemas/EntityColumnValue'
    EntitiesGetResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TableEntity'
        pagination:
          $ref: '#/components/schemas/V3PaginationResponse'
        billing:
          $ref: '#/components/schemas/V3Billing'
    ColumnSummary:
      type: object
      description: >-
        ColumnDto — a column's definition plus aggregated per-cell status
        counts.
      properties:
        columnId:
          type: string
          example: c1
        name:
          type: string
          example: Job title
        type:
          type: string
          enum:
            - lusha
            - crm
            - signal
            - ai
            - score
          example: lusha
        key:
          type: string
          nullable: true
          example: jobTitle
        isDefault:
          type: boolean
          description: Default Lusha columns cannot be removed.
          example: false
        addedAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        rowsNotRun:
          type: integer
        rowsProcessing:
          type: integer
        rowsSuccess:
          type: integer
        rowsNoData:
          type: integer
        rowsFailed:
          type: integer
    ColumnsListResponse:
      type: object
      description: Response for List Columns — `data` is a bare array of ColumnDto.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ColumnSummary'
        billing:
          $ref: '#/components/schemas/V3Billing'
    ColumnsAddRequest:
      type: object
      required:
        - name
        - type
        - owner
      properties:
        name:
          type: string
          example: Job title
        type:
          type: string
          enum:
            - lusha
            - crm
            - signal
            - ai
            - score
          example: lusha
        key:
          type: string
          description: >-
            Optional, type-specific key identifying which underlying
            field/signal/etc. this column pulls.
          example: jobTitle
        meta:
          type: object
          description: Optional, type-specific configuration for the column.
          example: {}
        runScope:
          $ref: '#/components/schemas/RunScope'
        entityIds:
          type: array
          items:
            type: string
          description: Required only when `runScope` is `specific`.
        owner:
          $ref: '#/components/schemas/TableOwner'
    ColumnsAddResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            columnId:
              type: string
              example: c1
            name:
              type: string
              example: Job title
            type:
              type: string
              example: lusha
            runStatus:
              type: string
              nullable: true
              description: Present only if `runScope` triggered a run on add.
              example: processing
        billing:
          $ref: '#/components/schemas/V3Billing'
    ColumnsRunRequest:
      type: object
      required:
        - runScope
        - owner
      properties:
        runScope:
          $ref: '#/components/schemas/RunScope'
        entityIds:
          type: array
          items:
            type: string
          description: Required when `runScope` is `specific`.
        owner:
          $ref: '#/components/schemas/TableOwner'
    ColumnsRunResponse:
      type: object
      description: >
        Run is asynchronous — this response confirms the run was accepted. Poll
        Get Table for per-column row-status counts to know when it's finished.
      properties:
        data:
          type: object
          properties:
            columnId:
              type: string
              example: c1
            runScope:
              $ref: '#/components/schemas/RunScope'
            status:
              type: string
              example: processing
        billing:
          $ref: '#/components/schemas/V3Billing'
    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
    WebsiteVisitsIntRange:
      type: object
      description: Integer range filter (non-negative)
      properties:
        min:
          type: integer
          minimum: 0
        max:
          type: integer
          minimum: 0
    WebsiteVisitsFloatRange:
      type: object
      description: Float range filter (non-negative)
      properties:
        min:
          type: number
          minimum: 0
        max:
          type: number
          minimum: 0
    WebsiteVisitsFilters:
      type: object
      properties:
        scoreBands:
          type: array
          items:
            type: string
            enum:
              - cold
              - warm
              - hot
          description: Restrict to specific score bands.
          example:
            - hot
            - warm
        visitorCountries:
          type: object
          description: ISO 3166-1 alpha-2 country code filters.
          properties:
            include:
              type: array
              items:
                type: string
              example:
                - US
                - GB
            exclude:
              type: array
              items:
                type: string
              example:
                - CN
        score:
          allOf:
            - $ref: '#/components/schemas/WebsiteVisitsIntRange'
          description: Score range (1–100).
        totalSessions:
          $ref: '#/components/schemas/WebsiteVisitsIntRange'
        avgSessionMinutes:
          $ref: '#/components/schemas/WebsiteVisitsFloatRange'
        uniqueVisitors:
          $ref: '#/components/schemas/WebsiteVisitsIntRange'
        daysVisited:
          $ref: '#/components/schemas/WebsiteVisitsIntRange'
        highIntentPageviews:
          $ref: '#/components/schemas/WebsiteVisitsIntRange'
        daysSinceLastVisit:
          $ref: '#/components/schemas/WebsiteVisitsIntRange'
    WebsiteVisitsRequest:
      type: object
      required:
        - domains
        - startDate
        - endDate
        - pagination
      properties:
        domains:
          type: array
          items:
            type: string
          minItems: 1
          description: Domains configured for tracking in the Lusha dashboard.
          example:
            - lusha.com
            - google.com
        startDate:
          type: string
          format: date
          description: Window start date (YYYY-MM-DD).
          example: '2026-01-01'
        endDate:
          type: string
          format: date
          description: Window end date (YYYY-MM-DD). Range must be ≤ 3 months.
          example: '2026-03-18'
        pagination:
          type: object
          required:
            - page
            - size
          properties:
            size:
              type: integer
              minimum: 1
              maximum: 150
              example: 25
            page:
              type: integer
              minimum: 0
              example: 0
        sort:
          type: object
          properties:
            by:
              type: string
              description: Field to sort by (e.g. `score`).
              example: score
            order:
              type: string
              enum:
                - asc
                - desc
              example: desc
        filters:
          $ref: '#/components/schemas/WebsiteVisitsFilters'
    WebsiteVisitsCompanyResult:
      allOf:
        - $ref: '#/components/schemas/V3CompanyPreview'
        - type: object
          description: Firmographic preview plus behavioral visit metrics.
          properties:
            score:
              type: number
              description: Display score (0–100).
              example: 87
            scoreBand:
              type: string
              enum:
                - cold
                - warm
                - hot
              description: Qualitative score band.
              example: hot
            totalSessions:
              type: number
              description: Total sessions in the window.
              example: 12
            uniqueVisitors:
              type: number
              description: Distinct visitors in the window.
              example: 5
            avgSessionMinutes:
              type: number
              description: Average session length in minutes.
              example: 4.2
            daysVisited:
              type: number
              description: Distinct days with activity.
              example: 8
            highIntentPageviews:
              type: number
              description: High-intent pageviews in the window.
              example: 10
            daysSinceLastVisit:
              type: number
              description: Days since the most recent visit.
              example: 6
            lastVisit:
              type: string
              format: date
              description: Date of the last visit in the window.
              example: '2026-03-20'
            visitorCountry:
              type: string
              description: >-
                Primary visitor country (ISO 3166-1 alpha-2). Omitted if
                unavailable.
              example: US
    WebsiteVisitsPagination:
      type: object
      required:
        - page
        - size
        - total
      properties:
        size:
          type: integer
          example: 25
        page:
          type: integer
          example: 0
        total:
          type: integer
          description: Total results across all pages.
          example: 142
    WebsiteVisitsResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        results:
          type: array
          items:
            $ref: '#/components/schemas/WebsiteVisitsCompanyResult'
        pagination:
          $ref: '#/components/schemas/WebsiteVisitsPagination'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3CompanySearchItem:
      type: object
      properties:
        clientReferenceId:
          type: string
          example: comp-ref-1
        id:
          type: string
          example: '16303253'
        name:
          type: string
          example: Lusha
        domain:
          type: string
          example: lusha.com
    V3CompanySignalsDto:
      type: object
      required:
        - types
      properties:
        types:
          type: array
          items:
            type: string
            enum:
              - allSignals
              - linkedinActivityIntent
              - websiteTrafficDecrease
              - websiteTrafficIncrease
              - itSpendIncrease
              - itSpendDecrease
              - surgeInHiring
              - headcountIncrease1m
              - headcountIncrease3m
              - headcountIncrease6m
              - headcountIncrease12m
              - headcountDecrease1m
              - headcountDecrease3m
              - headcountDecrease6m
              - headcountDecrease12m
              - surgeInHiringByDepartment
              - surgeInHiringByLocation
              - riskNews
              - commercialActivityNews
              - corporateStrategyNews
              - financialEventsNews
              - peopleNews
              - marketIntelligenceNews
              - productActivityNews
          example:
            - headcountIncrease3m
            - surgeInHiring
        startDate:
          type: string
          format: date
          example: '2025-01-01'
        maxResultsPerSignal:
          type: integer
          minimum: 1
          maximum: 100
          example: 10
    V3CompanyPreview:
      type: object
      properties:
        clientReferenceId:
          type: string
          example: comp-ref-1
        id:
          type: string
          example: '16303253'
        name:
          type: string
          example: Lusha
        domain:
          type: string
          example: www.lusha.com
        employeeCount:
          type: object
          properties:
            exact:
              type: integer
              example: 364
            min:
              type: integer
              example: 201
            max:
              type: integer
              example: 500
        industry:
          type: string
          example: Technology, Information & Media
        location:
          type: object
          properties:
            city:
              type: string
              example: London
            state:
              type: string
              example: England
            stateCode:
              type: string
              description: Free field. ISO/postal state or region code, when available.
              example: MA
            country:
              type: string
              example: United Kingdom
            countryIso2:
              type: string
              example: GB
            continent:
              type: string
              example: Europe
        socialLinks:
          type: object
          properties:
            linkedin:
              type: string
              example: https://www.linkedin.com/company/lushadata
        has:
          type: array
          items:
            type: string
          description: >
            Available data points that can be revealed via Enrich Companies.
            Includes base firmographic fields plus new revealable fields:
            employeesByDepartment, employeesByLocation, employeesBySeniority,
            competitors, businessModel, phones, emails, keywords, socialLinks,
            estimatedAnnualItSpend, monthlyWebsiteTraffic, openJobs.
          example:
            - alternativeName
            - alternativeDomains
            - description
            - companyType
            - yearFounded
            - subIndustry
            - specialities
            - sicCodes
            - naicsCodes
            - additionalLocations
            - linkedinFollowers
            - popularityTier
            - logoUrl
            - employeesByDepartment
            - employeesByLocation
            - employeesBySeniority
            - competitors
            - businessModel
            - phones
            - emails
            - keywords
            - socialLinks
            - estimatedAnnualItSpend
            - monthlyWebsiteTraffic
            - openJobs
        canReveal:
          type: array
          description: >
            Data fields that can be revealed via Enrich Companies, with the
            credit cost per field. A cost of 0 means the field has already been
            revealed for this account.
          items:
            $ref: '#/components/schemas/V3CanRevealItem'
          example:
            - field: employeesByDepartment
              credits: 1
            - field: employeesByLocation
              credits: 1
            - field: employeesBySeniority
              credits: 1
            - field: competitors
              credits: 1
            - field: intent
              credits: 0
            - field: estimatedAnnualItSpend
              credits: 1
            - field: monthlyWebsiteTraffic
              credits: 1
            - field: openJobsTotal
              credits: 1
            - field: openJobsByDepartment
              credits: 1
            - field: openJobsByLocation
              credits: 1
            - field: openJobsBySeniority
              credits: 1
        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
        stateCode:
          type: string
          description: Free field. ISO/postal state or region code, when available.
          example: MA
        country:
          type: string
          example: United Kingdom
        countryIso2:
          type: string
          example: GB
        continent:
          type: string
          example: Europe
        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
    V3OpenJobsByDepartment:
      type: object
      description: Open job posting count for a single department.
      properties:
        department:
          type: string
          example: Engineering
        count:
          type: integer
          example: 21
    V3OpenJobsByLocation:
      type: object
      description: Open job posting count for a single location.
      properties:
        location:
          type: string
          example: United States
        count:
          type: integer
          example: 12
    V3OpenJobsBySeniority:
      type: object
      description: Open job posting count for a single seniority level.
      properties:
        seniority:
          type: string
          example: Manager
        count:
          type: integer
          example: 5
    V3OpenJobs:
      type: object
      description: >
        Open job posting counts. Each sub-field is revealed independently in
        Enrich Companies via `reveal: ["openJobsTotal", "openJobsByDepartment",
        "openJobsByLocation", "openJobsBySeniority"]`. A sub-field is present
        only when its matching token was requested in `reveal` and data exists
        for it; sub-fields that weren't requested, or that have no data, are
        omitted. Department, location, and seniority values use the same
        vocabularies as the existing prospecting filters.
      nullable: true
      properties:
        total:
          type: integer
          description: Total number of open job postings. Revealed via `openJobsTotal`.
          example: 47
        byDepartment:
          type: array
          description: >-
            Open job counts broken down by department. Revealed via
            `openJobsByDepartment`.
          items:
            $ref: '#/components/schemas/V3OpenJobsByDepartment'
        byLocation:
          type: array
          description: >-
            Open job counts broken down by location. Revealed via
            `openJobsByLocation`.
          items:
            $ref: '#/components/schemas/V3OpenJobsByLocation'
        bySeniority:
          type: array
          description: >-
            Open job counts broken down by seniority level. Revealed via
            `openJobsBySeniority`.
          items:
            $ref: '#/components/schemas/V3OpenJobsBySeniority'
    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'
        companyOffering:
          type: string
          description: Free field. Short description of what the company sells or does.
          example: Cloud-based CRM software for small businesses
        emailDomain:
          type: string
          description: Free field. Primary domain used for company email addresses.
          example: lusha.com
        additionalIndustries:
          type: array
          description: >-
            Free field. Up to 2 secondary industry classifications beyond the
            primary `industry`/`subIndustry`.
          maxItems: 2
          items:
            type: object
            properties:
              industry:
                type: string
                example: Financial Services
              subIndustry:
                type: string
                example: Insurance
        estimatedAnnualItSpend:
          type: object
          description: >-
            Revealed via reveal: ["estimatedAnnualItSpend"] in Enrich Companies.
            Charged 1 credit when non-null.
          nullable: true
          properties:
            value:
              type: number
              example: 500000
            currency:
              type: string
              example: USD
            valueUsd:
              type: number
              example: 500000
        monthlyWebsiteTraffic:
          type: object
          description: >-
            Revealed via reveal: ["monthlyWebsiteTraffic"] in Enrich Companies.
            Charged 1 credit when non-null.
          nullable: true
          properties:
            visits:
              type: number
              example: 128450
            momChangePercent:
              type: number
              example: 4.3
            month:
              type: string
              example: 2026-06
        openJobs:
          $ref: '#/components/schemas/V3OpenJobs'
        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
            facebook:
              type: string
              nullable: true
              description: >
                Company Facebook page URL. Included automatically when available
                - no `reveal` entry needed. Omitted from the response when not
                available (never returned empty). Free field - no credits
                charged. Available on all plans.
              example: https://www.facebook.com/lusha
            x:
              type: string
              nullable: true
              description: >
                Company X (formerly Twitter) profile URL. Included automatically
                when available - no `reveal` entry needed. Omitted from the
                response when not available (never returned empty). Free field -
                no credits charged. Available on all plans.
              example: https://x.com/lusha
        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
        tableId:
          type: string
          description: >-
            Optional. If provided, results are also persisted to this table. See
            the Tables API.
          example: '482910'
    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'
        tableWrite:
          $ref: '#/components/schemas/TableWrite'
        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
        tableId:
          type: string
          description: >-
            Optional. If provided, results are also persisted to this table. See
            the Tables API.
          example: '583021'
    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'
        tableWrite:
          $ref: '#/components/schemas/TableWrite'
        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
    V3BuyingGroupCompanyItem:
      type: object
      description: Identifies one target company. Provide exactly one of domain or id.
      properties:
        clientReferenceId:
          type: string
          description: Optional caller-supplied token, echoed back on the matching result.
          example: comp-ref-1
        domain:
          type: string
          example: acme.com
        id:
          type: string
          description: Lusha company ID.
          example: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
    V3BuyingGroupRequest:
      type: object
      required:
        - companies
      properties:
        companies:
          type: array
          items:
            $ref: '#/components/schemas/V3BuyingGroupCompanyItem'
          minItems: 1
          maxItems: 25
        personas:
          type: array
          description: Filter results to specific persona roles. Omit to return all three.
          items:
            type: string
            enum:
              - decision_maker
              - potential_champion
              - end_user
          example:
            - decision_maker
            - potential_champion
        contactsLimit:
          type: integer
          description: Maximum number of contacts returned per company.
          default: 60
          minimum: 1
          example: 20
        pagination:
          type: object
          description: Optional. If omitted, defaults to page 0, size 100.
          properties:
            page:
              type: integer
              minimum: 0
              default: 0
              example: 0
            size:
              type: integer
              minimum: 10
              maximum: 100
              default: 100
              example: 100
    V3BuyingGroupContact:
      type: object
      properties:
        id:
          type: string
          example: v1.VdKU4HkaDb7CE4CEImoUcm7bxUGUUz-aOQ
        firstName:
          type: string
          example: Mohammed
        lastName:
          type: string
          example: Alam
        jobTitle:
          type: object
          properties:
            title:
              type: string
              example: RF/Analog IC Design Engineer
            departments:
              type: array
              items:
                type: string
              example:
                - Engineering & Technical
            seniority:
              type: string
              example: Non-Manager
        company:
          type: object
          properties:
            id:
              type: string
              example: v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP
            name:
              type: string
              example: Intel
            domain:
              type: string
              example: www.intel.com
        location:
          type: object
          properties:
            country:
              type: string
              example: United States
            state:
              type: string
              example: Arizona
            city:
              type: string
              example: Chandler
        socialLinks:
          type: object
          properties:
            linkedin:
              type: string
              example: https://www.linkedin.com/in/mohammed-alam-83759111
        has:
          type: array
          items:
            type: string
          example:
            - firstName
            - lastName
            - jobTitle
            - company
            - location
            - socialLinks
            - phones
            - previousEmployment
            - jobStartDate
        canReveal:
          type: array
          items:
            $ref: '#/components/schemas/V3CanRevealItem'
        roles:
          type: array
          description: Persona role(s) the model assigned to this contact.
          items:
            type: string
            enum:
              - decision_maker
              - potential_champion
              - end_user
          example:
            - potential_champion
        score:
          type: number
          minimum: 0
          maximum: 1
          description: Relevance score for the assigned role(s).
          example: 0.8872673511505127
        error:
          $ref: '#/components/schemas/V3ItemError'
    V3BuyingGroupCompanyResult:
      type: object
      properties:
        clientReferenceId:
          type: string
          example: comp-ref-1
        companyId:
          type: string
          example: v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/V3BuyingGroupContact'
        error:
          $ref: '#/components/schemas/V3ItemError'
    V3BuyingGroupResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          example: 951d46da-24f9-4608-84bf-5e70a10bf851
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3BuyingGroupCompanyResult'
        pagination:
          $ref: '#/components/schemas/V3PaginationResponse'
        billing:
          $ref: '#/components/schemas/V3Billing'
    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
        emails:
          type: array
          items:
            type: string
            format: email
          description: Personal data — no catalog.
        previousEmails:
          type: array
          items:
            type: string
            format: email
          description: Personal data — no catalog.
        previousJobTitle:
          type: array
          items:
            type: string
        skills:
          type: array
          items:
            type: string
          example:
            - Python
        certifications:
          type: array
          items:
            type: string
        awards:
          type: array
          items:
            type: string
        ids:
          type: array
          items:
            type: string
          description: Encrypted contact id from a prior search's `results[].id`.
        existingDataPointsCondition:
          type: string
          enum:
            - or
            - and
          description: Pairs with `existingDataPoints`.
        jobChangedAfterDate:
          type: string
          format: date
          description: >-
            Refinement-only — must be paired with a base filter (e.g.
            `jobTitles`).
        jobChangedLastViewDate:
          type: string
          format: date
          description: Refinement-only — must be paired with a base filter.
        education:
          type: object
          description: Refinement-only — must be paired with a base filter.
          properties:
            degrees:
              type: array
              items:
                type: string
            fieldsOfStudy:
              type: array
              items:
                type: string
            schools:
              type: array
              items:
                type: string
            startYearGte:
              type: integer
            graduationYearLte:
              type: integer
        score:
          type: object
          description: >
            Refinement-only — must be paired with a base filter. Raw 0–100
            contact score. Distinct from the `confidence` band ("A+"/"A")
            returned on enriched contacts, which is derived from this score
            (e.g. `A+` when score > 75).
          properties:
            minScore:
              type: integer
              minimum: 0
              maximum: 100
            maxScore:
              type: integer
              minimum: 0
              maximum: 100
        geographicDetails:
          type: array
          items:
            type: object
            properties:
              country:
                type: string
              zipcode:
                type: string
              distance:
                type: integer
                description: Radius in miles.
    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
        intentMinScore:
          type: integer
          minimum: 1
          maximum: 100
        intentMaxScore:
          type: integer
          minimum: 1
          maximum: 100
        intentTopicsOperator:
          type: string
          enum:
            - or
            - and
            - any
            - all
          description: >
            Recommended over `intentTopicsCondition`. `any`/`all` are aliases
            for `or`/`and`. `intentTopicsCondition` is not deprecated and
            remains accepted.
        topicCountThreshold:
          type: array
          items:
            $ref: '#/components/schemas/V3Range'
        sicCodes:
          type: array
          items:
            type: string
        naicsCodes:
          type: array
          items:
            type: string
        funding:
          type: object
          description: >
            All funding sub-filters live under this single object. Every field
            is optional; combine any subset.
          properties:
            isIpo:
              type: boolean
            ranges:
              type: array
              items:
                type: object
                properties:
                  coverage:
                    type: string
                    enum:
                      - last_funding
                      - any_round
                      - total_funds
                      - last_round
                  min:
                    type: integer
                  max:
                    type: integer
            date:
              type: object
              properties:
                coverage:
                  type: string
                  enum:
                    - last_funding
                    - any_round
                    - total_funds
                    - last_round
                date:
                  type: string
                  format: date
            rounds:
              type: array
              items:
                type: object
                properties:
                  coverage:
                    type: string
                    enum:
                      - last_funding
                      - any_round
                      - total_funds
                      - last_round
                  round:
                    type: string
                    enum:
                      - pre_seed
                      - seed
                      - series_a
                      - series_b
                      - series_c
                      - series_d
                      - series_e
                      - series_f
                      - series_g
                      - series_h
                      - other
            names:
              type: array
              items:
                type: object
                properties:
                  coverage:
                    type: string
                    enum:
                      - last_funding
                      - any_round
                      - total_funds
                      - last_round
                  name:
                    type: string
                    enum:
                      - angel
                      - venture
                      - private_equity
                      - crowdfunding
                      - grant
                      - debt_financing
                      - other
            investors:
              type: array
              items:
                type: string
              description: Free text. Accepted but not currently applied downstream.
            types:
              type: array
              items:
                type: string
              description: Legacy free text. Accepted but not currently applied downstream.
        foundedYear:
          type: array
          description: >-
            Filter by year the company was founded. Supports `min` (greater than
            or equal) and `max` (less than or equal) range operators.
          items:
            type: object
            properties:
              min:
                type: integer
                example: 2000
              max:
                type: integer
                example: 2020
        businessModel:
          type: array
          description: 'Filter by business model. Accepted values: B2B, B2C, B2G.'
          items:
            type: string
            enum:
              - B2B
              - B2C
              - B2G
          example:
            - B2B
        companyType:
          type: array
          description: >-
            Filter by company type. Accepted values: Government, Private
            Company, Public Company, Educational, Non Profit, Self Employed.
          items:
            type: string
            enum:
              - Government
              - Private Company
              - Public Company
              - Educational
              - Non Profit
              - Self Employed
          example:
            - Public Company
        linkedinUrls:
          type: array
          description: Filter by company LinkedIn URLs.
          items:
            type: string
          example:
            - https://www.linkedin.com/company/google
        keywords:
          type: array
          description: Filter by keywords associated with the company.
          items:
            type: string
          example:
            - fintech
        specialities:
          type: array
          items:
            type: string
        exactSpecialities:
          type: array
          items:
            type: string
        exactKeywords:
          type: array
          items:
            type: string
        keywordsSearchFields:
          type: array
          items:
            type: string
        previousCompanyDomains:
          type: array
          items:
            type: string
        previousCompanyNames:
          type: array
          items:
            type: string
        geographicDetails:
          type: array
          items:
            type: object
            properties:
              country:
                type: string
              zipcode:
                type: string
              distance:
                type: integer
                description: Radius in miles.
        locationsZipcodes:
          type: array
          items:
            type: object
            properties:
              countryIso2:
                type: string
              zipcode:
                type: string
        headquarterZipcodes:
          type: array
          items:
            type: object
            properties:
              countryIso2:
                type: string
              zipcode:
                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
        intentMinScore:
          type: integer
          minimum: 1
          maximum: 100
        intentMaxScore:
          type: integer
          minimum: 1
          maximum: 100
        intentTopicsOperator:
          type: string
          enum:
            - or
            - and
            - any
            - all
          description: >
            Recommended over `intentTopicsCondition`. `any`/`all` are aliases
            for `or`/`and`. `intentTopicsCondition` is not deprecated and
            remains accepted.
        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
                - linkedinActivityIntent
            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
            filterByIntentCategory:
              type: array
              items:
                type: string
              description: >
                Refines linkedinActivityIntent results by Bombora intent
                category. Applied only when linkedinActivityIntent is present in
                `types` (or selected via allSignals). Omit to match all
                categories. See GET
                /v3/companies/signals/filters/intentCategories for the full list
                of valid values.
              example:
                - Technology
        foundedYear:
          type: array
          description: >-
            Filter by year the company was founded. Supports `min` (greater than
            or equal) and `max` (less than or equal) range operators.
          items:
            type: object
            properties:
              min:
                type: integer
                example: 1990
              max:
                type: integer
                example: 2020
        businessModel:
          type: array
          description: 'Filter by business model. Accepted values: B2B, B2C, B2G.'
          items:
            type: string
            enum:
              - B2B
              - B2C
              - B2G
          example:
            - B2B
            - B2G
        companyType:
          type: array
          description: >-
            Filter by company type. Accepted values: Government, Private
            Company, Public Company, Educational, Non Profit, Self Employed.
          items:
            type: string
            enum:
              - Government
              - Private Company
              - Public Company
              - Educational
              - Non Profit
              - Self Employed
          example:
            - Public Company
            - Private Company
        linkedinUrls:
          type: array
          description: Filter by company LinkedIn URLs.
          items:
            type: string
          example:
            - https://www.linkedin.com/company/microsoft
        keywords:
          type: array
          description: Filter by keywords associated with the company.
          items:
            type: string
          example:
            - cloud
            - artificial intelligence
        specialities:
          type: array
          items:
            type: string
        exactSpecialities:
          type: array
          items:
            type: string
        exactKeywords:
          type: array
          items:
            type: string
        keywordsSearchFields:
          type: array
          items:
            type: string
        previousCompanyDomains:
          type: array
          items:
            type: string
        previousCompanyNames:
          type: array
          items:
            type: string
        geographicDetails:
          type: array
          items:
            type: object
            properties:
              country:
                type: string
              zipcode:
                type: string
              distance:
                type: integer
                description: Radius in miles.
        locationsZipcodes:
          type: array
          items:
            type: object
            properties:
              countryIso2:
                type: string
              zipcode:
                type: string
        headquarterZipcodes:
          type: array
          items:
            type: object
            properties:
              countryIso2:
                type: string
              zipcode:
                type: string
    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
        tableId:
          type: string
          description: >-
            Optional. If provided, these contacts are also added to this table
            (if not already present) and the Signals column is populated. See
            the Tables API.
          example: '482910'
    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
        tableWrite:
          $ref: '#/components/schemas/TableWrite'
        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
              - linkedinActivityIntent
              - 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
          description: >
            For linkedinActivityIntent, results are limited to a trailing 90-day
            window regardless of the value passed (legal requirement). Other
            signal types are unaffected.
          example: '2025-01-01'
        maxResultsPerSignal:
          type: integer
          minimum: 1
          maximum: 100
          description: >
            For linkedinActivityIntent, results are capped at 50 per company
            regardless of the value passed. Other signal types use the requested
            value as-is (1-100).
          example: 10
        tableId:
          type: string
          description: >-
            Optional. If provided, these companies are also added to this table
            (if not already present) and the Signals column is populated. See
            the Tables API.
          example: '583021'
        filters:
          type: object
          properties:
            include:
              type: object
              properties:
                intentCategories:
                  type: array
                  items:
                    type: string
                  description: >
                    Refines linkedinActivityIntent results by Bombora intent
                    category. Only applies when linkedinActivityIntent is
                    requested (via signalTypes or allSignals). See GET
                    /v3/companies/signals/filters/intentCategories for valid
                    values.
                  example:
                    - Technology
                    - Business
    LinkedinActivityIntentTopic:
      type: object
      properties:
        topic:
          type: string
          example: Cloud Security
        category:
          type: string
          example: Technology
    LinkedinActivityIntentPerson:
      type: object
      description: >-
        A person referenced in a LinkedIn activity intent post (author or
        mention).
      properties:
        id:
          type: string
          nullable: true
          description: >-
            Lusha contact ID, or null if the person couldn't be resolved to a
            Lusha record.
          example: '4389064624'
        fullName:
          type: string
          example: Daniel Turgeman
        linkedinUrl:
          type: string
          example: https://www.linkedin.com/in/daniel-turgeman-49676b161
    LinkedinActivityIntentCompanyMention:
      type: object
      description: A company referenced in a LinkedIn activity intent post.
      properties:
        id:
          type: string
          nullable: true
          description: >-
            Lusha company ID, or null if the company couldn't be resolved to a
            Lusha record.
          example: '16303253'
        name:
          type: string
          example: Lusha
        linkedinUrl:
          type: string
          example: https://www.linkedin.com/company/lushadata
    LinkedinActivityIntentItem:
      type: object
      properties:
        companyId:
          type: number
          description: Lusha company ID this activity belongs to.
          example: 16303253
        activityPublicationDate:
          type: string
          format: date
          description: Date the post was published.
          example: '2026-05-12'
        signalCategory:
          type: string
          description: Post classification.
          example: Technology or Stack Discussion
        intentTopics:
          type: array
          description: Detected Bombora topics and their category.
          items:
            $ref: '#/components/schemas/LinkedinActivityIntentTopic'
        author:
          $ref: '#/components/schemas/LinkedinActivityIntentPerson'
        contactsMentioned:
          type: array
          items:
            $ref: '#/components/schemas/LinkedinActivityIntentPerson'
        companiesMentioned:
          type: array
          items:
            $ref: '#/components/schemas/LinkedinActivityIntentCompanyMention'
        activityUrl:
          type: string
          description: URL of the source post.
          example: https://www.linkedin.com/feed/update/urn:li:activity:1234567890
        activitySummary:
          type: string
          nullable: true
          description: AI-generated summary. Never contains the raw post text.
          example: Discusses adopting a new cloud security stack ahead of Q3 rollout.
        activityLikes:
          type: integer
          default: 0
          example: 42
        activityComments:
          type: integer
          default: 0
          example: 5
        activityShares:
          type: integer
          default: 0
          example: 3
        activityType:
          type: string
          example: post
    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
              linkedinActivityIntent:
                type: array
                items:
                  $ref: '#/components/schemas/LinkedinActivityIntentItem'
            additionalProperties:
              type: array
              items:
                type: object
                additionalProperties: true
        startDate:
          type: string
        endDate:
          type: string
        tableWrite:
          $ref: '#/components/schemas/TableWrite'
        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
    V3SignalScoreCompanyItem:
      type: object
      description: Must contain exactly one of id, domain, name, or email.
      properties:
        clientReferenceId:
          type: string
          maxLength: 256
          description: Caller-supplied token echoed back on the matching result.
          example: ref-1
        id:
          type: string
          description: >-
            Encrypted Lusha company ID (vN.…). Legacy numeric IDs accepted
            during the transition window.
          example: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
        domain:
          type: string
          example: www.microsoft.com
        name:
          type: string
          example: Apple
        email:
          type: string
          format: email
          description: >-
            Must be a valid email address; only the domain part is used for
            resolution. A malformed email is rejected with 400.
          example: jane@acme.com
    V3SignalScoreCompaniesRequest:
      type: object
      required:
        - companies
      properties:
        companies:
          type: array
          items:
            $ref: '#/components/schemas/V3SignalScoreCompanyItem'
          minItems: 1
          maxItems: 100
    V3SignalScoreCompanyResult:
      type: object
      description: >-
        A scored entry, or an error entry with NOT_FOUND / NO_SCORE instead of
        the score fields.
      properties:
        clientReferenceId:
          type: string
          example: ref-1
        id:
          type: string
          description: >-
            Encrypted Lusha company ID for scored entries. On NOT_FOUND, echoes
            the supplied domain/name (or the derived domain, for an email
            request).
          example: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
        name:
          type: string
          example: Acme Corp
        domain:
          type: string
          example: www.acmecorp.io
        signalScore:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Aggregate signal score - the fraction of the company's active
            signals. Absent on error entries.
          example: 0.42
        signalTypes:
          type: array
          description: >-
            Signal types currently active for this company (canonical
            camelCase). Absent on error entries.
          items:
            type: string
          example:
            - hiringSignalIncrease
            - websiteVisit
        noActiveSignals:
          type: boolean
          description: >-
            True when the company resolved and scored but has no active signals
            (signalScore is 0). Absent on error entries.
          example: false
        error:
          $ref: '#/components/schemas/V3ItemError'
    V3SignalScoreCompaniesResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          example: 5d6f13d2-f6b0-4e55-85d5-04e17f932c1a
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3SignalScoreCompanyResult'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3SignalScoreContactItem:
      type: object
      description: >
        Must contain id, linkedinUrl, email, or firstName + lastName +
        (companyName | companyDomain).
      properties:
        clientReferenceId:
          type: string
          maxLength: 256
          example: ref-1
        id:
          type: string
          description: Encrypted Lusha contact ID (vN.…).
          example: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
        linkedinUrl:
          type: string
          example: https://linkedin.com/in/johndoe
        email:
          type: string
          format: email
          example: jane.doe@acme.com
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Doe
        companyName:
          type: string
          example: Acme Corp
        companyDomain:
          type: string
          example: acme.com
    V3SignalScoreContactsRequest:
      type: object
      required:
        - contacts
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/V3SignalScoreContactItem'
          minItems: 1
          maxItems: 100
    V3SignalScoreContactCompanyRef:
      type: object
      description: Company the contact was scored at.
      properties:
        id:
          type: string
          example: v1.6789ZyXwVuTsRqPoNmLkJiHgFeDcBa01
        name:
          type: string
          example: Acme Corp
        domain:
          type: string
          example: acme.com
    V3SignalScoreContactResult:
      type: object
      description: >-
        A scored entry, or an error entry with NOT_FOUND / NO_SCORE instead of
        the score fields.
      properties:
        clientReferenceId:
          type: string
          example: ref-1
        id:
          type: string
          description: >-
            Encrypted Lusha contact ID for scored entries. On NOT_FOUND, echoes
            the supplied id, if one was given.
          example: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
        fullName:
          type: string
          example: Jane Doe
        company:
          $ref: '#/components/schemas/V3SignalScoreContactCompanyRef'
        signalScore:
          type: number
          minimum: 0
          maximum: 1
          description: Aggregate signal score. Absent on error entries.
          example: 0.3
        signalTypes:
          type: array
          description: >-
            Signal types currently active for this contact (canonical
            camelCase). Absent on error entries.
          items:
            type: string
          example:
            - promotion
        noActiveSignals:
          type: boolean
          description: >-
            True when the contact resolved and scored but has no active signals
            (signalScore is 0). Absent on error entries.
          example: false
        error:
          $ref: '#/components/schemas/V3ItemError'
    V3SignalScoreContactsResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          example: 5d6f13d2-f6b0-4e55-85d5-04e17f932c1a
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3SignalScoreContactResult'
        billing:
          $ref: '#/components/schemas/V3Billing'
    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
        waterfallEnabled:
          type: boolean
          default: true
          description: >
            Whether this call is allowed to fall through to your enabled

            third-party providers when Lusha's own data has no match, for the
            fields

            requested via `reveal`. Defaults to `true` whenever Data Waterfall
            is

            enabled on your account (Account > Waterfall) - pass `false` to opt
            this

            specific call out. Has no effect if Data Waterfall or no providers
            are

            enabled on your account. Provider order isn't configurable - Lusha
            manages

            that internally.
          example: false
        tableId:
          type: string
          description: >-
            Optional. If provided, these contacts are also added to this table
            (if not already present) and the revealed fields' columns are
            populated. See the Tables API.
          example: '482910'
    V3ContactsEnrichResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3EnrichedContact'
        tableWrite:
          $ref: '#/components/schemas/TableWrite'
        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
              - estimatedAnnualItSpend
              - monthlyWebsiteTraffic
              - openJobsTotal
              - openJobsByDepartment
              - openJobsByLocation
              - openJobsBySeniority
          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

            - `estimatedAnnualItSpend` — estimated annual IT spend.

            - `monthlyWebsiteTraffic` — monthly website traffic and
            month-over-month change.

            - `openJobsTotal` — reveals the total open job count. In the
            response, this appears as the `total` field inside the `openJobs`
            object.

            - `openJobsByDepartment` — reveals open job counts broken down by
            department. In the response, this appears as the `byDepartment`
            field inside the `openJobs` object.

            - `openJobsByLocation` — reveals open job counts broken down by
            location. In the response, this appears as the `byLocation` field
            inside the `openJobs` object.

            - `openJobsBySeniority` — reveals open job counts broken down by
            seniority level. In the response, this appears as the `bySeniority`
            field inside the `openJobs` object.
          example:
            - employeesByDepartment
            - employeesByLocation
            - employeesBySeniority
            - competitors
            - intent
            - estimatedAnnualItSpend
            - monthlyWebsiteTraffic
            - openJobsTotal
            - openJobsByDepartment
            - openJobsByLocation
            - openJobsBySeniority
        tableId:
          type: string
          description: >-
            Optional. If provided, these companies are also added to this table
            (if not already present) and the revealed fields' columns are
            populated. See the Tables API.
          example: '583021'
    V3CompaniesEnrichResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3EnrichedCompany'
        tableWrite:
          $ref: '#/components/schemas/TableWrite'
        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'
        tableId:
          type: string
          description: >-
            Optional. If provided, results are also persisted to this table. See
            the Tables API.
          example: '482910'
        options:
          type: object
          properties:
            includePartialProfiles:
              type: boolean
              default: true
            excludeDnc:
              type: boolean
            maxContactsPerCompany:
              type: integer
              minimum: 1
              maximum: 20
              description: >
                Caps how many contacts are returned per company — not the page
                size. `pagination.size` still controls the page size. Accepts
                1–20; omit for uncapped results.
              example: 2
    V3ProspectingContactsResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/V3ContactPreview'
        pagination:
          $ref: '#/components/schemas/V3ProspectingContactsPagination'
        tableWrite:
          $ref: '#/components/schemas/TableWrite'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3ProspectingCompaniesRequest:
      type: object
      required:
        - pagination
        - filters
      properties:
        pagination:
          $ref: '#/components/schemas/V3PaginationRequest'
        filters:
          type: object
          required:
            - companies
          description: >
            `filters.contacts` cannot be combined with company `searchText`,
            `signals`, `intent`, or `technologies` on the same request — doing
            so returns `400` (contact filters are never silently ignored).
          properties:
            companies:
              type: object
              required:
                - include
              properties:
                include:
                  $ref: '#/components/schemas/V3CompanyProspectingFilters'
                exclude:
                  $ref: '#/components/schemas/V3CompanyProspectingFilters'
            contacts:
              type: object
              properties:
                include:
                  $ref: '#/components/schemas/V3ContactsOnCompanySearchFilters'
                exclude:
                  $ref: '#/components/schemas/V3ContactsOnCompanySearchFilters'
        tableId:
          type: string
          description: >-
            Optional. If provided, results are also persisted to this table. See
            the Tables API.
          example: '583021'
        options:
          type: object
          properties:
            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'
        tableWrite:
          $ref: '#/components/schemas/TableWrite'
        billing:
          $ref: '#/components/schemas/V3Billing'
    V3ContactsOnCompanySearchFilters:
      type: object
      description: >-
        Restricted contact-attribute filters usable within a company prospecting
        request.
      properties:
        jobTitles:
          type: array
          items:
            type: string
        departments:
          type: array
          items:
            type: string
        seniorityIds:
          type: array
          items:
            type: integer
        skills:
          type: array
          items:
            type: string
        locations:
          type: array
          items:
            $ref: '#/components/schemas/V3Location'
        existingDataPoints:
          type: array
          items:
            type: string
    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
          nullable: true
          description: >-
            Renewal/end date. Omitted (null) for free accounts, since they have
            no renewal cycle.
          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
        - size
        - page
        - 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'
    V3ConversationsSearchRequest:
      type: object
      description: >
        All properties are optional. Supply `query` for keyword mode (structural
        filters are then ignored), or omit `query` and supply structural filters
        for filter mode. An empty body returns the first page of the account's
        conversations.
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 500
          description: >-
            Free-text search over transcript content. When present, the
            structural filters below are ignored.
          example: pricing objection
        conversationIds:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: >-
            Return only these conversations. IDs that don't exist, are still
            processing, or belong to another account are omitted from the
            response rather than erroring.
        dateFrom:
          type: string
          format: date
          description: Earliest meeting date, inclusive (YYYY-MM-DD).
          example: '2026-01-01'
        dateTo:
          type: string
          format: date
          description: Latest meeting date, inclusive (YYYY-MM-DD).
          example: '2026-03-31'
        contactNames:
          type: array
          items:
            type: string
          description: >-
            Partial, case-insensitive match on participant names. Multiple
            values are ORed.
          example:
            - Jane Doe
        companyDomains:
          type: array
          items:
            type: string
          description: >-
            Company domains of the external participants (e.g. acme.com).
            Matches on domain, not display name. Multiple values are ORed.
          example:
            - acme.com
        meetingTitles:
          type: array
          items:
            type: string
          description: >-
            Partial, case-insensitive match on the meeting title. Multiple
            values are ORed.
          example:
            - Quarterly review
        page:
          type: integer
          minimum: 1
          default: 1
          description: Page number, starting at 1.
          example: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
          description: >-
            Conversations per page. Values above 100 are rejected with 400 (not
            silently clamped).
          example: 25
    ConversationActionItem:
      type: object
      properties:
        text:
          type: string
          example: Send the revised pricing sheet
        owner:
          type: string
          example: Sam Rep
        dueDate:
          type: string
          format: date
          nullable: true
          description: May be null.
          example: '2026-03-19'
    ConversationSeverityItem:
      type: object
      properties:
        text:
          type: string
          example: Budget approval is still pending
        severity:
          type: string
          nullable: true
          description: >-
            Null means the pipeline did not assess severity. Do not read it as
            "low".
          example: high
    ConversationCompetitor:
      type: object
      properties:
        name:
          type: string
          example: Competitor Inc
        context:
          type: string
          example: Mentioned as incumbent
        sentiment:
          type: string
          nullable: true
          description: May be null.
          example: negative
    ConversationSummary:
      type: object
      nullable: true
      description: Post-call analysis, or null while it is still being produced.
      properties:
        text:
          type: string
          description: Narrative summary.
          example: The team walked through the pricing tiers.
        keyHighlights:
          type: array
          items:
            type: string
          description: Notable moments.
          example:
            - Budget confirmed for Q3
        actionItems:
          type: array
          items:
            $ref: '#/components/schemas/ConversationActionItem'
        nextSteps:
          type: array
          items:
            type: string
          example:
            - Schedule a technical deep dive
        risks:
          type: array
          items:
            $ref: '#/components/schemas/ConversationSeverityItem'
        objections:
          type: array
          items:
            $ref: '#/components/schemas/ConversationSeverityItem'
        competition:
          type: array
          items:
            $ref: '#/components/schemas/ConversationCompetitor'
    ConversationCoachingSection:
      type: object
      properties:
        section:
          type: string
          example: discovery
        score:
          type: number
          nullable: true
          description: May be null.
          example: 72
        whatHappened:
          type: string
          example: The rep opened with a clear agenda.
        whatToKeep:
          type: array
          items:
            type: string
          example:
            - Strong discovery questions
        whatToImprove:
          type: array
          items:
            type: string
          example:
            - Confirm the decision process earlier
    ConversationCoaching:
      type: object
      nullable: true
      description: Coaching analysis, or null while it is still being produced.
      properties:
        overallScore:
          type: number
          description: Overall coaching score, 0–100.
          example: 68
        likelihoodOfSale:
          type: number
          nullable: true
          description: Predicted likelihood of closing, 0–100. May be null.
          example: 45
        sections:
          type: array
          items:
            $ref: '#/components/schemas/ConversationCoachingSection'
        notes:
          type: string
          description: Free-text coaching notes.
          example: Focus on quantifying impact.
    ConversationChapter:
      type: object
      properties:
        index:
          type: integer
          example: 0
        title:
          type: string
          example: Introductions
        startTime:
          type: string
          description: Offset from the start of the recording.
          example: '00:00:00'
        endTime:
          type: string
          description: Offset from the start of the recording.
          example: '00:04:12'
        summary:
          type: string
          example: Participants introduced themselves.
    ConversationParticipant:
      type: object
      properties:
        name:
          type: string
          example: Jane Doe
        email:
          type: string
          example: jane@acme.com
        role:
          type: string
          example: VP Sales
        isInternal:
          type: boolean
          example: false
    ConversationCompany:
      type: object
      description: External participants' company. Either field may be null.
      properties:
        name:
          type: string
          nullable: true
          example: Acme Inc
        domain:
          type: string
          nullable: true
          example: acme.com
    Conversation:
      type: object
      properties:
        id:
          type: string
          description: Conversation identifier. Pass this to Get Conversation Transcript.
          example: 8f2c9b1e-4a7d-4f3b-9c2e-1d6a5b8c7e90
        title:
          type: string
          description: Meeting title.
          example: Acme <> Lusha - Quarterly review
        date:
          type: string
          format: date
          description: Meeting date (YYYY-MM-DD).
          example: '2026-03-12'
        startTime:
          type: string
          format: date-time
          description: Meeting start time (ISO 8601).
          example: '2026-03-12T14:00:00Z'
        durationSeconds:
          type: number
          description: Meeting length in seconds.
          example: 1830
        durationFormatted:
          type: string
          description: Human readable length, e.g. 30m 30s.
          example: 30m 30s
        meetingType:
          type: string
          nullable: true
          description: Meeting type as classified by the analysis pipeline.
          example: discovery
        isExternal:
          type: boolean
          nullable: true
          description: true when at least one participant is outside your account.
          example: true
        company:
          $ref: '#/components/schemas/ConversationCompany'
        participants:
          type: array
          items:
            $ref: '#/components/schemas/ConversationParticipant'
        topicLabels:
          type: array
          items:
            type: string
          description: Topics detected in the conversation.
          example:
            - pricing
            - security
        summary:
          $ref: '#/components/schemas/ConversationSummary'
        coaching:
          $ref: '#/components/schemas/ConversationCoaching'
        chapters:
          type: array
          description: Timestamped chapters. Empty until the analysis pipeline has run.
          items:
            $ref: '#/components/schemas/ConversationChapter'
    ConversationPage:
      type: object
      description: Paging envelope for Search Conversations.
      properties:
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 25
        totalItems:
          type: integer
          example: 137
        totalPages:
          type: integer
          example: 6
    V3ConversationsSearchResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          description: Correlation / request id for support and tracing.
          example: 3f1a9c2e-7b4d-4a8e-9f10-2c5d6e7a8b90
        conversations:
          type: array
          description: >-
            Matching conversations. In keyword mode they are ordered by content
            relevance.
          items:
            $ref: '#/components/schemas/Conversation'
        page:
          $ref: '#/components/schemas/ConversationPage'
        billing:
          $ref: '#/components/schemas/V3Billing'
    ConversationTranscriptSegment:
      type: object
      properties:
        speaker:
          type: string
          description: Speaker name as resolved by the meeting provider.
          example: Jane Doe
        side:
          type: string
          nullable: true
          description: >-
            Which side of the conversation the speaker is on, e.g. internal /
            external.
          example: external
        text:
          type: string
          description: What was said.
          example: We need to understand the pricing tiers before we commit.
        startTime:
          type: string
          description: Offset from the start of the recording.
          example: '00:12:04'
        endTime:
          type: string
          description: Offset from the start of the recording.
          example: '00:12:19'
    V3ConversationTranscriptResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          description: Correlation / request id for support and tracing.
          example: 3f1a9c2e-7b4d-4a8e-9f10-2c5d6e7a8b90
        conversationId:
          type: string
          description: The conversation this transcript belongs to.
          example: 8f2c9b1e-4a7d-4f3b-9c2e-1d6a5b8c7e90
        segments:
          type: array
          description: Chronologically ordered segments.
          items:
            $ref: '#/components/schemas/ConversationTranscriptSegment'
        billing:
          $ref: '#/components/schemas/V3Billing'
