---
title: "Enrich Contacts"
method: POST
path: "/v3/contacts/enrich"
tags: ["Enrich"]
---

# Enrich Contacts

`POST /v3/contacts/enrich`

Reveal full contact data for contacts you've already found via Search Contacts.

Pass up to 100 contact `ids` (from the search response). Use the `reveal` field to control what gets unlocked:
- `emails` — work and personal email addresses
- `phones` — mobile and direct phone numbers
- Omit `reveal` to get both by default

---

###  Waterfall Reveal
Fall through to your enabled third-party providers when Lusha's own data has no match, for extra reach on hard-to-match contacts.

If **Data Waterfall** is enabled on your account, with specific providers turned on under **Account > Waterfall**, the waterfall runs automatically on every Enrich Contacts call - you don't need to pass anything to trigger it.


Pass `waterfallEnabled: false` to opt a specific call out:

  ```json
                  "reveal": ["emails", "phones"],
                  "waterfallEnabled": false
  ```

- `reveal` controls **which fields** come back.
- `waterfallEnabled` controls whether the waterfall runs for this call at all. Defaults to `true` whenever Data Waterfall is enabled on your account; pass `false` to disable it just for this call.
- Provider order isn't configurable - Lusha manages that internally.
- If Data Waterfall is off or no providers are enabled on your account, `waterfallEnabled` has no effect either way.
---
> **Tip:** If `canReveal.credits` is `0` in the search response, that data has already been revealed for your account — re-enriching it is free.

> **Billing:** Charged per revealed field (email or phone) via per-datapoint pricing.

> **Persisting to a table:** Pass `tableId` to also add these contacts to an existing table and populate the Work email / Phone columns. See [Contacts Tables](#tag/Contacts-Tables).

## Request body

- V3ContactsEnrichRequest
  - `ids` string[], required
  - `reveal` string[]
  - `waterfallEnabled` boolean — Whether this call is allowed to fall through to your enabled third-party providers when Lusha's own data has no match, for the fields requested via `reveal`. Defaults to `true` whenever Data Waterfall is enabled on your account (Account > Waterfall) - pass `false` to opt this specific call out. Has no effect if Data Waterfall or no providers are enabled on your account. Provider order isn't configurable - Lusha manages that internally.
  - `tableId` string — Optional. If provided, these contacts are also added to this table (if not already present) and the revealed fields' columns are populated. See the Tables API.

## Response `200`

Successful response

- V3ContactsEnrichResponse
  - `requestId` string, uuid
  - `results` V3EnrichedContact[]
    - `id` string
    - `firstName` string
    - `lastName` string
    - `fullName` string
    - `jobTitle` object
      - `title` string
      - `departments` string[]
      - `seniority` string
    - `location` object
      - `country` string
      - `countryIso2` string
      - `state` string
      - `city` string
      - `continent` string
      - `coordinates` number[]
      - `isEuContact` boolean
    - `tags` V3ContactTag[]
      - `id` string
      - `name` string
      - `color` string
    - `emails` V3EmailAddress[]
      - `email` string, email
      - `type` 'work' | 'private' | 'unknown'
      - `confidence` string, nullable
      - `updateDate` string, date
    - `phones` V3PhoneNumber[]
      - `number` string
      - `type` 'mobile' | 'direct' | 'work' | 'unknown'
      - `doNotCall` boolean
      - `updateDate` string, date
    - `company` V3EnrichedContactCompanyRef
      - `id` string
      - `name` string
      - `domain` string
      - `industry` string
    - `socialLinks` object
      - `linkedin` string
      - `xUrl` string
    - `previousEmployment` object[]
      - `company` object
        - `name` string
        - `domain` string
      - `jobTitle` object
        - `title` string
        - `departments` string[]
        - `seniority` string
    - `updateDate` string, date
    - `error` V3ItemError — Per-item error in a batch response
      - `code` 'NOT_FOUND' | 'COMPLIANCE_RESTRICTED' | 'ENRICH_FAILED' | 'NO_SCORE'
      - `message` string
  - `tableWrite` TableWrite — Added to a Prospecting, Enrich, Signals, or Lookalike response when `tableId` is passed on the request. The primary response is unaffected even if the table write fails.
    - `tableId` string
    - `added` integer — Number of new entities added to the table by this call.
    - `alreadyPresent` integer — Number of entities from this call that were already in the table.
    - `columnsCreated` integer — Number of columns auto-created by this call (e.g. a Signals column created on first use).
    - `rowsProcessed` integer — Number of rows the column-run touched as part of this call.
    - `rowsCharged` integer — Number of those rows that incurred a credit charge.
    - `rowsAlreadyPaidInTable` integer — Number of those rows that were already paid for in this table and were not re-charged.
    - `creditsCharged` integer — Credits charged specifically for this table write.
  - `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
- `402` — Payment required - insufficient credits
- `403` — Forbidden - account inactive, V3 access not enabled, or plan does not include this feature
- `429` — Too many requests - rate limit exceeded

---

[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/revisions/d37bb08edd61/schema)