> ## 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 Phone Number via API

> Unlock direct dial and mobile phone numbers for contacts in Clodura's database using a LinkedIn URL or person ID, with multi-provider fallback enrichment.

The Reveal Phone endpoint returns phone numbers for contacts in Clodura's database. You identify a person using their `personId` or LinkedIn profile URL, set `revealPhoneNumberViaPartners` to `true` to enable multi-provider enrichment, and provide a `webhookUrl` to receive the result once processing completes. Clodura handles all provider orchestration on your behalf — you do not need separate accounts or API keys with third-party data sources.

Just like the email endpoint, the response schema varies by your Clodura plan:

* **Prospect & Prospect Pro plans** — receive the **Standard Webhook Response** with phone numbers sourced directly from Clodura's database.
* **Free Forever, Max, and PAYG plans** — receive the **Multi-Provider Response**, aggregating results from Clodura, SignalHire, Enrichlayer, Wiza, LeadMagic, RocketReach, Findymail, and more.

<Note>
  **Credit cost (Prospect/Prospect Pro):** 1 phone credit + 1 export credit when a number is found and shared. No credits are deducted if no number is found.

  **Credit cost (Free Forever, Max, PAYG):** 10–20 credits when a phone number is successfully retrieved. The exact cost depends on which provider locates the number. No credits are charged if no number is found across all 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/phone/match`

## Request

### Headers

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

### Body Parameters

You must supply either `personId` or `linkedinUrl`.

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

<ParamField body="linkedinUrl" type="string">
  Standard LinkedIn profile URL for the person (e.g., `https://www.linkedin.com/in/kapilkhangaonkar/`). Sales Navigator URLs are not supported.
</ParamField>

<ParamField body="revealPhoneNumberViaPartners" type="boolean">
  When `true`, Clodura queries integrated partner providers for additional phone numbers if the primary database has no result. Requires `webhookUrl` to be set. Defaults to `false`.
</ParamField>

<ParamField body="webhookUrl" type="string" required>
  The URL where Clodura will POST the final JSON result once phone verification and partner enrichment complete. Required when `revealPhoneNumberViaPartners` is `true`.
</ParamField>

## Example Request

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

  ```bash cURL — by person ID theme={null}
  curl --request POST \
    --url https://api.clodura.ai/api/v1/search/people/phone/match \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "personId": "3730147541266727225",
      "revealPhoneNumberViaPartners": true,
      "webhookUrl": "https://webhook.site/your-unique-id"
    }'
  ```

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

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

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

  payload = {
      "linkedinUrl": "https://www.linkedin.com/in/brad-dickey-72b846a",
      "revealPhoneNumberViaPartners": True,
      "webhookUrl": "https://webhook.site/your-unique-id"
  }

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

## Response

### Immediate API Response (200)

<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 that the job has been queued for processing.
</ResponseField>

```json theme={null}
{
  "trackingId": "688a0c47e21f6bc2b089ee19",
  "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="phoneNumbers" type="array">
  <Expandable title="phoneNumbers array fields">
    <ResponseField name="raw_number" type="string">
      The phone number in raw format.
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of phone number: `mobile`, `direct`, or `office`.
    </ResponseField>

    <ResponseField name="source" type="string">
      The source that provided this number (e.g., `partner`, `clodura`).
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "personId": "2751275603503088159",
  "firstName": "Brad",
  "lastName": "Dickey",
  "phoneNumbers": [
    {
      "raw_number": "+11099773515",
      "type": "mobile",
      "source": "partner"
    }
  ]
}
```

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

<ResponseField name="trackingId" type="string">
  The tracking ID matching the one 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="phoneNumbers" type="object">
      Results keyed by provider name (e.g., `Clodura`, `SignalHire`, `Enrichlayer`, `Wiza`, `LeadMagic`, `RocketReach`, `Findymail`). Each provider object contains a `status` string, and a `mobile` array if numbers were found.
    </ResponseField>
  </Expandable>
</ResponseField>

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

```json theme={null}
{
  "trackingId": "69c25b4178ded0e4ebfc4772",
  "people": [
    {
      "personId": "3602687943191298570",
      "firstName": "Brad",
      "lastName": "Dickey",
      "phoneNumbers": {
        "Clodura": { "status": "notFound" },
        "SignalHire": { "status": "notFound" },
        "Enrichlayer": { "status": "notFound" },
        "Wiza": { "status": "notFound" },
        "LeadMagic": { "status": "notFound" },
        "RocketReach": { "status": "notFound" },
        "Findymail": {
          "mobile": ["+1439-570-0805"],
          "status": "found"
        }
      }
    }
  ],
  "status": "success"
}
```

### Provider Status Definitions

| Status                 | Description                                                                |
| ---------------------- | -------------------------------------------------------------------------- |
| `found`                | The provider retrieved one or more phone numbers for this contact.         |
| `notFound`             | The provider could not locate any phone data for this contact.             |
| `Insufficient Credits` | Your Clodura credits are exhausted; no further provider calls can be made. |

## Error Codes

| Status | Meaning                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------- |
| `400`  | Bad request — check request body for missing or invalid fields                                     |
| `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, or the request is missing required details |
| `404`  | No result found — no phone number could be located                                                 |
| `422`  | Unprocessable entity — invalid or incomplete request body                                          |
| `429`  | Rate limit exceeded — reduce request frequency or upgrade your plan                                |