> ## 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. # Add Columns to Companies Table > Add up to 10 Lusha columns to a table in one call. Enrichment starts automatically on **all rows** in the table as soon as the columns are added. **Body** - either a list or a single key: - `columns: [{ "columnKey": "industry" }, { "columnKey": "yearFounded" }]` - `columnKey: "industry"` for a single column Keys come straight from [Get Companies Column Catalog](#operation/getCompaniesColumnCatalog). **Partial success:** columns are handled independently. The response returns one entry per requested column with its own `status` (`added` / `failed`) and `columnId` - if one column fails the rest still go through. The most common failure is the column already being on the table, in which case the existing `columnId` is returned, so the call is safe to re-run. > **Billing:** Free today - credits aren't charged for adding columns yet. ## OpenAPI ````yaml /openapi.json post /v3/companies/tables/{table_id}/columns 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: >
**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).
--- 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 |
**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).
--- ## 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": , ... }` 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. ---
Rate Limits | Operation | Limit | |-----------|-------| | API Requests | 100 requests/minute per account | | Create Subscriptions | 25 items per request | | Delete Subscriptions | 25 items per request |
---
Security & Verification **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.
---
Credits & Billing **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
---
Error Response Format 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) |
--- 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/companies/tables/{table_id}/columns: post: tags: - Companies Tables summary: Add Columns to Companies Table description: > Add up to 10 Lusha columns to a table in one call. Enrichment starts automatically on **all rows** in the table as soon as the columns are added. **Body** - either a list or a single key: - `columns: [{ "columnKey": "industry" }, { "columnKey": "yearFounded" }]` - `columnKey: "industry"` for a single column Keys come straight from [Get Companies Column Catalog](#operation/getCompaniesColumnCatalog). **Partial success:** columns are handled independently. The response returns one entry per requested column with its own `status` (`added` / `failed`) and `columnId` - if one column fails the rest still go through. The most common failure is the column already being on the table, in which case the existing `columnId` is returned, so the call is safe to re-run. > **Billing:** Free today - credits aren't charged for adding columns yet. operationId: addCompaniesTableColumns parameters: - $ref: '#/components/parameters/TableIdPath' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ColumnsAddRequest' examples: multipleColumns: summary: Add several columns at once value: columns: - columnKey: industry - columnKey: yearFounded - columnKey: employeesByDepartment owner: email: user@example.com singleColumn: summary: Add a single column value: columnKey: industry owner: email: user@example.com responses: '200': description: > Columns processed. Returns one entry per requested column - check each entry's `status`, as some may have failed while others succeeded. content: application/json: schema: $ref: '#/components/schemas/ColumnsAddResponse' example: data: - columnKey: industry columnId: c_31aa90 status: added - columnKey: yearFounded columnId: c_77b201 status: added - columnKey: employeesByDepartment columnId: c_0ce4d3 status: failed error: code: COLUMN_ALREADY_EXISTS message: Column already exists on this table billing: creditsCharged: 0 resultsReturned: 2 '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: ColumnsAddRequest: type: object description: > Supply either `columns` (up to 10 entries) or a single `columnKey` - not both. Sending neither returns `400`. properties: columns: type: array minItems: 1 maxItems: 10 description: Up to 10 Lusha columns to add in one call. items: $ref: '#/components/schemas/ColumnsAddItem' columnKey: type: string description: Shorthand for adding exactly one column. example: jobTitle owner: $ref: '#/components/schemas/TableOwner' oneOf: - required: - columns - required: - columnKey ColumnsAddResponse: type: object description: > One entry per requested column. Enrichment runs asynchronously on every row in the table for each successfully added column - poll Get Table for `isProcessing` and per-column row-status counts, then read the values via Get Table Entities. properties: data: type: array items: $ref: '#/components/schemas/ColumnsAddResultItem' billing: $ref: '#/components/schemas/V3Billing' ColumnsAddItem: type: object required: - columnKey properties: columnKey: type: string description: A `columnKey` from the column catalog endpoint. example: jobTitle 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 ColumnsAddResultItem: type: object description: > Outcome for a single requested column. Columns are processed independently - a `failed` entry does not prevent the others from being added. properties: columnKey: type: string example: jobTitle columnId: type: string description: > ID of the column on this table. Present on `added`, and also on a `COLUMN_ALREADY_EXISTS` failure - in that case it's the ID of the column that was already there, so the request can simply be re-run. example: c_9f2a1b status: type: string enum: - added - failed example: added error: $ref: '#/components/schemas/ColumnsAddItemError' 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' ColumnsAddItemError: type: object description: Present only when `status` is `failed`. properties: code: type: string enum: - COLUMN_ALREADY_EXISTS - COLUMN_KEY_NOT_FOUND - COLUMN_LIMIT_EXCEEDED - UNKNOWN_ERROR description: > `COLUMN_ALREADY_EXISTS` is the most common - the column is already on the table, and the existing `columnId` is returned alongside it. example: COLUMN_ALREADY_EXISTS message: type: string example: Column already exists on this table 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. ````