Tables API

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.

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
Run columns — list available columns, 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:

Table type	Tag in API docs	What it stores
Contacts Tables	`Contacts Tables`	Individual contacts with enrichment, Signals, and contact-level data
Companies Tables	`Companies Tables`	Company records with firmographics, tech stack, Signals, and company-level data

Both types support the same table, entity, and column operations.

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

💡 Note: OAuth and token-based callers are already identified by their token, so owner.email is optional for those authentication methods.

Limits

Limit	Value
Entities per add/remove call	Up to 500
Entities per table	Max 50,000
Tables per account	Max 500
Page range	0–100
Default page size	100

Credit usage

Adding contacts or companies to a table is free. Credits are only used when you trigger enrichment or data columns to run across a table's rows.

Error codes

Tables API errors use a different response shape than other Lusha API endpoints:

{ "message": "...", "code": <status> }

Common Tables-specific error codes:

Code	Status	Meaning
`TABLE_NOT_FOUND`	404	The `table_id` doesn't exist or isn't accessible to this account
`COLUMN_NOT_FOUND`	404	The `column_id` doesn't exist on the given table
`TABLE_NAME_CONFLICT`	409	A table with this name already exists

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: