# Add Entities to Contacts Table

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.

Endpoint: POST /v3/contacts/tables/{table_id}/entities
Security: ApiKeyAuth

## Path parameters:

  - `table_id` (string, required)
    The table's ID.
    Example: "482910"

## Request fields (application/json):

  - `entityIds` (array, 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.
    Example: ["10042854","10042855","10042856"]

  - `companyIds` (array)
    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` (object, 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.

  - `owner.email` (string)
    Must resolve to an existing user on the account tied to your API key.
    Example: "user@example.com"

## Response 200 fields (application/json):

  - `data` (object)

  - `data.added` (integer)
    Example: 20

  - `data.alreadyPresent` (integer)
    Example: 5

  - `data.invalidIds` (array)
    IDs that couldn't be resolved. Not an error — the call still returns 200.
    Example: []

  - `data.addedBy` (object)
    Where and by whom a row was added to the table.

  - `data.addedBy.surface` (string)
    Enum: "api", "mcp", "workspace"

  - `billing` (object)
    Credit usage summary for a V3 API request

  - `billing.creditsCharged` (integer)
    Total credits charged for this request
    Example: 3

  - `billing.resultsReturned` (integer)
    Number of successful results returned
    Example: 1

## Response 400 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]