Quick start

1. Create an account

Create a Ploid account, then create an API key in Workspace settings → API keys. A secret is shown only once, so save it in your password manager or secret store.

export PLOID_API_KEY="ploid_live_..."

2. Research a person

curl https://api.ploid.com/v1/person \
  -H "Authorization: Bearer $PLOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": { "name": "Manny Hernandez", "company_domain": "ploid.com" }
  }'

The key needs the people:enrich scope. Identify the person with exactly one of person_id, linkedin_url, or name plus company_domain.

An eligible reviewed snapshot returns 200 immediately. Otherwise the API returns 202 with a durable run:

{
    "data": {
        "run_id": "...",
        "status": "queued",
        "poll_url": "/v1/person/runs/..."
    },
    "meta": {
        "request_id": "...",
        "usage": { "acu_used": 0, "billed": [], "free": [], "not_found": [] }
    }
}

3. Poll for the result

Poll GET /v1/person/runs/{id} until the run completes. Fresh research can take minutes, so keep the run ID rather than holding one HTTP request open. The completed record leads with a reviewed summary, deduplicated source_links, and field-level provenance. See Person for the full response, uncertain-identity outcomes, and pricing.

4. Choose the next surface

• Use POST /v1/search for a synchronous list of people.
• Use the enrichment APIs when you already know the identity and need selected profile, email, phone, or social fields.
• People Sets (preview) build durable, criteria-verified lists and are available to API keys with the people:search scope.

Next steps