Skip to main content
The Lusha Tables API lets you create and manage persistent tables of contacts and companies directly from your own systems. If you use the Lusha Workspace UI, MCP server, or any other Lusha surface - they all read and write the same underlying data, so changes made through the API are reflected everywhere.
The Tables API is currently in Beta.

​
What the Tables API does

Tables are structured, configurable sets of contacts or companies. Through the API you can:
  • Create and manage tables - create, list, rename, archive, change visibility, or delete tables
  • Manage entities - add or remove contacts or companies (rows) from a table, or read the full list
  • Manage columns - list available columns, add new columns to a table, remove columns, or trigger a column to populate across all rows in a table
  • Persist search results automatically - pass a tableId on Prospecting, Enrich, Signals, or Lookalike calls to save those results into a table without a separate step

​
Contacts Tables vs. Companies Tables

There are two separate table types, each with its own set of endpoints: Both types support the same table, entity, and column operations.
Use the Add columns endpoint to add new columns to an existing table, in addition to listing, removing, or running columns.

​
Authentication and ownership

All Tables API calls require a valid API key passed as an api_key header. Every call must also include an owner.email value - the email of a user on your Lusha account - to identify who owns the table. This is required when authenticating with an API key.
  • For POST and PATCH calls: pass owner as a body field - { "owner": { "email": "you@company.com" } }
  • For GET and DELETE calls (no body): pass ?email=you@company.com as a query parameter
OAuth and token-based callers are already identified by their token, so owner.email is optional for those authentication methods.

​
Limits

​
Credit usage

  • Adding contacts to a table is free.
  • Adding companies to a table is charged per newly-added company (deduped by row-count delta - duplicates and companies already in the table aren’t charged again).
  • Reading rows (GET .../entities) is charged per row returned.
  • Creating, listing, updating, and deleting tables is free, as is listing, adding, and removing columns.
  • Running a column is charged per row, per that column’s credit tier - company-enrichment columns charge once per company per table, so re-running an already-paid company is free.

​
Error codes

Tables API errors use a different response shape than other Lusha API endpoints:
Common Tables-specific error codes: For the full list of Lusha API error codes, see the Error Codes Reference.

​
Where to find the full reference

The complete endpoint reference - including request/response schemas and example calls - is in the API docs: