---
title: "Add Entities to Contacts Table"
method: POST
path: "/v3/contacts/tables/{table_id}/entities"
tags: ["Contacts Tables"]
---

# Add Entities to Contacts Table

`POST /v3/contacts/tables/{table_id}/entities`

Add up to 500 contact 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 `personId` — 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`.

Optionally pass `companyIds` — one `lushaCompanyId` per contact, index-aligned with `entityIds` — to help pair company-level enrichment to the right company for each contact.

> **Billing:** Free.

## Path parameters

- `table_id` string, required

## Request body

- EntitiesAddRequest
  - `entityIds` string[], required — 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`.
  - `companyIds` string[] — 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.
  - `owner` TableOwner, required — 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.
    - `email` string, email — Must resolve to an existing user on the account tied to your API key.

## Response `200`

Entities added

- EntitiesAddResponse
  - `data` object
    - `added` integer
    - `alreadyPresent` integer
    - `invalidIds` string[] — IDs that couldn't be resolved. Not an error — the call still returns `200`.
    - `addedBy` AddedBy — Where and by whom a row was added to the table.
      - `surface` 'api' | 'mcp' | 'workspace'
  - `billing` V3Billing — Credit usage summary for a V3 API request
    - `creditsCharged` integer — Total credits charged for this request
    - `resultsReturned` integer — Number of successful results returned

## Other responses

- `400` — Bad request - invalid input data
- `401` — Unauthorized - invalid or missing API key
- `403` — Forbidden - account inactive, V3 access not enabled, or plan does not include this feature
- `404` — Not found - table does not exist or is not accessible to this account

---

[API](https://skmtc.net/lusha/apis/lusha-api-documentation.md) · [All operations](https://skmtc.net/lusha/apis/lusha-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lusha/lusha-api-documentation/versions/4c51e40e3e67/schema)