> ## Documentation Index
> Fetch the complete documentation index at: https://testdocs.clodura.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reveal and Unlock a Contact's Email Address via API

> Look up and unlock a verified email address for any contact in Clodura's database using a LinkedIn URL, person ID, or name and company domain.

The Reveal Email endpoint discloses the email address of a contact found within Clodura's database. You supply one of three identifier combinations — a `personId`, a LinkedIn profile URL, or a full name plus company domain — and the API queues an enrichment job that delivers the result to your `webhookUrl`. This asynchronous design lets Clodura run real-time catch-all and deliverability checks in the background, so you always receive the most accurate email status rather than a raw, unverified guess.

The response schema you receive depends on your Clodura plan:

* **Prospect & Prospect Pro plans** — receive the **Standard Webhook Response** with a single verified email address directly from the Clodura database.
* **Free Forever, Max, and PAYG plans** — receive the **Multi-Provider Enrichment Response**, which aggregates results from Clodura and integrated third-party providers (Prospeo, Hunter, RocketReach, Findymail, LeadMagic, and more) in a single call.

<Note>
  **Credit cost:** 1 unlock credit + 1 export credit when a verified email is found and shared. No credits are deducted when no email is found or for a guessed email on Prospect/Prospect Pro plans. On Free Forever, Max, and PAYG plans, **1–6 credits** are consumed even for guessed emails retrieved from third-party providers.
</Note>

<Warning>
  LinkedIn Sales Navigator URLs are not supported. Always supply standard `linkedin.com/in/` profile URLs.
</Warning>

## Endpoint

`POST /api/v1/search/people/email/match`

## Request

### Headers

| Header         | Value                |
| -------------- | -------------------- |
| `X-API-KEY`    | Your Clodura API key |
| `Content-Type` | `application/json`   |

### Body Parameters

You must supply **one** of the three identifier options below plus a `webhookUrl`.

<ParamField body="personId" type="string">
  Clodura's unique identifier for the person. Obtain this from the [Search Prospect](/api/people/search-people) endpoint. Use this for the highest-confidence match.
</ParamField>

<ParamField body="linkedinUrl" type="string">
  Standard LinkedIn profile URL (e.g., `https://www.linkedin.com/in/kapilkhangaonkar/`). Cannot be a Sales Navigator URL.
</ParamField>

<ParamField body="firstName" type="string">
  First name of the person. Must be combined with `lastName` and `companyDomain`.
</ParamField>

<ParamField body="lastName" type="string">
  Last name of the person. Must be combined with `firstName` and `companyDomain`.
</ParamField>

<ParamField body="companyDomain" type="string">
  Domain name of the person's employer (e.g., `clodura.ai`, `google.com`). Do not include `www.`, `@`, or any path component.
</ParamField>

<ParamField body="webhookUrl" type="string" required>
  The URL where Clodura posts the JSON result once email verification is complete. Required for all plans. Use a service like [webhook.site](https://webhook.site) for testing.
</ParamField>

<Tip>
  Supply as much identifying information as possible. The more context you provide, the higher the match confidence.
</Tip>

## Example Request

<CodeGroup>
  ```bash cURL — by LinkedIn URL theme={null}
  curl --request POST \
    --url https://api.clodura.ai/api/v1/search/people/email/match \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "linkedinUrl": "https://www.linkedin.com/in/kapilkhangaonkar/",
      "webhookUrl": "https://webhook.site/your-unique-id"
    }'
  ```

  ```bash cURL — by name and domain theme={null}
  curl --request POST \
    --url https://api.clodura.ai/api/v1/search/people/email/match \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "firstName": "Kapil",
      "lastName": "Khangaonkar",
      "companyDomain": "clodura.ai",
      "webhookUrl": "https://webhook.site/your-unique-id"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.clodura.ai/api/v1/search/people/email/match"

  headers = {
      "X-API-KEY": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  # Option 1: by personId
  payload = {
      "personId": "3597524184265130552",
      "webhookUrl": "https://webhook.site/your-unique-id"
  }

  # Option 2: by LinkedIn URL
  # payload = {
  #     "linkedinUrl": "https://www.linkedin.com/in/kapilkhangaonkar/",
  #     "webhookUrl": "https://webhook.site/your-unique-id"
  # }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

## Response

### Immediate API Response (200)

The API responds immediately with a `trackingId` you can use to poll for results.

<ResponseField name="trackingId" type="string">
  A unique identifier for this enrichment job. Use this with `GET /api/v1/search/people/track/{trackingId}` to poll for the result if your webhook does not receive the callback.
</ResponseField>

<ResponseField name="status" type="string">
  Confirmation message that the job has been queued (e.g., `"Callback will be triggered once processing is complete."`).
</ResponseField>

```json theme={null}
{
  "trackingId": "688a0c47e21f6bc2b089ee18",
  "status": "Callback will be triggered once processing is complete."
}
```

### Webhook Payload — Standard (Prospect & Prospect Pro Plans)

<ResponseField name="personId" type="string">
  Clodura's unique identifier for the matched contact.
</ResponseField>

<ResponseField name="firstName" type="string">
  The contact's first name.
</ResponseField>

<ResponseField name="lastName" type="string">
  The contact's last name.
</ResponseField>

<ResponseField name="email" type="object">
  <Expandable title="email fields">
    <ResponseField name="emailId" type="string">
      The email address found for this contact.
    </ResponseField>

    <ResponseField name="emailStatus" type="string">
      Verification status of the email: `verified`, `unverified`, or `not found`.
    </ResponseField>

    <ResponseField name="extrapolatedEmailConfidence" type="string">
      Confidence level when an email is pattern-generated: `High`, `Medium`, or `Low`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="companyDomain" type="string">
  The domain of the contact's employer used for matching.
</ResponseField>

```json theme={null}
{
  "personId": "2431397674847567872",
  "firstName": "Kapil",
  "lastName": "Khangaonkar",
  "email": {
    "emailId": "kapil@clodura.ai",
    "emailStatus": "verified",
    "extrapolatedEmailConfidence": "High"
  },
  "companyDomain": "clodura.ai"
}
```

### Webhook Payload — Multi-Provider (Free Forever, Max & PAYG Plans)

<ResponseField name="trackingId" type="string">
  The tracking ID for this job, matching the ID returned in the immediate API response.
</ResponseField>

<ResponseField name="people" type="array">
  <Expandable title="people array fields">
    <ResponseField name="personId" type="string">
      Clodura's unique identifier for the matched contact.
    </ResponseField>

    <ResponseField name="firstName" type="string">
      The contact's first name.
    </ResponseField>

    <ResponseField name="lastName" type="string">
      The contact's last name.
    </ResponseField>

    <ResponseField name="companyDomain" type="string">
      The domain of the contact's employer.
    </ResponseField>

    <ResponseField name="email" type="object">
      A breakdown of results keyed by provider name (e.g., `Clodura`, `Prospeo`, `Hunter`, `RocketReach`, `Findymail`, `LeadMagic`). Each provider object contains an `emailId` (string or null) and an `emailStatus` string.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="string">
  Final status of the enrichment job: `success`.
</ResponseField>

```json theme={null}
{
  "trackingId": "69c2563778ded0e4ebfc476c",
  "people": [
    {
      "personId": "3730992042440917382",
      "firstName": "Kapil",
      "lastName": "Khangaonkar",
      "companyDomain": "clodura.ai",
      "email": {
        "Clodura": { "emailId": null, "emailStatus": "not found" },
        "Prospeo": { "emailId": "kapil@clodura.ai", "emailStatus": "not verified" },
        "LeadMagic": { "emailId": "k.khangaonkar@clodura.ai", "emailStatus": "not verified" },
        "Findymail": { "emailId": "kapilk@clodura.ai", "emailStatus": "not verified" },
        "Hunter": { "emailId": null, "emailStatus": "Insufficient Credits" },
        "RocketReach": { "emailId": null, "emailStatus": "Insufficient Credits" }
      }
    }
  ],
  "status": "success"
}
```

### Provider Status Definitions

| Status                  | Description                                                                     |
| ----------------------- | ------------------------------------------------------------------------------- |
| `not found`             | The provider could not find an email for this contact.                          |
| `not verified`          | An email was found but deliverability could not be confirmed.                   |
| `Insufficient Credits`  | Your Clodura credits are exhausted; no further provider calls can be made.      |
| `Success / Deliverable` | The email is valid, verified, and ready for outreach.                           |
| `guessed`               | The email was pattern-predicted from the company domain and naming conventions. |

## Error Codes

| Status | Meaning                                                                  |
| ------ | ------------------------------------------------------------------------ |
| `400`  | Bad request — check your request body (e.g., domain count exceeds limit) |
| `401`  | Unauthorized — your API key is missing or invalid                        |
| `402`  | Payment required — credits exhausted; upgrade your plan or add credits   |
| `403`  | Forbidden — this endpoint requires a paid Clodura plan                   |
| `404`  | No match found — no email could be located for the given identifier      |
| `422`  | Unprocessable entity — invalid or incomplete request body                |
| `429`  | Rate limit exceeded — reduce request frequency or upgrade your plan      |