> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusha.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Contacts Table

> Rename a table, change its visibility, or reassign its owner. All fields except `owner` are optional - send only what changes.

> **Billing:** Free.




## OpenAPI

````yaml /openapi.json patch /v3/contacts/tables/{table_id}
openapi: 3.0.3
info:
  title: Lusha API Documentation
  version: 0.0.1
  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/).


    ---


    ## Legal Notices


    (a) Data brokers and other third-party platforms may not embed, expose, or
    otherwise provide access to the Lusha API, or to Data obtained through it,
    on or through their own website, product, or service, without Lusha's prior
    written consent.


    (b) Data obtained through the API may not be used to train or develop AI/ML
    systems, subject to the terms and exceptions outlined in the [Terms and
    Conditions](https://lusha.com/legal/terms).


    ---


    ## 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. Premium data points are
      never returned unless you request them explicitly in `reveal`.


      > **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** - browse the Lusha column catalog, add 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 / Column Catalog / Add Columns /
      List Columns / Remove Column / Remove Entities are free. (Add Columns is
      free today - credits aren't charged for it yet.)

      - 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** - browse the Lusha column catalog, add 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 / Column Catalog / Add Columns /
      List Columns / Remove Column / Remove Entities are free. (Add Columns is
      free today - credits aren't charged for it yet.)

      - 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/tables/{table_id}:
    patch:
      tags:
        - Contacts Tables
      summary: Update Contacts Table
      description: >
        Rename a table, change its visibility, or reassign its owner. All fields
        except `owner` are optional - send only what changes.


        > **Billing:** Free.
      operationId: updateContactsTable
      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'
components:
  parameters:
    TableIdPath:
      name: table_id
      in: path
      required: true
      description: The table's ID.
      schema:
        type: string
      example: '482910'
  schemas:
    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'
    TableResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TableStatusData'
        billing:
          $ref: '#/components/schemas/V3Billing'
    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
    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'
    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
    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'
    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
    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
    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
    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
  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
    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
    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'
  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.

````