Enrichment API

Phone Enrichment

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

#Use case

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

#Endpoint

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

Send your API key in the x-api-key header. See Authentication.

This endpoint returns 202 Accepted. Create a webhook signing secret and supply a public HTTPS webhook_url before making your first request. See Async Polling for retrieving results.

#Pricing

See Credits & Pricing for credit costs and charging behavior.

#Errors

For error responses and retry guidance, see Handling 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.

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

#Response (202)

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

#Webhook events

phone_enrich.completed (hit):

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

phone_enrich.completed (miss):

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

phone_enrich.failed:

{
  "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:

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:

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:

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:

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.