Enrichment

Contact resolution

POST /v1/enrich

Requires people:enrich. Identify the person with exactly one of linkedin_url, person_id, email (reverse lookup), or name plus company_domain.

curl https://api.ploid.com/v1/enrich \
  -H "Authorization: Bearer $PLOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_url": "https://www.linkedin.com/in/example",
    "fields": ["work_email", "personal_email", "phone"]
  }'

Every requested field is returned, even when it is not found:

{
    "data": {
        "work_email": {
            "value": "example@company.com",
            "status": "found",
            "confidence": "verified",
            "source": "fullenrich",
            "last_seen": "2026-08-31T00:00:00.000Z"
        },
        "phone": {
            "value": null,
            "status": "not_found",
            "confidence": null,
            "source": null,
            "last_seen": null
        }
    },
    "meta": {
        "usage": {
            "billed": ["work_email"],
            "free": [],
            "not_found": ["phone"]
        }
    }
}

status is unavailable for a provider or transport failure, so it is never silently reported as a clean miss. Only successful reveals are billed.

The legacy enrichments lightweight LinkedIn/contact contract remains supported for existing clients. Deep public evidence lives only at /v1/person, which provides durable runs and 90-day organization-wide rereads.

Partial success

One field can fail without failing the whole person. Unresolved fields return null, and transport or provider failures appear in meta.warnings. Clean not-found fields and failed fields are not charged.

If every requested field fails, the API returns 503 upstream_unavailable with error.retryable: true, error.unavailable_fields, and Retry-After: 1. No fields are billed. A completed lookup that finds no contact remains a 200 response. These rules also apply to the legacy enrichments contract.

Errors and limits

Requested fields run concurrently. Provider lookups have an 80-second deadline; if they exceed it, the API returns 503 upstream_timeout with retryable: true instead of waiting for a gateway timeout. That attempt does not charge enrichment credits. Retry the request using the same Idempotency-Key when one was supplied.

Focused enrichment uses the organization and API-key per-minute buckets; it has no additional route cap. Partial provider failures remain in meta.warnings; complete provider failure returns a retryable 503. You can retry with the same Idempotency-Key after Retry-After. See Errors & rate limits.