# Phone Enrichment

## Use case

Find a person’s phone number from their professional identity.

## Endpoint

```http
POST https://api-public.clodo.ai/api/public/v1/enrich/phone/
```

Send your API key in the `x-api-key` header. See [Authentication](https://docs.clodo.ai/api-reference/authentication).

> This endpoint returns `202 Accepted`. Create a [webhook signing secret](https://docs.clodo.ai/guides/webhook-secrets) and supply a public HTTPS `webhook_url` before making your first request. See [Async Polling](https://docs.clodo.ai/guides/async-polling) for retrieving results.

## Pricing

See [Credits & Pricing](https://docs.clodo.ai/guides/credits-and-pricing) for credit costs and charging behavior.

## Errors

For error responses and retry guidance, see [Handling Errors](https://docs.clodo.ai/api-reference/errors).

`POST /api/public/v1/enrich/phone/` — async (returns `202 Accepted`). 50 credits on hit, 0 on miss.

Phone-number lookup. Typical completion time ranges from a few seconds to around a minute. Always returns 202 + webhook delivery for a uniform integration shape. Polling fallback at `GET /api/public/v1/enrich/phone/{job_id}/`.

## Request

Provide at least one of:

- `professional_url`
- `email`
- `first_name` + `last_name` + `company_name`
- `first_name` + `last_name` + `domain`


| Field | Type | Notes |
|---|---|---|
| `professional_url` | string | LinkedIn URL. |
| `email` | string | Person's professional email. |
| `first_name` | string | Required when not using `professional_url` or `email`. |
| `last_name` | string | Required when not using `professional_url` or `email`. |
| `company_name` | string | Pair with `first_name` + `last_name`. Mutually exclusive with `domain`. |
| `domain` | string | e.g. `acme.com`. Pair with `first_name` + `last_name`. Must contain a dot. |
| `webhook_url` | string | Required. HTTPS URL. Must resolve to a public IP. |

Pre-condition: an active webhook signing secret. See [Webhook Signing Secrets](https://docs.clodo.ai/guides/webhook-secrets).

`Idempotency-Key` header is supported. Same key returns the same job's current state.

## Response (202)

```json
{
  "id": "dj_a1b2c3d4...",
  "status": "pending",
  "created_at": "2026-05-01T12:00:00Z"
}
```

## Webhook events

`phone_enrich.completed` (hit):

```json
{
  "id": "dj_a1b2c3d4...",
  "event_type": "phone_enrich.completed",
  "phone": "+14155551234"
}
```

`phone_enrich.completed` (miss):

```json
{
  "id": "dj_a1b2c3d4...",
  "event_type": "phone_enrich.completed",
  "phone": null
}
```

`phone_enrich.failed`:

```json
{
  "id": "dj_a1b2c3d4...",
  "event_type": "phone_enrich.failed",
  "error": {"code": "error", "message": "Phone enrichment failed; please retry."}
}
```

| `error.code` | `error.message` |
|---|---|
| `invalid_input` | `Invalid phone-enrichment request.` |
| `error` | `Phone enrichment failed; please retry.` |

Branch on `phone === null` to detect miss, not on `event_type`. A miss is a clean completion.

`phone` is E.164 normalized.

## Billing

50 credits charged on hit. 0 on miss. 0 on error or invalid input.

## Examples

By LinkedIn URL:

```bash
curl -X POST https://api-public.clodo.ai/api/public/v1/enrich/phone/ \
  -H "x-api-key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "professional_url": "https://www.linkedin.com/in/patrickcollison/",
    "webhook_url": "https://yourapp.com/webhooks/clodo"
  }'
```

By email:

```bash
curl -X POST https://api-public.clodo.ai/api/public/v1/enrich/phone/ \
  -H "x-api-key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "patrick@stripe.com",
    "webhook_url": "https://yourapp.com/webhooks/clodo"
  }'
```

By name + company:

```bash
curl -X POST https://api-public.clodo.ai/api/public/v1/enrich/phone/ \
  -H "x-api-key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Patrick",
    "last_name": "Collison",
    "company_name": "Stripe",
    "webhook_url": "https://yourapp.com/webhooks/clodo"
  }'
```

By name + domain:

```bash
curl -X POST https://api-public.clodo.ai/api/public/v1/enrich/phone/ \
  -H "x-api-key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Patrick",
    "last_name": "Collison",
    "domain": "stripe.com",
    "webhook_url": "https://yourapp.com/webhooks/clodo"
  }'
```

## Rate limit

`POST /api/public/v1/enrich/phone/`:

| Limit | Value |
|---|---|
| Sustained rate | 15 requests / minute |
| Burst | 3 requests |

Polling `GET /api/public/v1/enrich/phone/{job_id}/`:

| Limit | Value |
|---|---|
| Sustained rate | 3,600 requests / minute |
| Burst | 100 requests |

Exceeding any returns `429`.

## See also

- [Webhook Signing Secrets](https://docs.clodo.ai/guides/webhook-secrets)
- [Webhook Signature Verification](https://docs.clodo.ai/guides/webhook-signing)
- [Async Polling](https://docs.clodo.ai/guides/async-polling)
- [Idempotency](https://docs.clodo.ai/guides/idempotency)