Lusha

Lusha Companies Tables API

The company-side twin of Contacts Tables — persist and enrich company working sets in tables with dynamic columns, capped at 50,000 entities per table and 500 tables per account.

GitHub OpenAPI

Operations 11

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /v3/companies/tables Create a companies table · Create Companies Table #
Ask an LLM
“How do I start a new account list table in Lusha?”
“Can I seed a new companies table with company IDs when I create it?”
Tell an agent
Create a companies table named {name} owned by {owner}.
Create a companies table called {name} for {owner} seeded with companies {ids}.
POST /v3/companies/tables/list List companies tables · List Companies Tables #
Ask an LLM
“Which companies tables do I own or have shared with me?”
“Can I find an account list table by its name?”
Tell an agent
List the companies tables owned by {owner}.
Find companies tables for {owner} whose name matches {name}.
GET /v3/companies/tables/{table_id} Get a companies table and its status · Get Companies Table #
Ask an LLM
“Is my companies table still processing?”
“What metadata does a single account table have?”
Tell an agent
Show the details of companies table {table_id}.
Check whether companies table {table_id} has finished processing.
PATCH /v3/companies/tables/{table_id} Rename, archive or reassign a companies table · Update Companies Table #
Ask an LLM
“How do I rename a companies table?”
“Can I archive an account table or change who owns it?”
Tell an agent
Rename companies table {table_id} to {name} as owner {owner}.
Archive companies table {table_id}, owned by {owner}.
DELETE /v3/companies/tables/{table_id} Delete a companies table · Delete Companies Table #
Ask an LLM
“How do I permanently delete a companies table?”
“Can a deleted account table be recovered?”
Tell an agent destructive · confirm first
Delete companies table {table_id} and all its data.
Permanently remove companies table {table_id} on behalf of {email}.
GET /v3/companies/tables/{table_id}/entities Read the rows of a companies table · Get Companies Table Entities #
Ask an LLM
“How do I export the rows and column values from a companies table?”
“Am I charged for reading rows out of an account table?”
Tell an agent
Show the rows in companies table {table_id}.
Get page {page} of rows from companies table {table_id}, {size} per page.
POST /v3/companies/tables/{table_id}/entities Add companies to a table · Add Entities to Companies Table #
Ask an LLM
“How do I add more companies to an existing table?”
“How many company IDs can I add to a table in one call?”
Tell an agent
Add companies {entityIds} to companies table {table_id} as owner {owner}.
Put these accounts into table {table_id}: {entityIds}, owner {owner}.
DELETE /v3/companies/tables/{table_id}/entities Remove companies from a table · Remove Entities from Companies Table #
Ask an LLM
“How do I take specific companies out of a table without deleting the table?”
“Can I remove several account rows from a table at once?”
Tell an agent destructive · confirm first
Remove companies {entityIds} from companies table {table_id} as owner {owner}.
Drop these account rows from table {table_id}: {entityIds}, owner {owner}.
GET /v3/companies/tables/{table_id}/columns List the columns on a companies table · List Companies Table Columns #
Ask an LLM
“What columns does my companies table have?”
“How many cells in each account table column are done or failed?”
Tell an agent
List the columns on companies table {table_id}.
Show column types and cell status counts for companies table {table_id}.
DELETE /v3/companies/tables/{table_id}/columns/{column_id} Remove a column from a companies table · Remove Column from Companies Table #
Ask an LLM
“How do I delete a column and its data from a companies table?”
“Can I remove the default Lusha columns from an account table?”
Tell an agent destructive · confirm first
Remove column {column_id} from companies table {table_id}.
Delete column {column_id} and all its cell data in companies table {table_id}.
POST /v3/companies/tables/{table_id}/columns/{column_id}/run Populate or refresh a companies table column · Run Column on Companies Table #
Ask an LLM
“How do I fill in a column's data for every row of a companies table?”
“Can I refresh an account table column for just a few rows?”
Tell an agent
Run column {column_id} on companies table {table_id} with scope {runScope} as owner {owner}.
Refresh column {column_id} in companies table {table_id} for rows {entityIds}, scope {runScope}, owner {owner}.

Documentation

📖
Documentation
https://docs.lusha.com/apis/openapi/companies-tables

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/lusha/refs/heads/main/openapi/lusha-companies-tables-api-openapi.yml

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/lusha/refs/heads/main/overlays/lusha-companies-tables-overlay.yaml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/lusha:lusha-companies-tables-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

lusha-companies-tables-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Lusha API Documentation Companies Tables API
  version: ''
  x-logo:
    url: https://www.lusha.com/logo.png
  license:
    name: Proprietary
    url: https://lusha.com/legal/terms
  description: '**This is the Lusha API V3 documentation.**


    V3 introduces a new search-then-enrich pattern, bulk operations, AI-powered lookalikes, and richer filter capabilities.'
  contact:
    name: Lusha Support
    url: https://api.lusha.com
    email: support@lusha.com
  termsOfService: https://lusha.com/legal/terms
  x-privacy-policy:
    name: Privacy Policy
    url: https://lusha.com/legal/privacy-notice/
servers:
- url: https://api.lusha.com
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Companies Tables
  description: '**Companies Tables API:** Create and manage persistent tables of companies inside Lusha.'
  x-tag-expanded: true
paths:
  /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'
components:
  schemas:
    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'
    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`.

        '
    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'
    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'
    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
    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'
    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'
    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'
    TableResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TableStatusData'
        billing:
          $ref: '#/components/schemas/V3Billing'
    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'
    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'
    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
    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'
    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
    V3PaginationResponse:
      type: object
      properties:
        page:
          type: integer
          example: 0
        size:
          type: integer
          example: 25
        total:
          type: integer
    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
    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'
    EntitiesGetResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TableEntity'
        pagination:
          $ref: '#/components/schemas/V3PaginationResponse'
        billing:
          $ref: '#/components/schemas/V3Billing'
    TableListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TableMetadata'
        pagination:
          $ref: '#/components/schemas/V3PaginationResponse'
        billing:
          $ref: '#/components/schemas/V3Billing'
    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.'
    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:
          description: The cell's data. Shape depends on the column type.
          example: Google
        status:
          $ref: '#/components/schemas/CellStatus'
    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.

        '
    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
    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'
    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
    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
          - 'null'
          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
  parameters:
    TableIdPath:
      name: table_id
      in: path
      required: true
      description: The table's ID.
      schema:
        type: string
      example: '482910'
    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
    ColumnIdPath:
      name: column_id
      in: path
      required: true
      description: The column's ID.
      schema:
        type: string
      example: col_signals_funding
  responses:
    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'
    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
    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'
    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'
  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.

        '
x-provenance:
  method: harvested
  publisher: Lusha
  source: https://docs.lusha.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)